djpbessems/ContainerImage.Pinniped
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update docs for new LDAP/AD browser-based login flow

Browse Source 
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.
This commit is contained in:
Ryan Richard 2022-05-11 11:19:08 -07:00
parent aa732a41fb
commit 4101a55001
10 changed files with 98 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
site/content/docs/howto/configure-supervisor-with-activedirectory.md
View File

@ -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" >}})!

22
site/content/docs/howto/configure-supervisor-with-dex.md
View File

@ -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: "<your-client-id>"
# 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: "<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-ldap` over `my-idp`.
Once your OIDCIdentityProvider resource has been created, you can validate your configuration by running:
```bash

5
site/content/docs/howto/configure-supervisor-with-gitlab.md
View File

@ -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: "<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-gitlab` over `my-idp`.
Once your OIDCIdentityProvider has been created, you can validate your configuration by running:
```shell

5
site/content/docs/howto/configure-supervisor-with-jumpcloudldap.md
View File

@ -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

5
site/content/docs/howto/configure-supervisor-with-okta.md
View File

@ -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: "<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-okta` over `my-idp`.
Once your OIDCIdentityProvider has been created, you can validate your configuration by running:
```shell

6
site/content/docs/howto/configure-supervisor-with-openldap.md
View File

@ -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

21
site/content/docs/howto/configure-supervisor-with-workspace_one_access.md
View File

@ -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: "<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-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.

4
site/content/docs/howto/configure-supervisor.md
View File

@ -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!

40
site/content/docs/howto/login.md
View File

@ -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)
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.

2
site/content/docs/reference/code-walkthrough.md
View File

@ -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).
- `<issuer_path>/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).
- `<issuer_path>/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).