Add Workspace ONE Access docs
Signed-off-by: Monis Khan <mok@vmware.com>
This commit is contained in:
Monis Khan
parent
9c5adad062
commit
57fb085bef
@ -0,0 +1,153 @@
|
||||
---
|
||||
title: Configure the Pinniped Supervisor to use Workspace ONE Access as an OIDC provider
|
||||
description: Set up the Pinniped Supervisor to use Workspace ONE Access login.
|
||||
cascade:
|
||||
layout: docs
|
||||
menu:
|
||||
docs:
|
||||
name: Configure Supervisor With Workspace ONE Access
|
||||
weight: 80
|
||||
parent: howtos
|
||||
---
|
||||
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 [Workspace ONE Access](https://www.vmware.com/products/workspace-one/access.html) 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](https://docs.vmware.com/en/VMware-Workspace-ONE-Access/services/ws1-access-resources/GUID-8B97BC55-7A6C-4F52-9F68-EC486A4241B7.html), including the documentation for [the detailed steps required](https://docs.vmware.com/en/VMware-Workspace-ONE-Access/services/ws1-access-resources/GUID-406D8154-3C32-4AD1-A746-619BDF2CCB70.html).
|
||||
|
||||
For example, to create an app:
|
||||
|
||||
1. In the Workspace ONE Access Console, navigate to _Catalog_ > _Web Apps_.
|
||||
1. Create a new app:
|
||||
1. Click `New`.
|
||||
1. Enter a name for your app, such as "My Kubernetes Clusters".
|
||||
1. For `Authentication Type`, select `OpenID Connect`.
|
||||
1. Enter the Target URL. This value is required but unused and may be set to the `spec.issuer` you configured in your `FederationDomain`.
|
||||
1. Enter the Redirect URL. This is the `spec.issuer` you configured in your `FederationDomain` appended with `/callback`.
|
||||
1. Enter the Client ID to a value such as "pinniped-supervisor" (this cannot be changed later).
|
||||
1. Enter the Client Secret. This should be set to a secure value such as the output of `openssl rand -hex 32`.
|
||||
1. Set both "Open in Workspace ONE Web" and "Show in User Portal" options to "No"
|
||||
1. Set the desired Access Policies for the app, such as requiring smart card login.
|
||||
1. 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.
|
||||
1. 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
|
||||
1. Set `Access Token Time-To-Live (TTL)` to 5 minutes
|
||||
1. Set `Refresh Token Time-To-Live (TTL)` to 9 hours (or shorter if you wish to require more frequent logins)
|
||||
1. Set `Idle Token Time-to-Live (TTL)` to 9 hours (or shorter if you wish to enforce an inactivity timeout)
|
||||
1. Edit the _Scope_ configuration:
|
||||
1. `OpenID` must be checked
|
||||
1. Check `Email` if you plan to use email as the username claim
|
||||
1. Check `Group` if you plan to use groups in your Kubernetes environment
|
||||
1. 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:
|
||||
|
||||
```yaml
|
||||
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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```shell
|
||||
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.
|
||||
Loading…
Reference in New Issue
Block a user