Merge pull request #1654 from vmware-tanzu/docs/configure-supervisor-…

…with-azuread

Add docs for Supervisor with Azure AD

site/content/docs/howto/concierge/configure-concierge-supervisor-jwt.md

@@ -5,7 +5,7 @@ cascade:
   layout: docs
 menu:
   docs:
-    name: JWT Authentication with Supervisor
+    name: With Supervisor
     weight: 40
     parent: howto-configure-concierge
 aliases:

site/content/docs/howto/supervisor/configure-supervisor-with-azuread.md

@@ -0,0 +1,145 @@
+---
+title: Configure the Pinniped Supervisor to use Azure Active Directory as an OIDC provider
+description: Set up the Pinniped Supervisor to use Azure Active Directory login.
+cascade:
+  layout: docs
+menu:
+  docs:
+    name: With Azure AD
+    weight: 80
+    parent: howto-configure-supervisor
+---
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
+"upstream" 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 Azure Active Directory credentials.
+
+## Prerequisites
+
+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" >}}).
+
+## Create an Azure AD Application
+
+If you don't already have an Azure subscription, [create a free account](https://azure.microsoft.com/en-us/free/).
+Next, [create a new tenant](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/create-new-tenant) in
+Azure Active Directory.  This tenant represents your organization.
+
+For example, to create a tenant:
+
+1. In the [Azure portal](portal.azure.com), navigate to _Home_ > _Azure Active Directory_.
+1. Create a new tenant:
+   1. Click `Manage Tenants`.
+   1. Click `Create`.
+   1. Fill out your organization details.
+1. Optionally, just use the `Default Directory` that is already created.
+1. Users can be added to the directory via the  `Manage` > `Users` link.
+1. Create a new app:
+   1. Click `App Registrations`.
+   1. Click `New Registration`.
+   1. Enter a `user-facing display name`.
+   1. Choose supported account types.
+   1.  Enter the `Redirect URI`. Choose `Web` from the dropdown menu. The redirect uri will be the `spec.issuer` you 
+       configured in your `FederationDomain` appended with `/callback`.  
+   1. Click `Register`.
+
+## Configure the Supervisor 
+
+Create an [OIDCIdentityProvider](https://github.com/vmware-tanzu/pinniped/blob/main/generated/{{< latestcodegenversion >}}/README.adoc#oidcidentityprovider) 
+in the same namespace as the Supervisor.
+
+1. In the [Azure portal](portal.azure.com), navigate to _Home_ > _Azure Active Directory_ > _App Registrations_.
+   1. Copy the `Application (client) ID)` for use in your OIDCIdentityProvider CR later.
+1. Select your application, and then click `Add a certificate or secret`.
+   1. Click `New client secret`, provide a name, an expiration time, and click `create`.
+   1. Copy the secret `Value` for use later with your `OIDCIdentityProvider`. 
+1. Select your application, and then click `Endpoints`.
+   1. Under `Endpoints`, find the `OpenID Connect Metadata Document` URL.
+   1. Perform a curl with this URL and find the issuer value (`curl https://<openid.connect.metadata.document.url> | jq ".issuer"`).
+   1. Copy the `issuer` value to use in your `OIDCIdentityProvider`.
+
+
+For example, this OIDCIdentityProvider and corresponding Secret use Azure AD's `email` claim as the Kubernetes username:
+
+
+```yaml
+apiVersion: idp.supervisor.pinniped.dev/v1alpha1
+kind: OIDCIdentityProvider
+metadata:
+  namespace: pinniped-supervisor
+  name: azuread
+spec:
+
+  # Specify the upstream issuer URL (no trailing slash). Change this to be the
+  # actual issuer provided by your Azure AD account. This is most easily found 
+  # by checking the Endpoints for your application and performing a curl against
+  # the OpenID Connect metadata document URL.
+  issuer: <issuer.from.OpenID.connect.metadata.document>
+
+  # Specify how to form authorization requests to your Azure AD application.
+  authorizationConfig:
+
+    # Request any scopes other than "openid" for claims besides
+    # the default claims in your token. The "openid" scope is always
+    # included.
+    #
+    # To learn more about how to customize the claims returned, see here:
+    # https://learn.microsoft.com/en-us/azure/active-directory/develop/custom-claims-provider-overview
+    additionalScopes: [offline_access, groups, email]
+
+    # If you would also like to allow your end users to authenticate using
+    # a password grant, then change this to true. 
+    allowPasswordGrant: false
+
+  # Specify how Azure AD claims are mapped to Kubernetes identities.
+  claims:
+
+    # Specify the name of the claim in your Azure AD token that will be mapped
+    # to the "username" claim in downstream tokens minted by the Supervisor.
+    username: email 
+
+    # Specify the name of the claim in Azure AD that represents the groups
+    # that the user belongs to. This matches what you specified above
+    # with the Groups claim filter.
+    groups: groups
+
+  # Specify the name of the Kubernetes Secret that contains your Azure AD
+  # application's client credentials (created below).
+  client:
+    secretName: azuread-client-credentials
+
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  namespace: pinniped-supervisor
+  name: azuread-client-credentials
+type: secrets.pinniped.dev/oidc-client
+stringData:
+
+  # The "Client ID" for your Application
+  # Note that when you create a secret the secret itself will also receive an ID. 
+  # The secret ID is not used. Use the Application Client ID.
+  clientID: "<your-client-id>"
+
+  # The "Client secret" that you created when you made a secret for your Azure AD Application.  
+  clientSecret: "<your-client-secret>"
+```
+
+Note that the `metadata.name` of the OIDCIdentityProvider resource may be visible to end users at login prompts
+if you choose to enable `allowPasswordGrant`, so choose a name which will be understood by your end users.
+For example, if you work at Acme Corp, choose something like `acme-corporate-azuread` over `my-idp`.
+
+Once your OIDCIdentityProvider has been created, you can validate your configuration by running:
+
+```shell
+kubectl describe OIDCIdentityProvider -n pinniped-supervisor azuread
+```
+
+Look at the `status` field. If it was configured correctly, you should see `phase: Ready`.
+
+## Next steps
+
+Next, [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}})!
+Then you'll be able to log into those clusters as any of the users from the Azure AD directory.

site/content/docs/howto/supervisor/configure-supervisor-with-entra-id.md

@@ -0,0 +1,16 @@
+---
+title: Configure the Pinniped Supervisor to use Miscrosoft Entra ID as an OIDC provider
+description: Set up the Pinniped Supervisor to use Miscrosoft Entra ID to login.
+cascade:
+  layout: docs
+menu:
+  docs:
+    name: With Entra ID
+    weight: 80
+    parent: howto-configure-supervisor
+---
+
+Microsoft's Entra ID is the rebranding of Microsoft Azure AD.  For more information,
+[read this](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id).
+
+To learn how to configure Entra ID, [read our Azure AD documentation]({{< ref "configure-supervisor-with-azuread" >}}).

site/content/docs/howto/supervisor/configure-supervisor-with-jumpcloudldap.md

@@ -26,6 +26,7 @@ This how-to guide assumes that you have already [installed the Pinniped Supervis
 and that you have [configured a FederationDomain to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}).
 
 ## Configure Your JumpCloud Account
+
 If you don't already have a JumpCloud account, you can create one for free with up to 10 users in the account.
 
 You will need to create two types of users in your JumpCloud account using the JumpCloud console UI: