From 4101a55001544b79df41fd47a98737a17e76cdbc Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Wed, 11 May 2022 11:19:08 -0700 Subject: [PATCH] Update docs for new LDAP/AD browser-based login flow Also fix some comments that didn't fit onto one line in the yaml examples, be consistent about putting a blank line above `---` yaml separators, and some other small doc improvements. --- ...nfigure-supervisor-with-activedirectory.md | 24 +++++++---- .../howto/configure-supervisor-with-dex.md | 22 ++++++---- .../howto/configure-supervisor-with-gitlab.md | 5 +++ ...configure-supervisor-with-jumpcloudldap.md | 5 ++- .../howto/configure-supervisor-with-okta.md | 5 +++ .../configure-supervisor-with-openldap.md | 6 ++- ...re-supervisor-with-workspace_one_access.md | 21 ++++++---- .../docs/howto/configure-supervisor.md | 4 +- site/content/docs/howto/login.md | 42 ++++++++++++++----- .../docs/reference/code-walkthrough.md | 2 + 10 files changed, 98 insertions(+), 38 deletions(-) diff --git a/site/content/docs/howto/configure-supervisor-with-activedirectory.md b/site/content/docs/howto/configure-supervisor-with-activedirectory.md index 4b5aa387..0941f607 100644 --- a/site/content/docs/howto/configure-supervisor-with-activedirectory.md +++ b/site/content/docs/howto/configure-supervisor-with-activedirectory.md @@ -27,8 +27,8 @@ Create an [ActiveDirectoryIdentityProvider](https://github.com/vmware-tanzu/pinn ### ActiveDirectoryIdentityProvider with default options This ActiveDirectoryIdentityProvider uses all the default configuration options. - -Learn more about the default configuration [here]({{< ref "../reference/active-directory-configuration">}}) +The default configuration options are documented in the +[Active Directory configuration reference]({{< ref "../reference/active-directory-configuration">}}). ```yaml apiVersion: idp.supervisor.pinniped.dev/v1alpha1 @@ -41,14 +41,13 @@ spec: # Specify the host of the Active Directory server. host: "activedirectory.example.com:636" - # Specify the name of the Kubernetes Secret that contains your Active Directory - # bind account credentials. This service account will be used by the - # Supervisor to perform LDAP user and group searches. + # Specify the name of the Kubernetes Secret that contains your Active + # Directory bind account credentials. This service account will be + # used by the Supervisor to perform LDAP user and group searches. bind: secretName: "active-directory-bind-account" --- - apiVersion: v1 kind: Secret metadata: @@ -64,6 +63,10 @@ stringData: password: "YOUR_PASSWORD" ``` +Note that the `metadata.name` of the ActiveDirectoryIdentityProvider resource may be visible to end users at login prompts, +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-active-directory` over `my-idp`. + If you've saved this into a file `activedirectory.yaml`, then install it into your cluster using: ```sh @@ -140,13 +143,16 @@ spec: # successful authentication. groupName: "dn" - # Specify the name of the Kubernetes Secret that contains your Active Directory - # bind account credentials. This service account will be used by the - # Supervisor to perform LDAP user and group searches. + # Specify the name of the Kubernetes Secret that contains your Active + # Directory bind account credentials. This service account will be + # used by the Supervisor to perform LDAP user and group searches. bind: secretName: "active-directory-bind-account" ``` +More information about the defaults for these configuration options can be found in +the [Active Directory configuration reference]({{< ref "../reference/active-directory-configuration">}}). + ## Next steps Next, [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}})! diff --git a/site/content/docs/howto/configure-supervisor-with-dex.md b/site/content/docs/howto/configure-supervisor-with-dex.md index 8c707653..fe549ca8 100644 --- a/site/content/docs/howto/configure-supervisor-with-dex.md +++ b/site/content/docs/howto/configure-supervisor-with-dex.md @@ -104,19 +104,21 @@ spec: # to the "username" claim in downstream tokens minted by the Supervisor. username: email - # Specify the name of the claim in your Dex ID token that represents the groups - # that the user belongs to. This matches what you specified above + # Specify the name of the claim in your Dex ID token that represents the + # groups to which the user belongs. This matches what you specified above # with the Groups claim filter. # Note that the group claims from Github are in the format of "org:team". - # To query for the group scope, you should set the organization you want Dex to - # search against in its configuration, otherwise your group claim would be empty. - # An example config can be found at - https://dexidp.io/docs/connectors/github/#configuration + # To query for the group scope, you should set the organization you + # want Dex to search against in its configuration, otherwise your group + # claim would be empty. An example config can be found at + # https://dexidp.io/docs/connectors/github/#configuration groups: groups # Specify the name of the Kubernetes Secret that contains your Dex # application's client credentials (created below). client: secretName: dex-client-credentials + --- apiVersion: v1 kind: Secret @@ -125,13 +127,19 @@ metadata: name: dex-client-credentials type: secrets.pinniped.dev/oidc-client stringData: - # The "Client ID" that you set in Dex. For example, in our case this is "pinniped-supervisor" + # The "Client ID" that you set in Dex. For example, in our case + # this is "pinniped-supervisor". clientID: "" - # The "Client secret" that you set in Dex. For example, in our case this is "pinniped-supervisor-secret" + # The "Client secret" that you set in Dex. For example, in our + # case this is "pinniped-supervisor-secret". clientSecret: "" ``` +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-ldap` over `my-idp`. + Once your OIDCIdentityProvider resource has been created, you can validate your configuration by running: ```bash diff --git a/site/content/docs/howto/configure-supervisor-with-gitlab.md b/site/content/docs/howto/configure-supervisor-with-gitlab.md index d495d67b..75e08414 100644 --- a/site/content/docs/howto/configure-supervisor-with-gitlab.md +++ b/site/content/docs/howto/configure-supervisor-with-gitlab.md @@ -89,6 +89,7 @@ spec: # application's client credentials (created below). client: secretName: gitlab-client-credentials + --- apiVersion: v1 kind: Secret @@ -105,6 +106,10 @@ stringData: clientSecret: "" ``` +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-gitlab` over `my-idp`. + Once your OIDCIdentityProvider has been created, you can validate your configuration by running: ```shell diff --git a/site/content/docs/howto/configure-supervisor-with-jumpcloudldap.md b/site/content/docs/howto/configure-supervisor-with-jumpcloudldap.md index 732e9e77..7faa2e7c 100644 --- a/site/content/docs/howto/configure-supervisor-with-jumpcloudldap.md +++ b/site/content/docs/howto/configure-supervisor-with-jumpcloudldap.md @@ -120,7 +120,6 @@ spec: secretName: "jumpcloudldap-bind-account" --- - apiVersion: v1 kind: Secret metadata: @@ -138,6 +137,10 @@ stringData: password: "YOUR_PASSWORD" ``` +Note that the `metadata.name` of the LDAPIdentityProvider resource may be visible to end users at login prompts, +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-ldap` over `my-idp`. + If you've saved this into a file `jumpcloud.yaml`, then install it into your cluster using: ```sh diff --git a/site/content/docs/howto/configure-supervisor-with-okta.md b/site/content/docs/howto/configure-supervisor-with-okta.md index 6e37573f..1c955b6f 100644 --- a/site/content/docs/howto/configure-supervisor-with-okta.md +++ b/site/content/docs/howto/configure-supervisor-with-okta.md @@ -97,6 +97,7 @@ spec: # application's client credentials (created below). client: secretName: okta-client-credentials + --- apiVersion: v1 kind: Secret @@ -113,6 +114,10 @@ stringData: clientSecret: "" ``` +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-okta` over `my-idp`. + Once your OIDCIdentityProvider has been created, you can validate your configuration by running: ```shell diff --git a/site/content/docs/howto/configure-supervisor-with-openldap.md b/site/content/docs/howto/configure-supervisor-with-openldap.md index 35605024..aafb635f 100644 --- a/site/content/docs/howto/configure-supervisor-with-openldap.md +++ b/site/content/docs/howto/configure-supervisor-with-openldap.md @@ -158,6 +158,7 @@ spec: - name: certs secret: secretName: certs + --- apiVersion: v1 kind: Service @@ -265,7 +266,6 @@ spec: secretName: openldap-bind-account --- - apiVersion: v1 kind: Secret metadata: @@ -284,6 +284,10 @@ stringData: EOF ``` +Note that the `metadata.name` of the LDAPIdentityProvider resource may be visible to end users at login prompts, +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-ldap` over `my-idp`. + Once your LDAPIdentityProvider has been created, you can validate your configuration by running: ```sh diff --git a/site/content/docs/howto/configure-supervisor-with-workspace_one_access.md b/site/content/docs/howto/configure-supervisor-with-workspace_one_access.md index a77c83ef..7d411169 100644 --- a/site/content/docs/howto/configure-supervisor-with-workspace_one_access.md +++ b/site/content/docs/howto/configure-supervisor-with-workspace_one_access.md @@ -76,7 +76,8 @@ spec: # 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. + # 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. @@ -85,22 +86,22 @@ spec: # 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. + # 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. + # Specify the name of the claim in Workspace ONE Access that represents + # the groups to which the user belongs. # - # 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. + # 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 @@ -117,6 +118,10 @@ stringData: clientSecret: "" ``` +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-workspace-one` over `my-idp`. + 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. diff --git a/site/content/docs/howto/configure-supervisor.md b/site/content/docs/howto/configure-supervisor.md index 5f2c7e47..baf998ad 100644 --- a/site/content/docs/howto/configure-supervisor.md +++ b/site/content/docs/howto/configure-supervisor.md @@ -244,6 +244,6 @@ should be signed by a certificate authority that is trusted by their browsers. ## Next steps Next, configure an OIDCIdentityProvider, ActiveDirectoryIdentityProvider, or an LDAPIdentityProvider for the Supervisor -(several examples are available in these guides), -and [configure the Concierge to use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}}) +(several examples are available in these guides). Then +[configure the Concierge to use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}}) on each cluster! diff --git a/site/content/docs/howto/login.md b/site/content/docs/howto/login.md index 45cfb3ad..b2ae46a0 100644 --- a/site/content/docs/howto/login.md +++ b/site/content/docs/howto/login.md @@ -72,6 +72,9 @@ pinniped get kubeconfig \ The new Pinniped-compatible kubeconfig YAML will be output as stdout, and can be redirected to a file. Various default behaviors of `pinniped get kubeconfig` can be overridden using [its command-line options]({{< ref "cli" >}}). +One flag of note is `--upstream-identity-provider-flow browser_authcode` to choose end-user `kubectl` login via a web browser +(the default for OIDCIdentityProviders), and `--upstream-identity-provider-flow cli_password` to choose end-user `kubectl` +login via CLI username/password prompts (the default for LDAPIdentityProviders and ActiveDirectoryIdentityProviders). ## Use the generated kubeconfig with `kubectl` to access the cluster @@ -94,20 +97,33 @@ to authenticate the user to the cluster. If the Pinniped Supervisor is used for authentication to that cluster, then the user's authentication experience will depend on which type of identity provider was configured. -- For an OIDC identity provider, there are two supported client flows. +- For an OIDC identity provider, there are two supported client flows: - When using the default browser-based flow, `kubectl` will open the user's web browser and direct it to the login page of + 1. When using the default browser-based flow, `kubectl` will open the user's web browser and direct it to the login page of their OIDC Provider. This login flow is controlled by the provider, so it may include two-factor authentication or other features provided by the OIDC Provider. If the user's browser is not available, then `kubectl` will instead print a URL which can be visited in a browser (potentially on a different computer) to complete the authentication. - When using the optional CLI-based flow, `kubectl` will interactively prompt the user for their username and password at the CLI. + 2. When using the optional CLI-based flow, `kubectl` will interactively prompt the user for their username and password at the CLI. + Alternatively, the user can set the environment variables `PINNIPED_USERNAME` and `PINNIPED_PASSWORD` for the + `kubectl` process to avoid the interactive prompts. Note that the optional CLI-based flow must be enabled by the + administrator in the OIDCIdentityProvider configuration before use + (see `allowPasswordGrant` in the + [API docs](https://github.com/vmware-tanzu/pinniped/blob/main/generated/{{< latestcodegenversion >}}/README.adoc#oidcauthorizationconfig) + for more details). + +- For LDAP and Active Directory identity providers, there are also two supported client flows: + + 1. When using the default CLI-based flow, `kubectl` will interactively prompt the user for their username and password at the CLI. Alternatively, the user can set the environment variables `PINNIPED_USERNAME` and `PINNIPED_PASSWORD` for the `kubectl` process to avoid the interactive prompts. -- For an LDAP identity provider, `kubectl` will interactively prompt the user for their username and password at the CLI. - Alternatively, the user can set the environment variables `PINNIPED_USERNAME` and `PINNIPED_PASSWORD` for the - `kubectl` process to avoid the interactive prompts. + 2. When using the optional browser-based flow, `kubectl` will open the user's web browser and direct it to a login page + hosted by the Pinniped Supervisor. When the user enters their username and password, the Supervisor will authenticate + the user using the LDAP or Active Directory provider. If the user's browser is not available, then `kubectl` will instead + print a URL which can be visited in a browser (potentially on a different computer) to complete the authentication. + Unlike the optional flow for OIDC providers described above, this optional flow does not need to be configured in + the LDAPIdentityProvider or ActiveDirectoryIdentityProvider resource, so it is always available for end-users. Once the user completes authentication, the `kubectl` command will automatically continue and complete the user's requested command. For the example above, `kubectl` would list the cluster's namespaces. @@ -135,8 +151,14 @@ in the upstream identity provider, for example: --group auditors ``` -## Other notes +## Session and credential caching by the CLI -- Temporary session credentials such as ID, access, and refresh tokens are stored in: - - `~/.config/pinniped/sessions.yaml` (macOS/Linux) - - `%USERPROFILE%/.config/pinniped/sessions.yaml` (Windows). +Temporary session credentials such as ID, access, and refresh tokens are stored in: + - `$HOME/.config/pinniped/sessions.yaml` (macOS/Linux) + - `%USERPROFILE%/.config/pinniped/sessions.yaml` (Windows). + +Temporary cluster credentials such mTLS client certificates are stored in: + - `$HOME/.config/pinniped/credentials.yaml` (macOS/Linux) + - `%USERPROFILE%/.config/pinniped/credentials.yaml` (Windows). + +Deleting the contents of these directories is equivalent to performing a client-side logout. diff --git a/site/content/docs/reference/code-walkthrough.md b/site/content/docs/reference/code-walkthrough.md index de077f34..5ce69299 100644 --- a/site/content/docs/reference/code-walkthrough.md +++ b/site/content/docs/reference/code-walkthrough.md @@ -206,6 +206,8 @@ The per-FederationDomain endpoints are: See [internal/oidc/callback/callback_handler.go](https://github.com/vmware-tanzu/pinniped/blob/main/internal/oidc/callback/callback_handler.go). - `/v1alpha1/pinniped_identity_providers` is a custom discovery endpoint for clients to learn about available upstream identity providers. See [internal/oidc/idpdiscovery/idp_discovery_handler.go](https://github.com/vmware-tanzu/pinniped/blob/main/internal/oidc/idpdiscovery/idp_discovery_handler.go). +- `/login` is a login UI page to support the optional browser-based login flow for LDAP and Active Directory identity providers. + See [internal/oidc/login/login_handler.go](https://github.com/vmware-tanzu/pinniped/blob/main/internal/oidc/login/login_handler.go). The OIDC specifications implemented by the Supervisor can be found at [openid.net](https://openid.net/connect).