From bed2d2dd624aad74ab44ee5a7c1bf3adbeb60ca9 Mon Sep 17 00:00:00 2001
From: Margo Crawford <margaretc@vmware.com>
Date: Wed, 28 Apr 2021 13:34:36 -0700
Subject: [PATCH] Incorporated PR feedback

---
 .../howto/configure-supervisor-with-gitlab.md | 27 ++++++++++++-------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/site/content/docs/howto/configure-supervisor-with-gitlab.md b/site/content/docs/howto/configure-supervisor-with-gitlab.md
index b143fc4f..bf928b17 100644
--- a/site/content/docs/howto/configure-supervisor-with-gitlab.md
+++ b/site/content/docs/howto/configure-supervisor-with-gitlab.md
@@ -11,7 +11,7 @@ menu:
 ---
 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
+This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
 cluster using their Gitlab credentials.
 ## Prerequisites
 
@@ -30,6 +30,7 @@ described [here](https://pinniped.dev/docs/howto/configure-supervisor/).
 
 ## 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
@@ -38,10 +39,10 @@ metadata:
 spec:
   # The upstream issuer name.
   # This should be something like https://gitlab.com or https://gitlab.your-company-name.example.com.
-  issuer: "<gitlab-url>"
-  # Optionally specify the CA bundle for the GitLab server as base64 encoded PEM data.
-  tls:
-    certificateAuthorityData: "<gitlab-ca-bundle>"
+  issuer: "https://gitlab.com"
+  # If needed, specify the CA bundle for the GitLab server as base64 encoded PEM data.
+  #tls:
+  #  certificateAuthorityData: "<gitlab-ca-bundle>"
   authorizationConfig:
     # Any scopes other than "openid" that you selected when creating your GitLab application.
     additionalScopes: [ email, profile ]
@@ -50,11 +51,12 @@ spec:
     # 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: "<username-claim>"
-    # The name of the claim in your GitLab token that represents the groups that the user belongs to.
+    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.
+    # The name of the kubernetes secret that contains your GitLab application's client ID and client secret.
     secretName: my-oidc-provider-client-secret
 ```
 
@@ -65,13 +67,20 @@ kind: Secret
 metadata:
   name: my-oidc-provider-client-secret
 stringData:
-   # clientID should be the Application ID that you got from GitLab.
+  # 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"
 ```
 
+To validate your configuration, run
+```shell
+kubectl describe OIDCIdentityProvider my-oidc-identity-provider
+```
+
+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,