diff --git a/site/content/docs/howto/configure-supervisor-with-gitlab.md b/site/content/docs/howto/configure-supervisor-with-gitlab.md index 8b9a5427..d958f9aa 100644 --- a/site/content/docs/howto/configure-supervisor-with-gitlab.md +++ b/site/content/docs/howto/configure-supervisor-with-gitlab.md @@ -19,7 +19,7 @@ cluster using their GitLab credentials. 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 +## 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. @@ -27,17 +27,17 @@ 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 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`. Optionally select `profile` and `email`. + 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_. -## Configuring the Supervisor cluster +## 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. +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 [gitlab.com](https://gitlab.com) and uses the GitLab `email` claim as the Kubernetes username: +For example, this OIDCIdentityProvider and corresponding Secret for [gitlab.com](https://gitlab.com) use the `nickname` claim (GitLab username) as the Kubernetes username: ```yaml apiVersion: idp.supervisor.pinniped.dev/v1alpha1 @@ -47,30 +47,15 @@ metadata: name: gitlab spec: - # Specify the upstream issuer name. This should be something like - # https://gitlab.com or https://gitlab.your-company.example.com. + # Specify the upstream issuer URL. issuer: https://gitlab.com - # Specify the CA bundle for the GitLab server as base64-encoded PEM - # data. This will only be needed for self-managed GitLab. - # tls: - # certificateAuthorityData: "" - - # Request any scopes other than "openid" that you selected when - # creating your GitLab application. - authorizationConfig: - additionalScopes: [ email, profile ] - # 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. - # For example, "email" or "sub". - # - # See here for a full list of available claims: - # https://docs.gitlab.com/ee/integration/openid_connect_provider.html - username: email + 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 @@ -81,11 +66,7 @@ spec: # application's client credentials (created below). client: secretName: gitlab-client-credentials -``` - -Then, create a `Secret` containing the Client ID and Client Secret in the same namespace as the Supervisor: - -```yaml +--- apiVersion: v1 kind: Secret metadata: @@ -101,14 +82,60 @@ stringData: clientSecret: "" ``` -To validate your configuration, run: +Once your OIDCIdentityProvider has been created, you can validate your configuration by running: ```shell -kubectl describe OIDCIdentityProvider gitlab +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. This will only be needed for self-managed GitLab. For example, + # the output of `cat my-ca-bundle.pem | base64`. + # + # This configuration 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 [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-jwt" >}}).