Project: Pinniped (Provisioning / Key Management)
File: configure-supervisor-with-auth0.md

title: Configure the Pinniped Supervisor to use Auth0 as an OIDC provider description: Set up the Pinniped Supervisor to use Auth0 login. cascade: layout: docs menu: docs: name: With Auth0 OIDC weight: 80 parent: howto-configure-supervisor aliases: /docs/howto/configure-supervisor-with-auth0/ The Supervisor is an issuer that supports connecting "upstream" identity providers 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 Auth0 credentials. This how-to guide assumes that you have already with working ingress, and that you have . Follow the instructions to . For example, to create an app: In the , navigate to Applications > Applications. Create a new application: Click `+ Create Application`. Provide a name. For `Choose an application type`, select `Regular Web Applications`. Under `Settings`: Note the `Client ID` and `Client Secret`, which will be provided later to Pinniped. Update `Allowed Callback URLs` with Pinniped's issuer URL, appending `/callback` to the end. (Example: `https://pinniped.issuer.example.com/callback). Under `Advanced Settings`: Choose `Grant Types` and make sure that `Authorization Code`, `Refresh Token`, and `Password` are selected. Find the Auth0 Issuer URL by loading the URL at `Endpoints` > `OAuth` > `OpenID Configuration` and finding the `"issuer"` field. Auth0 does not have a simple concept of group membership for users. It may be possible to model group membership in Auth0, but the specifics depend on which enterprise connector or database is used to create your users. Please refer to the Auth0 documentation for more information. Pinniped does not have a specific recommendation for how user groups are defined in Auth0. The examples below are provided as examples to better understand how Auth0 and Pinniped integrate, not how to configure

Assuming that you have somehow configured Auth0 to include group membership information about your users, you can expose this to Pinniped by configuring Auth0 to include a in the Auth0 ID token. Auth0 recommends using a for your custom claim names. In the following example, replace `"https://example.com/pinniped/groups"` with the namespaced claim name of your choice. Pinniped requires that the value of the group claim is an array of strings. The following example is intended to show how to add a custom claim, but does not show a realistic example of where the group names should come from. To keep this example simple, the group names shown here are hardcoded. Do not hardcode group names for a production system. Instead, the array of groups should be dynamically provisioned from the appropriate place in the Auth0 user store. ```typescript exports.onExecutePostLogin = async (event, api) => { if (event.authorization) { api.idToken.setCustomClaim("https://example.com/pinniped/groups", ["auth0-read-only", "other-grouo", "something-else"]); } }; ``` To configure your Kubernetes authorization, please see . Create an in the same namespace as the Supervisor. For example, this OIDCIdentityProvider uses Auth0's `email` claim as the Kubernetes username: ```yaml apiVersion: idp.supervisor.pinniped.dev/v1alpha1 kind: OIDCIdentityProvider metadata: namespace: pinniped-supervisor name: auth0 spec: issuer: https://<your-tenant-id>.<your-region>.auth0.com/ authorizationConfig: additionalScopes: offline_access email allowPasswordGrant: false claims: username: email groups: https://example.com/pinniped/groups client: secretName: auth0-client-credentials apiVersion: v1 kind: Secret metadata: namespace: pinniped-supervisor name: auth0-client-credentials type: secrets.pinniped.dev/oidc-client stringData: clientID: "<your-client-id>" 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-auth0` over `my-idp`. Once your OIDCIdentityProvider has been created, you can validate your configuration by running: ```shell kubectl describe OIDCIdentityProvider -n pinniped-supervisor auth0 ``` Look at the `status` field. If it was configured correctly, you should see `phase: Ready`. Next, ! Then you'll be able to log into those clusters as any of the users from the Auth0 directory.