MAS DevOps Ansible Collection Ansible CLI
Home Roles: OCP Mgmt ocp_github_oauth Role Variables Example Playbook License

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 ibmgithub as 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¤

oauth.github_client_secret_value¤

GitHub OAuth application client secret.

  • Required
  • Environment Variable: None (passed as variable)
  • Default: None

Purpose: Provides the client secret from the GitHub OAuth application configuration for secure authentication.

When to use: Always required. Obtained from GitHub OAuth app settings.

Valid values: Valid GitHub OAuth client secret string (generated by GitHub).

Impact: Used to authenticate the OpenShift cluster with GitHub. Incorrect secret will prevent GitHub authentication.

Related variables: oauth.github_client_id_value, oauth.github_hostname

Notes: - Obtain from GitHub OAuth app settings in your organization - Keep secret secure, never commit to version control - Stored as Kubernetes secret in the cluster - Regenerate if compromised

oauth.github_client_id_value¤

GitHub OAuth application client ID.

  • Required
  • Environment Variable: None (passed as variable)
  • Default: None

Purpose: Provides the client ID from the GitHub OAuth application configuration.

When to use: Always required. Obtained from GitHub OAuth app settings.

Valid values: Valid GitHub OAuth client ID string (generated by GitHub).

Impact: Identifies the OAuth application to GitHub during authentication flow.

Related variables: oauth.github_client_secret_value, oauth.github_hostname

Notes: - Obtain from GitHub OAuth app settings in your organization - Public value, but should still be managed securely - Must match the OAuth app configured with ibmgithub as the OAuth ID

oauth.github_hostname¤

GitHub server hostname for authentication.

  • Optional
  • Environment Variable: None (passed as variable)
  • Default: github.com (public GitHub)

Purpose: Specifies the GitHub server to use for authentication, supporting both public GitHub and GitHub Enterprise.

When to use: Set to your GitHub Enterprise hostname if using enterprise GitHub. Leave default for public GitHub.

Valid values: - github.com - Public GitHub (default) - github.ibm.com - IBM GitHub Enterprise - Custom GitHub Enterprise hostname (e.g., github.example.com)

Impact: Determines which GitHub server handles authentication requests.

Related variables: oauth.github_client_id_value, oauth.github_client_secret_value

Notes: - Default github.com is for public GitHub - Use your enterprise hostname for GitHub Enterprise - Hostname must be accessible from the OpenShift cluster - Verify SSL certificates are properly configured

oauth.organizations¤

List of GitHub organizations for authentication.

  • Required
  • Environment Variable: None (passed as variable)
  • Default: None

Purpose: Defines which GitHub organizations are allowed to authenticate to the OpenShift cluster.

When to use: Always required. Specify one or more GitHub organizations whose members can access the cluster.

Valid values: List of valid GitHub organization names (e.g., ['ibm', 'redhat'], ['myorg']).

Impact: Only users who are members of the specified organizations can authenticate to the cluster.

Related variables: oauth.groups

Notes: - Users must be members of at least one listed organization - Organization membership is verified during each login - Multiple organizations can be specified for broader access - Organization names are case-sensitive

oauth.groups¤

List of OpenShift groups to create with GitHub user mappings.

  • Optional
  • Environment Variable: None (passed as variable)
  • Default: None

Purpose: Defines OpenShift groups to be created, their GitHub user members, and associated cluster role bindings.

When to use: Use to map GitHub users to OpenShift groups and assign cluster permissions.

Valid values: List of group objects, each containing: - name: OpenShift group name - users: List of GitHub usernames to add to the group - groups_cluster_rolebindings: List of cluster roles to bind to the group

Impact: Creates OpenShift groups and assigns cluster roles, controlling user permissions in the cluster.

Related variables: oauth.organizations

Notes: - Groups enable role-based access control (RBAC) - Users must be members of specified organizations - Common cluster roles: cluster-admin, admin, edit, view - Groups are created if they don't exist

oauth.groups.name¤

Name of the OpenShift group to create.

  • Required (when defining groups)
  • Environment Variable: None (passed as variable)
  • Default: None

Purpose: Specifies the name of the OpenShift group for organizing users and assigning permissions.

When to use: Required for each group definition in the oauth.groups list.

Valid values: Valid Kubernetes group name (alphanumeric with hyphens, e.g., mas-admins, developers, viewers).

Impact: Group name is used in role bindings and for user organization.

Related variables: oauth.groups.users, oauth.groups.groups_cluster_rolebindings

Notes: - 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.

  • Required (when defining groups)
  • Environment Variable: None (passed as variable)
  • Default: None

Purpose: Specifies which GitHub users should be members of the OpenShift group.

When to use: Required for each group definition. List all GitHub usernames that should have the group's permissions.

Valid values: List of valid GitHub usernames (e.g., ['user1', 'user2', 'user3']).

Impact: Listed users will be added to the group and inherit all associated cluster role bindings.

Related variables: oauth.groups.name, oauth.organizations

Notes: - Users must be members of the specified GitHub organizations - GitHub usernames are case-sensitive - Users are added to groups upon first login - Update list to add or remove user access

oauth.groups.groups_cluster_rolebindings¤

List of cluster roles to bind to the group.

  • Required (when defining groups)
  • Environment Variable: None (passed as variable)
  • Default: None

Purpose: Defines which cluster-level permissions the group members will have.

When to use: Required for each group definition. Specify the cluster roles that match the group's intended access level.

Valid values: List of valid OpenShift cluster role names. Common values: - cluster-admin - Full cluster administration - admin - Full access to project resources - edit - Modify project resources - view - Read-only access to project resources - Custom cluster roles

Impact: Group members will have all permissions defined by the specified cluster roles.

Related variables: oauth.groups.name, oauth.groups.users

Notes: - Warning: cluster-admin grants full cluster control - Use least privilege principle when assigning roles - Multiple roles can be assigned to a single group - Verify roles exist: oc get clusterroles

Example Playbook¤

- hosts: localhost
  vars:
    # Add required variables here
  roles:
    - ibm.mas_devops.ocp_github_oauth

License¤

EPL-2.0