// Module included in the following assemblies:
//
// * authentication/identity_providers/configuring-github-identity-provider.adoc

[id="identity-provider-github-CR_{context}"]
= Sample GitHub CR

The following custom resource (CR) shows the parameters and acceptable values for a
GitHub identity provider.

.GitHub CR

[source,yaml]
----
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: githubidp <1>
    mappingMethod: claim <2>
    type: GitHub
    github:
      ca: <3>
        name: ca-config-map
      clientID: {...} <4>
      clientSecret: <5>
        name: github-secret
      hostname: ... <6>
      organizations: <7>
      - myorganization1
      - myorganization2
      teams: <8>
      - myorganization1/team-a
      - myorganization2/team-b
----
<1> This provider name is prefixed to the GitHub numeric user ID to form an
identity name. It is also used to build the callback URL.
<2> Controls how mappings are established between this provider's identities and `User` objects.
<3> Optional: Reference to an {product-title} `ConfigMap` object containing the
PEM-encoded certificate authority bundle to use in validating server
certificates for the configured URL. Only for use in GitHub Enterprise
with a non-publicly trusted root certificate.
<4> The client ID of a
link:https://github.com/settings/applications/new[registered GitHub OAuth
application]. The application must be configured with a callback URL of
`\https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name>`.
<5> Reference to an {product-title} `Secret` object containing the client secret
issued by GitHub.
<6> For GitHub Enterprise, you must provide the hostname of your instance, such as
`example.com`. This value must match the GitHub Enterprise `hostname` value in
in the `/setup/settings` file and cannot include a port number. If this
value is not set, then either `teams` or `organizations` must be defined.
For GitHub, omit this parameter.
<7> The list of organizations. Either the `organizations` or `teams` field must be set unless the `hostname` field is set, or if `mappingMethod` is set to `lookup`. Cannot be used in combination with the `teams` field.
<8> The list of teams. Either the `teams` or `organizations` field must be set unless the `hostname` field is set, or if `mappingMethod` is set to `lookup`. Cannot be used in combination with the `organizations` field.

[NOTE]
====
If `organizations` or `teams` is specified, only GitHub users that are members of
at least one of the listed organizations will be allowed to log in. If the GitHub OAuth
application configured in `clientID` is not owned by the organization, an organization
owner must grant third-party access to use this option. This can be done during
the first GitHub login by the organization's administrator, or from the GitHub organization settings.
====