From 3e13b5f39d88b813dadd8dd2b153e471ad73e994 Mon Sep 17 00:00:00 2001 From: Matt Moyer Date: Tue, 4 May 2021 14:13:20 -0500 Subject: [PATCH] Do some minor copyediting on "configure-supervisor-with-gitlab.md". Some minor edits I came across while reviewing this: - Capitalize "GitLab" the way they do. - Use `{{< ref "xyz" >}}` references when linking internally. The advantage of these is that they're "type checked" by Hugo when the site is rendered, so we'll know if we ever break one. - Add links to the GitLab docs about creating an OAuth client. These also cover adding a group-level or instance-wide application. - Re-wrap the YAML lines to fit a bit more naturally. - Add a `namespace` to the YAML examples, so they're more likely to work without tweaks. - Use "gitlab" instead of "my-oidc-identity-provider" as the example name, for clarity. - Re-word a few small bits. These are 100% subjective but hopefully an improvement? Signed-off-by: Matt Moyer --- .../howto/configure-supervisor-with-gitlab.md | 114 +++++++++++------- 1 file changed, 68 insertions(+), 46 deletions(-) diff --git a/site/content/docs/howto/configure-supervisor-with-gitlab.md b/site/content/docs/howto/configure-supervisor-with-gitlab.md index bf928b17..8b9a5427 100644 --- a/site/content/docs/howto/configure-supervisor-with-gitlab.md +++ b/site/content/docs/howto/configure-supervisor-with-gitlab.md @@ -1,92 +1,114 @@ --- -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 +## Configuring 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. 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. Save the application and make note of the Application ID and Secret. + 1. Save the application and make note of the _Application ID_ and _Secret_. ## 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. + +For example, here is an `OIDCIdentityProvider` that works against [gitlab.com](https://gitlab.com) and uses the GitLab `email` claim as the Kubernetes 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: "" + + # Specify the upstream issuer name. This should be something like + # https://gitlab.com or https://gitlab.your-company.example.com. + 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: - # 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 + + # Specify how GitLab claims are mapped to Kubernetes identities. 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. + + # 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". - 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" + # + # See here for a full list of available claims: + # https://docs.gitlab.com/ee/integration/openid_connect_provider.html + username: email + + # 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: - # The name of the kubernetes secret that contains your GitLab application's client ID and client secret. - secretName: my-oidc-provider-client-secret + secretName: gitlab-client-credentials ``` -Then, create a `Secret` containing the Client ID and Client Secret in the same namespace as the Supervisor. +Then, create a `Secret` containing the Client ID and Client Secret in the same namespace as the Supervisor: + ```yaml 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 +To validate your configuration, run: + ```shell -kubectl describe OIDCIdentityProvider my-oidc-identity-provider +kubectl describe OIDCIdentityProvider gitlab ``` Look at the `status` field. If it was configured correctly, you should see `phase: Ready`. ## 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" >}}).