diff --git a/site/content/docs/howto/configure-supervisor-with-gitlab.md b/site/content/docs/howto/configure-supervisor-with-gitlab.md index bf928b17..e81d9e59 100644 --- a/site/content/docs/howto/configure-supervisor-with-gitlab.md +++ b/site/content/docs/howto/configure-supervisor-with-gitlab.md @@ -1,92 +1,140 @@ --- -title: Configure the Pinniped Supervisor to use Gitlab as an OIDC Provider -description: Set up the Pinniped Supervisor to use Gitlab login. +title: Configure the Pinniped Supervisor to use GitLab as an OIDC Provider +description: Set up the Pinniped Supervisor to use GitLab login. cascade: layout: docs menu: docs: - name: Configure Supervisor With Gitlab + name: Configure Supervisor With GitLab weight: 35 parent: howtos --- The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single "upstream" OIDC identity provider to many "downstream" cluster clients. This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes -cluster using their Gitlab credentials. +cluster using their GitLab credentials. + ## Prerequisites -This how-to guide assumes that you have already installed the Pinniped Supervisor with working ingress, -and that you have configured a `FederationDomain` to issue tokens for your downstream clusters, as -described [here](https://pinniped.dev/docs/howto/configure-supervisor/). +This how-to guide assumes that you have already [installed the Pinniped Supervisor]({{< ref "install-supervisor" >}}) with working ingress, +and that you have [configured a `FederationDomain` to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}). -## Configuring your Gitlab Application -1. In Gitlab, navigate to User Settings > Applications +## Configure your GitLab Application + +Follow the instructions for [using GitLab as an OAuth2 authentication service provider](https://docs.gitlab.com/ee/integration/oauth_provider.html) and create a user, group, or instance-wide application. + +For example, to create a user-owned application: + +1. In GitLab, navigate to [_User Settings_ > _Applications_](https://gitlab.com/-/profile/applications) 1. Create a new application: - 1. Enter the name of your application. - 1. Enter the redirect URI. This is the `issuer` you configured in your `FederationDomain` appended with `/callback`. - 1. Check the box saying that the application is Confidential. - 1. Select scope `openid`. Optionally select `profile` and `email`. - 1. Save the application and make note of the Application ID and Secret. + 1. Enter a name for your application, such as "My Kubernetes Clusters". + 1. Enter the redirect URI. This is the `spec.issuer` you configured in your `FederationDomain` appended with `/callback`. + 1. Check the box saying that the application is _Confidential_. + 1. Select scope `openid`. This provides access to the `nickname` (GitLab username) and `groups` (GitLab groups) claims. + 1. Save the application and make note of the _Application ID_ and _Secret_. + +## Configure the Supervisor cluster + +Create an [OIDCIdentityProvider](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#oidcidentityprovider) in the same namespace as the Supervisor. + +For example, this OIDCIdentityProvider and corresponding Secret for [gitlab.com](https://gitlab.com) use the `nickname` claim (GitLab username) as the Kubernetes username: -## Configuring the Supervisor cluster -Create an [`OIDCIdentityProvider`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#oidcidentityprovider) in the same namespace as the Supervisor. -For example, here is an `OIDCIdentityProvider` that works against https://gitlab.com, and uses the email claim as the username. ```yaml apiVersion: idp.supervisor.pinniped.dev/v1alpha1 kind: OIDCIdentityProvider metadata: - name: my-oidc-provider + namespace: pinniped-supervisor + name: gitlab spec: - # The upstream issuer name. - # This should be something like https://gitlab.com or https://gitlab.your-company-name.example.com. - issuer: "https://gitlab.com" - # If needed, specify the CA bundle for the GitLab server as base64 encoded PEM data. - #tls: - # certificateAuthorityData: "" - authorizationConfig: - # Any scopes other than "openid" that you selected when creating your GitLab application. - additionalScopes: [ email, profile ] - # See here for a list of available claims: https://docs.gitlab.com/ee/integration/openid_connect_provider.html#shared-information - claims: - # The name of the claim in your GitLab token that will be mapped to the "username" claim in downstream - # tokens minted by the Supervisor. - # For example, "email" or "sub". - username: "email" - # The name of the claim in GitLab that represents the groups that the user belongs to. - # Note that GitLab's "groups" claim comes from their /userinfo endpoint, not the token. - groups: "groups" - client: - # The name of the kubernetes secret that contains your GitLab application's client ID and client secret. - secretName: my-oidc-provider-client-secret -``` -Then, create a `Secret` containing the Client ID and Client Secret in the same namespace as the Supervisor. -```yaml + # Specify the upstream issuer URL. + issuer: https://gitlab.com + + # Specify how GitLab claims are mapped to Kubernetes identities. + claims: + + # Specify the name of the claim in your GitLab token that will be mapped + # to the "username" claim in downstream tokens minted by the Supervisor. + username: nickname + + # Specify the name of the claim in GitLab that represents the groups + # that the user belongs to. Note that GitLab's "groups" claim comes from + # their "/userinfo" endpoint, not the token. + groups: groups + + # Specify the name of the Kubernetes Secret that contains your GitLab + # application's client credentials (created below). + client: + secretName: gitlab-client-credentials +--- apiVersion: v1 kind: Secret metadata: - name: my-oidc-provider-client-secret + namespace: pinniped-supervisor + name: gitlab-client-credentials +type: secrets.pinniped.dev/oidc-client stringData: - # clientID should be the Application ID that you got from GitLab. - clientID: xxx - # clientSecret should be the Secret that you got from GitLab. - clientSecret: yyy -type: "secrets.pinniped.dev/oidc-client" + + # The "Application ID" that you got from GitLab. + clientID: "" + + # The "Secret" that you got from GitLab. + clientSecret: "" ``` -To validate your configuration, run +Once your OIDCIdentityProvider has been created, you can validate your configuration by running: + ```shell -kubectl describe OIDCIdentityProvider my-oidc-identity-provider +kubectl describe OIDCIdentityProvider -n pinniped-supervisor gitlab ``` Look at the `status` field. If it was configured correctly, you should see `phase: Ready`. +### (Optional) Use a different GitLab claim for Kubernetes usernames + +You can also use other GitLab claims as the username. +To do this, make sure you have configured the appropriate scopes on your GitLab application, such as `email`. + +You must also adjust the `spec.authorizationConfig` to request those scopes at login and adjust `spec.claims` to use those claims in Kubernetes, for example: + +```yaml +# [...] +spec: + # Request any scopes other than "openid" that you selected when + # creating your GitLab application. The "openid" scope is always + # included. + # + # See here for a full list of available claims: + # https://docs.gitlab.com/ee/integration/openid_connect_provider.html + authorizationConfig: + additionalScopes: [ email ] + claims: + username: email + groups: groups +# [...] +``` + +### (Optional) Use a private GitLab instance + +To use privately hosted instance of GitLab, you can change the `spec.issuer` and `spec.tls.certificateAuthorityData` fields, for example: + +```yaml +apiVersion: idp.supervisor.pinniped.dev/v1alpha1 +kind: OIDCIdentityProvider +# [...] +spec: + # Specify your GitLab instance URL. + issuer: https://gitlab.your-company.example.com. + + # Specify the CA bundle for the GitLab server as base64-encoded PEM + # data. For example, the output of `cat my-ca-bundle.pem | base64`. + # + # This is only necessary if your instance uses a custom CA. + tls: + certificateAuthorityData: "" +# [...] +``` + ## Next Steps -Now that you have configured the Supervisor to use GitLab, -you may want to check out [Configure Concierge JWT Authentication](https://pinniped.dev/docs/howto/configure-concierge-jwt/) -to learn how to configure the Concierge to use the JWTs that the Supervisor now issues. - - - - +Now that you have configured the Supervisor to use GitLab, you may want to [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-jwt" >}}).