Configure the Pinniped Supervisor to use Azure Active Directory as an OIDC provider

The Supervisor is an OpenID Connect (OIDC) 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 with working ingress, and that you have configured a FederationDomain to issue tokens for your downstream clusters.

Create an Azure AD Application

If you don’t already have an Azure subscription, create a free account. Next, create a new tenant in Azure Active Directory. This tenant represents your organization.

For example, to create a tenant:

1. In the Azure portal, navigate to Home > Azure Active Directory.
2. Create a new tenant:
   1. Click Manage Tenants.
   2. Click Create.
   3. Fill out your organization details.
3. Optionally, just use the Default Directory that is already created.
4. Users can be added to the directory via the Manage > Users link.
5. Create a new app:
   1. Click App Registrations.
   2. Click New Registration.
   3. Enter a user-facing display name.
   4. Choose supported account types.
   5. 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.
   6. Click Register.

Configure the Supervisor

Create an OIDCIdentityProvider in the same namespace as the Supervisor.

1. In the Azure portal, navigate to Home > Azure Active Directory > App Registrations.
   1. Copy the Application (client) ID) for use in your OIDCIdentityProvider CR later.
2. 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.
   2. Copy the secret Value for use later with your OIDCIdentityProvider.
3. Select your application, and then click Endpoints.
   1. Under Endpoints, find the OpenID Connect Metadata Document URL.
   2. Perform a curl with this URL and find the issuer value (curl https://<openid.connect.metadata.document.url> | jq ".issuer").
   3. 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:

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:

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! Then you’ll be able to log into those clusters as any of the users from the Azure AD directory.