forked from pivotal-cf/docs-pks
-
Notifications
You must be signed in to change notification settings - Fork 0
/
_uaa.html.md.erb
188 lines (140 loc) · 14.6 KB
/
_uaa.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
To configure the UAA server, do the following:
1. Click **UAA**.
1. Under **PKS API Access Token Lifetime**, enter a time in seconds for the PKS API access token lifetime. This field defaults to `600`.<br>
<img src="images/uaa.png" alt="UAA pane configuration" width="325">
1. Under **PKS API Refresh Token Lifetime**, enter a time in seconds for the PKS API refresh token lifetime. This field defaults to `21600`.
1. Under **PKS Cluster Access Token Lifetime**, enter a time in seconds for the cluster access token lifetime. This field defaults to `600`.
1. Under **PKS Cluster Refresh Token Lifetime**, enter a time in seconds for the cluster refresh token lifetime. This field defaults to `21600`.
<p class="note"><strong>Note</strong>: Pivotal recommends using the default UAA token timeout values.
By default, access tokens expire after ten minutes and refresh tokens expire after six hours.
If you want to customize your token timeout values,
see <a href="https://docs.pivotal.io/pivotalcf/uaa/uaa-overview.html#tokens">Token Management</a> in <em>UAA Overview</em>.
</p>
1. Under **Configure created clusters to use UAA as the OIDC provider**, select **Enabled** or **Disabled**. If you click **Enabled**, Kubernetes verifies end-user identities based on authentication executed by a UAA authorization server. For more information, see the table below.
<table class="nice">
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td>**Disabled**</td>
<td>If you do not enable UAA as the OpenID Connect (OIDC) provider, Kubernetes authenticates users against its internal user management system.</td>
</tr>
<tr>
<td>**Enabled**</td>
<td>If you enable UAA as the OIDC provider, Kubernetes authenticates users as follows:
<ul>
<li>If you select <strong>Internal UAA</strong> in the next step, Kubernetes authenticates users against the internal UAA authentication mechanism.</li>
<li>If you select <strong>LDAP Server</strong> in the next step, Kubernetes authenticates users against the LDAP server.</li>
<li>If you select <strong>SAML Identity Provider</strong> in the next step, Kubernetes authenticates users against the SAML identity provider.</li>
</ul>
</td>
</tr>
</table>
<p class="note"><strong>Note</strong>: When you enable UAA as the OIDC provider, existing <%= vars.product_short %>-provisioned Kubernetes clusters are upgraded to use OIDC. This invalidates your kubeconfig files. You must regenerate the files for all clusters.</p>
To configure <%= vars.product_short %> to use UAA as the OIDC provider, do the following:
1. Under **Configure created clusters to use UAA as the OIDC provider**, select **Enabled**.
1. For **UAA OIDC Groups Claim**, enter the name of your groups claim. This is used to set a user's group in the JSON Web Token (JWT) claim. The default value is `roles`.
1. For **UAA OIDC Groups Prefix**, enter a prefix for your groups claim. This prevents conflicts with existing names. For example, if you enter the prefix `oidc:`, UAA creates a group name like `oidc:developers`. If you are configuring a new <%= vars.product_short %> installation, the default is `oidc:`. If you are upgrading to <%= vars.product_short %> v1.5, the default is `-`.
1. For **UAA OIDC Username Claim**, enter the name of your username claim. This is used to set a user's username in the JWT claim. The default value is `user_name`. Depending on your provider, admins can enter claims besides `user_name` like `email` or `name`.
1. For **UAA OIDC Username Prefix**, enter a prefix for your username claim. This prevents conflicts with existing names. For example, if you enter the prefix `oidc:`, UAA creates a username like `oidc:admin`. If you are configuring a new <%= vars.product_short %> installation, the default is `oidc:`. If you are upgrading to <%= vars.product_short %> v1.5, the default is `-`.
<p class="note"><strong>Note:</strong> Pivotal recommends adding OIDC prefixes to prevent OIDC users and groups from gaining unintended cluster privileges. When you upgrade to <%= vars.product_short %> v1.5, if you do not change the values for <strong>UAA OIDC Groups Prefix</strong> or <strong> UAA OIDC Username Prefix</strong>, <%=vars.product_short %> does not add prefixes.</p>
<p class="note warning"><strong>Warning:</strong> If you change the above values for a pre-existing <%=vars.product_short %> installation, you must change any existing role bindings that bind to a username or group. If you do not change your role bindings, developers cannot access Kubernetes clusters. For instructions about creating role bindings, see <a href="./manage-cluster-permissions.html">Managing Cluster Access and Permissions</a>.</p>
1. Select one of the following options:
* To use an internal user account store for UAA, select **Internal UAA**. Click **Save** and continue to [(Optional) Monitoring](#monitoring).
* To use LDAP for UAA, select **LDAP Server** and continue to [Configure LDAP as an Identity Provider](#configure-ldap).
<p class="note"><strong>Note</strong>: Selecting <strong>LDAP Server</strong> allows admin users to give cluster access to groups of users. For more information about performing this procedure, see <a href="manage-cluster-permissions.html#cluster-access-group">Grant Cluster Access to a Group</a> in <em>Managing Cluster Access and Permissions</em>.</p>
* To use SAML for UAA, select **SAML Identity Provider** and continue to [Configure SAML as an Identity
Provider](#configure-saml).
#### <a id="configure-ldap"></a>Configure LDAP as an Identity Provider
To integrate UAA with one or more LDAP servers, configure <%= vars.product_short %> with your LDAP endpoint information as follows:
1. Under **UAA**, select **LDAP Server**.<br>
1. For **Server URL**, enter the URLs that point to your LDAP server.
If you have multiple LDAP servers, separate their URLs with spaces.
Each URL must include one of the following protocols:
* `ldap://`: Use this protocol if your LDAP server uses an unencrypted connection.
* `ldaps://`: Use this protocol if your LDAP server uses SSL for an encrypted connection.
To support an encrypted connection, the LDAP server must hold a trusted certificate or you must import a trusted certificate to the JVM truststore.
1. For **LDAP Credentials**, enter the LDAP Distinguished Name (DN) and password for binding to the LDAP server.
For example, `cn=administrator,ou=Users,dc=example,dc=com`.
If the bind user belongs to a different search base, you must use the full DN.
<p class="note"><strong>Note</strong>: We recommend that you provide LDAP credentials that grant read-only permissions on the LDAP search base and the LDAP group search base.</p>
1. For **User Search Base**, enter the location in the LDAP directory tree where LDAP user search begins. The LDAP search base typically matches your domain name.
<br><br>
For example, a domain named `cloud.example.com` may use `ou=Users,dc=example,dc=com` as its LDAP user search base.
1. For **User Search Filter**, enter a string to use for LDAP user search criteria.
The search criteria allows LDAP to perform more effective and efficient searches.
For example, the standard LDAP search filter `cn=Smith` returns all objects with a common name equal to `Smith`.
<br><br>
In the LDAP search filter string that you use to configure <%= vars.product_short %>, use `{0}` instead of the username.
For example, use `cn={0}` to return all LDAP objects with the same common name as the username.
<br><br>
In addition to `cn`, other common attributes are `mail`, `uid` and, in the case of Active Directory, `sAMAccountName`.
<p class="note"><strong>Note</strong>: For information about testing and troubleshooting your LDAP search filters, see <a href="https://community.pivotal.io/s/article/Configuring-LDAP-Integration-with-Pivotal-Cloud-Foundry">Configuring LDAP Integration with Pivotal Cloud Foundry</a>.</p>
1. For **Group Search Base**, enter the location in the LDAP directory tree where the LDAP group search begins.
<br><br>
For example, a domain named `cloud.example.com` may use `ou=Groups,dc=example,dc=com` as its LDAP group search base.
<br><br>
Follow the instructions in the [Grant <%= vars.product_short %> Access to an External LDAP Group](manage-users.html#external-group) section of _Managing Users in <%= vars.product_short %> with UAA_ to map the groups under this search base to roles in <%= vars.product_short %>.
1. For **Group Search Filter**, enter a string that defines LDAP group search criteria. The standard value is `member={0}`.
1. For **Server SSL Cert**, paste in the root certificate from your CA certificate or your self-signed certificate.<br>
1. For **Server SSL Cert AltName**, do one of the following:
* If you are using `ldaps://` with a self-signed certificate, enter a Subject Alternative Name (SAN) for your certificate.
* If you are not using `ldaps://` with a self-signed certificate, leave this field blank.
1. For **First Name Attribute**, enter the attribute name in your LDAP directory that contains user first names.
For example, `cn`.
1. For **Last Name Attribute**, enter the attribute name in your LDAP directory that contains user last names.
For example, `sn`.
1. For **Email Attribute**, enter the attribute name in your LDAP directory that contains user email addresses.
For example, `mail`.
1. For **Email Domain(s)**, enter a comma-separated list of the email domains for external users who can receive invitations to Apps Manager.
1. For **LDAP Referrals**, choose how UAA handles LDAP server referrals to other user stores.
UAA can follow the external referrals, ignore them without returning errors, or generate an error for each external referral and abort the authentication.
1. For **External Groups Whitelist**, enter a comma-separated list of group patterns which need to be populated in the user's `id_token`. For further information on accepted patterns see the description of the `config.externalGroupsWhitelist` in the OAuth/OIDC [Identity Provider Documentation](https://docs.cloudfoundry.org/api/uaa/version/4.19.0/index.html#oauth-oidc).
<p class="note"><strong>Note</strong>: When sent as a Bearer token in the Authentication header, wide pattern queries for users who are members of multiple groups, can cause the size of the <code>id_token</code> to extend beyond what is supported by web servers.</p>
1. Click **Save**.
#### <a id="configure-saml"></a>Configure SAML as an Identity Provider
Before you configure a SAML identity provider in the <%= vars.product_tile %> tile, you must configure your identity provider to designate <%= vars.product_short %> as a service provider.
Refer to the table below for information about industry-standard identity providers and how to integrate them with <%= vars.product_short %>:
<table>
<tr>
<th>Solution Name</th>
<th>Integration Guide</th>
</tr>
<tr>
<td><a href="https://www.okta.com/products/single-sign-on/">Okta Single Sign-On</a></td>
<td><a href="./okta-sso-config.html">Configuring Okta as a SAML Identity Provider</a></td>
</tr>
<tr>
<td><a href="https://azure.microsoft.com/en-us/services/active-directory/">Azure Active Directory</a></td>
<td><a href="./azure-ad-sso-config.html">Configuring Azure Active Directory as a SAML Identity Provider</a></td>
</tr>
</table>
To integrate UAA with a SAML identity provider, configure <%= vars.product_short %>, by doing the following:
1. Under **UAA**, select **SAML Identity Provider**.
1. For **Provider Name**, enter a unique name you create for the Identity Provider. This name can include only alphanumeric characters, +, _, and -. You must not change this name after deployment because all external users use it to link to the provider.
1. For **Display Name**, enter a display name for your provider. This display name appears as a link on your Pivotal login page, which you can access at `https://PKS-API:8443/login`.
1. Retrieve the metadata from your identity provider and enter it into either the **Provider Metadata** or the **Provider Metadata URL** fields, depending on whether your identity provider exposes a metadata URL or not.
You recorded your identity provider metadata when you configure your identity provider to designate <%= vars.product_short %> as a service provider.
<br><br>Enter the your identity provider metadata by doing one of the following:
* If your identity provider exposes a metadata URL, enter it in **Metadata URL**.
* Download your identity provider metadata and paste this XML into **Provider Metadata**.
Pivotal recommends that you use the Provider Metadata URL rather than Provider Metadata because the metadata can change.
<p class='note'><strong>Note:</strong> You only need to select one of the above configurations. If you configure both, your Identity Provider defaults to the <strong>(OR) Provider Metadata URL</strong>.</p>
1. For **Name ID Format**, select the name identifier format for your SAML Identity Provider. This translates to `username` on <%= vars.product_short %>. The default is `Email Address`.
1. For **First Name Attribute** and **Last Name Attribute**, enter the attribute names in your SAML database that correspond to the first and last names in each user record. This field is case sensitive.
1. For **Email Attribute**, enter the attribute name in your SAML assertion that corresponds to the email address in each user record, for example, `EmailID`. This field is case sensitive.
1. For **External Groups Attribute**, enter the attribute name in your SAML database for your user groups. This field is case sensitive.
To map the groups from the SAML assertion to admin roles in PKS, see [Grant Enterprise PKS Access to an External LDAP Group](./manage-users.html#external-group) in _Managing Enterprise PKS Admin Users with UAA_.
1. By default, all SAML Authentication Request from <%= vars.product_short %> are signed. To change this, disable **Sign Authentication Requests** and configure your Identity Provider to verify SAML authentication requests.
1. To validate the signature for the incoming SAML assertions, enable **Required Signed Assertions**
and configure your Identity Provider to send signed SAML assertions.
1. For **Signature Algorithm**, choose an algorithm from the dropdown to use for signed requests and assertions. The default value is `SHA256`.
1. Click **Save**.