ContainerImage.Pinniped/site/content/docs/howto/configure-supervisor-with-workspace_one_access.md

title	description	cascade	menu
Configure the Pinniped Supervisor to use Workspace ONE Access as an OIDC provider	Set up the Pinniped Supervisor to use Workspace ONE Access login.	layout docs	docs name weight parent Configure Supervisor With Workspace ONE Access 80 howtos

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 Workspace ONE Access 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 Workspace ONE Access Application

Follow the Workspace ONE documentation for adding an OIDC app, including the documentation for the detailed steps required.

For example, to create an app:

1. In the Workspace ONE Access Console, navigate to Catalog > Web Apps.
2. Create a new app:
   1. Click New.
   2. Enter a name for your app, such as "My Kubernetes Clusters".
   3. For Authentication Type, select OpenID Connect.
   4. Enter the Target URL. This value is required but unused and may be set to the spec.issuer you configured in your FederationDomain.
   5. Enter the Redirect URL. This is the spec.issuer you configured in your FederationDomain appended with /callback.
   6. Enter the Client ID to a value such as "pinniped-supervisor" (this cannot be changed later).
   7. Enter the Client Secret. This should be set to a secure value such as the output of openssl rand -hex 32.
   8. Set both "Open in Workspace ONE Web" and "Show in User Portal" options to "No"
   9. Set the desired Access Policies for the app, such as requiring smart card login.
   10. Save and assign the app to the desired users and/or groups. This can be used to restrict which users can log in to Kubernetes using this integration.
3. Configure the token TTLs and scopes. Navigate to Catalog > Settings > Remote App access and click on the "pinniped-supervisor" client.
   1. Edit the Client Configuration:
      1. Issue Refresh Token must be checked
      2. Set Access Token Time-To-Live (TTL) to 5 minutes
      3. Set Refresh Token Time-To-Live (TTL) to 9 hours (or shorter if you wish to require more frequent logins)
      4. Set Idle Token Time-to-Live (TTL) to 9 hours (or shorter if you wish to enforce an inactivity timeout)
   2. Edit the Scope configuration:
      1. OpenID must be checked
      2. Check Email if you plan to use email as the username claim
      3. Check Group if you plan to use groups in your Kubernetes environment
      4. Uncheck all other scopes

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.

For example, this OIDCIdentityProvider and corresponding Secret use Workspace ONE Access's email claim as the Kubernetes username:

apiVersion: idp.supervisor.pinniped.dev/v1alpha1
kind: OIDCIdentityProvider
metadata:
  namespace: pinniped-supervisor
  name: ws1
spec:

  # Specify the issuer URL (no trailing slash). Change this to be the
  # actual issuer of your Workspace ONE Access environment.  Note that
  # the Workspace ONE Access issuer ends with the string "/SAAS/auth."
  issuer: https://ws1.my-company.com/SAAS/auth

  # Specify how to form authorization requests to Workspace ONE Access.
  authorizationConfig:

    # Request any scopes other than "openid" for claims besides
    # the default claims in your token. The "openid" scope is always
    # included.
    #
    # See the example claims below to learn how to customize the claims returned.
    additionalScopes: [group, email]

  # Specify how Workspace ONE Access claims are mapped to Kubernetes identities.
  claims:

    # Specify the name of the claim in your Workspace ONE Access token that
    # will be mapped to the username in your Kubernetes environment.
    #
    # User's emails can change. Use the sub claim if 
    # your environment requires a stable identifier.
    username: email

    # Specify the name of the claim in Workspace ONE Access that represents the
    # groups the user belongs to.
    #
    # Group names may not be unique and can change.
    # The group_ids claim is recommended for environments
    # that want to use a more stable identifier.
    groups: group_names

  # Specify the name of the Kubernetes Secret that contains your
  # Workspace ONE Access application's client credentials (created below).
  client:
    secretName: ws1-client-credentials
---
apiVersion: v1
kind: Secret
metadata:
  namespace: pinniped-supervisor
  name: ws1-client-credentials
type: secrets.pinniped.dev/oidc-client
stringData:

  # The "Client ID" that you got from Workspace ONE Access.
  clientID: "<your-client-id>"

  # The "Client secret" that you got from Workspace ONE Access.
  clientSecret: "<your-client-secret>"

The following claims are returned by Workspace ONE Access. The group scope is required to use the group_ids and group_names claims. The email scope is required to use the email claim. The remaining claims are always available.

{
  "acct": "my-username@System Domain",
  "email": "my-email@my-company.com",
  "email_verified": true,
  "group_ids": [
    "8cb8d875-4eb5-4d75-af7e-136efb439b6d",
    "9eb9c163-0677-4fc6-b70f-b4e14600a097"
  ],
  "group_names": [
    "ALL USERS",
    "Test Group"
  ],
  "iss": "https://ws1.my-company.com/SAAS/auth",
  "sub": "my-username@WS1-ENV-NAME",
}

Once your OIDCIdentityProvider has been created, you can validate your configuration by running:

kubectl describe OIDCIdentityProvider -n pinniped-supervisor ws1

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 Workspace ONE Access.