Merge pull request #756 from vmware-tanzu/ad-identity-provider-docs
Document how to configure the ActiveDirectoryIdentityProvider
This commit is contained in:
Ryan Richard
GitHub
commit
883007aa1b
@ -0,0 +1,153 @@
|
||||
---
|
||||
title: Configure the Pinniped Supervisor to use Microsoft Active Directory as an ActiveDirectoryIdentityProvider
|
||||
description: Set up the Pinniped Supervisor to use Microsoft Active Directory
|
||||
cascade:
|
||||
layout: docs
|
||||
menu:
|
||||
docs:
|
||||
name: Configure Supervisor With Active Directory
|
||||
weight: 110
|
||||
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 identity from Active Directory.
|
||||
|
||||
## 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" >}}).
|
||||
|
||||
## Configure the Supervisor cluster
|
||||
|
||||
Create an [ActiveDirectoryIdentityProvider](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#activedirectoryidentityprovider) in the same namespace as the Supervisor.
|
||||
|
||||
### ActiveDirectoryIdentityProvider with default options
|
||||
|
||||
This ActiveDirectoryIdentityProvider uses all the default configuration options.
|
||||
|
||||
Learn more about the default configuration [here]({{< ref "../reference/active-directory-configuration">}})
|
||||
|
||||
```yaml
|
||||
apiVersion: idp.supervisor.pinniped.dev/v1alpha1
|
||||
kind: ActiveDirectoryIdentityProvider
|
||||
metadata:
|
||||
name: my-active-directory-idp
|
||||
namespace: pinniped-supervisor
|
||||
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.
|
||||
bind:
|
||||
secretName: "active-directory-bind-account"
|
||||
|
||||
---
|
||||
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: active-directory-bind-account
|
||||
namespace: pinniped-supervisor
|
||||
type: kubernetes.io/basic-auth
|
||||
stringData:
|
||||
|
||||
# The dn (distinguished name) of your Active Directory bind account.
|
||||
username: "CN=Bind User,OU=Users,DC=activedirectory,DC=example,dc=com"
|
||||
|
||||
# The password of your Active Directory bind account.
|
||||
password: "YOUR_PASSWORD"
|
||||
```
|
||||
|
||||
If you've saved this into a file `activedirectory.yaml`, then install it into your cluster using:
|
||||
|
||||
```sh
|
||||
kubectl apply -f activedirectory.yaml
|
||||
```
|
||||
|
||||
Once your ActiveDirectoryIdentityProvider has been created, you can validate your configuration by running:
|
||||
|
||||
```sh
|
||||
kubectl describe ActiveDirectoryIdentityProvider -n pinniped-supervisor my-active-directory-idp
|
||||
```
|
||||
|
||||
Look at the `status` field. If it was configured correctly, you should see `phase: Ready`.
|
||||
|
||||
### (Optional) Configure the ActiveDirectoryIdentityProvider with custom options
|
||||
|
||||
You can also override the default `userSearch` and `groupSearch` options with other values.
|
||||
|
||||
```yaml
|
||||
apiVersion: idp.supervisor.pinniped.dev/v1alpha1
|
||||
kind: ActiveDirectoryIdentityProvider
|
||||
metadata:
|
||||
name: my-active-directory-idp
|
||||
namespace: pinniped-supervisor
|
||||
spec:
|
||||
|
||||
# Specify the host of the Active Directory server.
|
||||
host: "activedirectory.example.com:636"
|
||||
|
||||
# Specify how to search for the username when an end-user tries to log in
|
||||
# using their username and password.
|
||||
userSearch:
|
||||
|
||||
# Specify the root of the user search.
|
||||
base: "OU=my-department,OU=Users,DC=activedirectory,DC=example,DC=com"
|
||||
|
||||
# Specify how to filter the search to find the specific user by username.
|
||||
# "{}" will be replaced # by the username that the end-user had typed
|
||||
# when they tried to log in.
|
||||
filter: "&(objectClass=person)(userPrincipleName={})"
|
||||
|
||||
# Specify which fields from the user entry should be used upon
|
||||
# successful login.
|
||||
attributes:
|
||||
|
||||
# Specifies the name of the attribute in the LDAP entry whose
|
||||
# value shall become the username of the user after a successful
|
||||
# authentication.
|
||||
username: "mail"
|
||||
|
||||
# Specifies the name of the attribute in the LDAP entry whose
|
||||
# value shall be used to uniquely identify the user within this
|
||||
# LDAP provider after a successful authentication.
|
||||
uid: "objectGUID"
|
||||
|
||||
# Specify how to search for the group membership of an end-user during login.
|
||||
groupSearch:
|
||||
|
||||
# Specify the root of the group search. This may be a different subtree of
|
||||
# the LDAP database compared to the user search
|
||||
base: "ou=Groups,DC=activedirectory,DC=example,DC=com"
|
||||
|
||||
# Specify the search filter which should be applied when searching for
|
||||
# groups for a user. "{}" will be replaced by the dn (distinguished
|
||||
# name) of the user entry found as a result of the user search.
|
||||
filter: "&(objectClass=group)(member={})"
|
||||
|
||||
# Specify which fields from each group entry should be used upon
|
||||
# successful login.
|
||||
attributes:
|
||||
|
||||
# Specify the name of the attribute in the LDAP entries whose value
|
||||
# shall become a group name in the user’s list of groups after a
|
||||
# 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.
|
||||
bind:
|
||||
secretName: "active-directory-bind-account"
|
||||
```
|
||||
|
||||
## 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 your users from Active Directory.
|
||||
@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Active Directory Configuration
|
||||
description: See the default configuration values for the ActiveDirectoryIdentityProvider.
|
||||
cascade:
|
||||
layout: docs
|
||||
menu:
|
||||
docs:
|
||||
name: Active Directory Configuration
|
||||
weight: 10
|
||||
parent: reference
|
||||
---
|
||||
|
||||
This describes the default values for the `ActiveDirectoryIdentityProvider` user and group search. For more about `ActiveDirectoryIdentityProvider`
|
||||
configuration, see [the API reference documentation](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#activedirectoryidentityprovider).
|
||||
|
||||
### `spec.userSearch.base`
|
||||
|
||||
*Default Behavior*: Queries the Active Directory host for the [defaultNamingContext](https://docs.microsoft.com/en-us/windows/win32/adschema/rootdse).
|
||||
|
||||
*Implications*: Searches your entire domain for users. It may make sense to specify a subtree as a search base if you wish to exclude some users for security reasons or to make searches faster.
|
||||
|
||||
|
||||
### `spec.userSearch.attributes.username`
|
||||
|
||||
*Default Behavior*: The `userPrincipalName` attribute will become the user's Kubernetes username.
|
||||
|
||||
### `spec.userSearch.attributes.uid`
|
||||
*Default Behavior*: The `objectGUID` attribute will be used to uniquely identify users.
|
||||
|
||||
### `spec.userSearch.filter`
|
||||
*Default Behavior*:
|
||||
```
|
||||
"(&(objectClass=person)(!(objectClass=computer))(!(showInAdvancedViewOnly=TRUE))(|(sAMAccountName={})(mail={})(userPrincipalName={}))(sAMAccountType=805306368))"
|
||||
```
|
||||
|
||||
Requires the following of the Active Directory entry of the user specified:
|
||||
* is a person.
|
||||
* is not a computer.
|
||||
* is not shown in advanced view only (which would likely mean its a system created service account with advanced permissions).
|
||||
* either the `sAMAccountName`, the `userPrincipalName`, or the `mail` attribute matches the input username.
|
||||
* the `sAMAccountType` is for a normal user account.
|
||||
|
||||
### `spec.groupSearch.base`
|
||||
|
||||
*Default Behavior*: Queries the Active Directory host for the [defaultNamingContext](https://docs.microsoft.com/en-us/windows/win32/adschema/rootdse).
|
||||
|
||||
*Implications*: Searches your entire domain for groups. It may make sense to specify a subtree as a search base if you wish to exclude some groups for security reasons or to make searches faster.
|
||||
|
||||
### `spec.groupSearch.attributes.groupName`
|
||||
*Default Behavior*: The attribute that will become the user's groups in Kubernetes will look like `sAMAccountName@domain` (where domain is constructed from the domain components of the group).
|
||||
|
||||
### `spec.groupSearch.filter`
|
||||
|
||||
*Default Behavior*:
|
||||
```
|
||||
(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={}))
|
||||
```
|
||||
Requires the following of the Active Directory entrys that will represent the groups:
|
||||
* is a group.
|
||||
* has a member that matches the DN of the user we successfully logged in as, including indirectly through nested groups.
|
||||
|
||||
*Implications*: Nested group search may be slow. If you are having performance issues during login, you can change the filter to the following:
|
||||
```
|
||||
(&(objectClass=group)(member={}))
|
||||
```
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user