ocp_github_oauth¤
Configure OpenShift cluster authentication using GitHub OAuth. This role enables users to log into OpenShift using their GitHub credentials, with support for both public GitHub and GitHub Enterprise. It also manages user groups and cluster role bindings based on GitHub organization membership.
Prerequisites:
- GitHub OAuth application must be configured in your GitHub organization before using this role
- OAuth application must use
ibmgithubas the OAuth ID - Requires GitHub organization admin permissions
The role creates OAuth configuration, manages user groups, and assigns cluster roles based on GitHub organization membership.
Role Variables¤
| Variable | Required | Default |
|---|---|---|
oauth.github_client_secret_value |
Yes | None |
oauth.github_client_id_value |
Yes | None |
oauth.github_hostname |
No | github.com |
oauth.organizations |
Yes | None |
oauth.groups |
No | None |
oauth.groups.name |
Conditional | None |
oauth.groups.users |
Conditional | None |
oauth.groups.groups_cluster_rolebindings |
Conditional | None |
The oauth.groups.* variables are only required when defining entries in the oauth.groups list.
OAuth Configuration¤
oauth.github_client_secret_value¤
GitHub OAuth application client secret, generated by GitHub and obtained from your GitHub OAuth app settings.
- Required
- Environment Variable: None (passed as variable)
- Default: None
Used to authenticate the OpenShift cluster with GitHub; an incorrect secret will prevent GitHub authentication. The secret is stored as a Kubernetes secret in the cluster — keep it secure, never commit it to version control, and regenerate it if compromised.
oauth.github_client_id_value¤
GitHub OAuth application client ID, generated by GitHub and obtained from your GitHub OAuth app settings.
- Required
- Environment Variable: None (passed as variable)
- Default: None
Identifies the OAuth application to GitHub during the authentication flow. It is a public value, but should still be managed securely, and must match the OAuth app configured with ibmgithub as the OAuth ID.
oauth.github_hostname¤
GitHub server hostname for authentication — github.com for public GitHub (default), github.ibm.com for IBM GitHub Enterprise, or a custom GitHub Enterprise hostname (e.g., github.example.com).
- Optional
- Environment Variable: None (passed as variable)
- Default:
github.com(public GitHub)
Determines which GitHub server handles authentication requests. The hostname must be accessible from the OpenShift cluster and have properly configured SSL certificates.
oauth.organizations¤
List of GitHub organizations allowed to authenticate to the OpenShift cluster — for example ['ibm', 'redhat'] or ['myorg'].
- Required
- Environment Variable: None (passed as variable)
- Default: None
Only users who are members of at least one listed organization can authenticate to the cluster; membership is verified during each login. Organization names are case-sensitive, and multiple organizations can be specified for broader access.
Group Mappings¤
oauth.groups¤
List of OpenShift groups to create, each mapping GitHub users to cluster role bindings.
- Optional
- Environment Variable: None (passed as variable)
- Default: None
Each entry is an object with name (OpenShift group name), users (list of GitHub usernames), and groups_cluster_rolebindings (list of cluster roles to bind to the group). Groups are created if they don't exist, enabling role-based access control (RBAC); users must be members of the specified organizations.
oauth.groups.name¤
Name of the OpenShift group to create — a valid Kubernetes group name (alphanumeric with hyphens, e.g., mas-admins, developers, or viewers).
- Required when defining groups
- Environment Variable: None (passed as variable)
- Default: None
Required for each group definition in the oauth.groups list. Use descriptive names that reflect the group's purpose (common patterns: <project>-admins, <team>-developers); group names must be unique within the cluster.
oauth.groups.users¤
List of GitHub usernames to add to the group — for example ['user1', 'user2', 'user3'].
- Required when defining groups
- Environment Variable: None (passed as variable)
- Default: None
Listed users are added to the group upon first login and inherit all associated cluster role bindings. GitHub usernames are case-sensitive, users must be members of the specified GitHub organizations, and the list can be updated to add or remove user access.
oauth.groups.groups_cluster_rolebindings¤
List of cluster roles to bind to the group — common values are cluster-admin (full cluster administration), admin (full access to project resources), edit (modify project resources), view (read-only access), or custom cluster roles.
- Required when defining groups
- Environment Variable: None (passed as variable)
- Default: None
Group members receive all permissions defined by the specified cluster roles; multiple roles can be assigned to a single group. Verify that roles exist with oc get clusterroles, and use the least privilege principle when assigning them.
Warning
cluster-admin grants full cluster control — assign it sparingly.
Example Playbook¤
- hosts: localhost
vars:
# Add required variables here
roles:
- ibm.mas_devops.ocp_github_oauth
License¤
EPL-2.0