forked from pivotal-cf/docs-ops-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathauth-sso.html.md.erb
175 lines (111 loc) · 12.5 KB
/
auth-sso.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
---
breadcrumb: Pivotal Cloud Foundry Documentation
title: Configuring Authentication and Enterprise SSO for PAS
owner: Identity
---
<strong><%= modified_date %></strong>
This topic describes [Pivotal Cloud Foundry](https://network.pivotal.io/products/pivotal-cf) (PCF) Pivotal Application Service (PAS) authentication and single sign-on configuration with Lightweight Directory Access Protocol (LDAP) and Security Assertion Markup Language (SAML).
Refer to the instructions below to configure your deployment with SAML or LDAP.
Connecting Pivotal Application Service (PAS) to either the LDAP or SAML external user store allows the User Account and Authentication (UAA) server to delegate authentication to existing enterprise user stores.
If your enterprise user store is exposed as a SAML or LDAP Identity Provider for single sign-on (SSO), you can configure SSO to allow users to access the Apps Manager and Cloud Foundry Command Line Interface (cf CLI) without creating a new account or, if using SAML, without re-entering credentials.
See the [Adding Existing SAML or LDAP Users to a PCF Deployment](./external-user-management.html) topic for information about managing user identity and pre-provisioning user roles with SAML or LDAP in PCF.
For an explanation of the process used by the UAA Server when it attempts to authenticate a user through LDAP, see the [Configuring LDAP Integration with Pivotal Cloud Foundry](https://discuss.zendesk.com/hc/en-us/articles/204140418-Configuring-LDAP-Integration-with-Pivotal-Cloud-Foundry-) Knowledge Base article.
<p class='note'><strong>Note:</strong> When integrating with an external identity provider, such as LDAP, authentication within the UAA becomes chained. An authentication attempt with a user's credentials is first attempted against the UAA user store before the external provider, LDAP. For more information, see <a href="https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-LDAP.md#chained-authentication">Chained Authentication</a> in the <em>User Account and Authentication LDAP Integration</em> GitHub documentation.</p>
## <a id="configure-saml"></a> Configure PAS to Use a SAML Identity Provider
In SAML terminology, the SAML protocol communicates user data between an identity provider (IdP) and a service provider (SP).
To connect PAS with SAML, do the following:
* [Configure PAS as a Service Provider for SAML](#configure-pcf-for-saml)
* [Configure SAML as an Identity Provider for PAS](#configure-saml-for-pcf)
### <a id="configure-pcf-for-saml"></a> Configure PAS as a Service Provider for SAML
To configure PAS to use a SAML IdP, do the following:
1. From the **Installation Dashboard**, click the PAS tile.
1. Select the **Domains** tab and record your system domain.
<%= image_tag("new-domains.png") %>
1. Select **Authentication and Enterprise SSO**.
1. Select **SAML Identity Provider**.
<%= image_tag("sso-ert.png") %>
1. Set the **Provider Name**. This is a unique name you create for the Identity Provider. This name can include only alphanumeric characters, `+`, `_`, and `-`. You should not change this name after deployment because all external users use it to link to the provider.
1. Enter a **Display Name**. Your provider display name appears as a link on your Pivotal login page, which you can access at `https://login.YOUR-SYSTEM-DOMAIN`.
<%= image_tag("login-page.png") %>
1. Retrieve the metadata from your Identity Provider and copy it into either the **Provider Metadata** or the **Provider Metadata URL** fields, depending on whether your Identity Provider exposes a Metadata URL or not. Refer to the [Configure SAML as an Identity Provider for PAS](#configure-saml-for-pcf) section of this topic for more information. Pivotal recommends that you use the Provider Metadata URL rather than Provider Metadata because the metadata can change. You can do this in either of the following ways:
* If your Identity Provider exposes a Metadata URL, provide the Metadata URL.
* Download your Identity Provider metadata and paste this XML into the **Provider Metadata** area.
<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>
<p class="note"><strong>Note:</strong> See <a href="../opsguide/external-user-management.html">Adding Existing SAML or LDAP Users to a PCF Deployment</a> for information about on-boarding SAML users and mapping them to PAS user roles.</p>
1. Select the **Name ID Format** for your SAML Identity Provider. This translates to `username` on PAS. The default is `Email Address`.
1. For **Email Domain(s)**, enter a comma-separated list of the email domains for external users who will receive invitations to Apps Manager.
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, for example `first_name` and `last_name`.
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`.
1. For **External Groups Attribute**, enter the attribute name in your SAML database that defines the groups that a user belongs to, for example `group_memberships`. To map the groups from the SAML assertion to admin roles in PAS, follow the instructions in the [Grant Admin Permissions to an External Group (SAML or LDAP)](../uaa/uaa-user-management.html#external-group) section of the _Creating and Managing Users with the UAA CLI (UAAC)_ topic.
1. By default, all SAML Authentication Request from PAS are signed. To change this, disable the **Sign Authentication Requests** checkbox and configure your Identity Provider to verify SAML authentication requests.
1. To validate the signature for the incoming SAML assertions, enable the **Required Signed Assertions** checkbox and configure your Identity Provider to send signed SAML assertions.
1. Click **Save**.
1. Return to the **Installation Dashboard** by clicking the link.
1. On the Installation Dashboard, click **Review Pending Changes**, then **Apply Changes**.
<%=image_tag("uaa/apply-changes.png")%>
### <a id="configure-saml-for-pcf"></a> Configure SAML as an Identity Provider for PAS
The following procedure configures a SAML IdP to designate PAS as an SP.
Download the Service Provider Metadata from `https://login.YOUR-SYSTEM-DOMAIN/saml/metadata`. Consult the documentation from your Identity Provider for configuration instructions.
Refer to the table below for information about certain industry-standard Identity Providers and how to integrate them with PAS:
<table border="1">
<tr>
<th>Solution Name</th>
<th>Integration Guide</th>
</tr>
<tr>
<td><a href='http://www.ca.com/us/securecenter/ca-single-sign-on.aspx'>CA Single Sign-On aka CA SiteMinder</a></td>
<td><a href="./ca-sso-config.html">Link</a></td>
</tr>
<tr>
<td><a href='https://www.pingidentity.com/en/products/pingfederate.html'>Ping Federate</a></td>
<td><a href="./ping-federate-sso-configuration.html">Link</a></td>
</tr>
<tr>
<td><a href='https://technet.microsoft.com/en-us/windowsserver/dd448613.aspx'>Active Directory Federation Services</a></td>
<td><a href="adfs-sso-configuration.html">Link</a></td>
</tr>
</table>
<p class="note"><strong>Note:</strong> Some Identity Providers allow uploads of Service Provider Metadata. Other providers require you to manually enter the Service Provider Metadata into a form.</p>
## <a id="configure-ldap"></a> Configure LDAP as an Identity Provider for PAS
To integrate the UAA with one or more LDAP servers, configure PAS with your LDAP endpoint information as follows:
1. Log into the Operations Manager web interface.
1. On the Product Dashboard, select the PAS tile.
<%=image_tag("uaa/er-tile.png")%>
1. In the left navigation menu, select **Authentication and Enterprise SSO**.
<%=image_tag("uaa/ldap-config.png")%>
1. Under **Configure your UAA**, select **LDAP Server**.
* For **Server URL**, enter the URL that point your LDAP server. With multiple LDAP servers, separate their URLs with spaces. Each URL must include one of the following protocols:
* `ldap://`: This specifies that the LDAP server uses an unencrypted connection.
* `ldaps://`: This specifies that the LDAP server uses SSL for an encrypted connection and requires that the LDAP server holds a trusted certificate or that you import a trusted certificate to the JVM truststore.
* For **LDAP Credentials**, enter the LDAP Distinguished Name (DN) and password for binding to the LDAP Server. Example DN: `cn=administrator,ou=Users,dc=example,dc=com`
<p class="note"><strong>Note:</strong> Pivotal recommends that you provide LDAP credentials that grant read-only permissions on the LDAP Search Base and the LDAP Group Search Base. In addition to this, if the bind user belongs to a different search base, you must use the full DN.</p>
<p class="note warning"><strong>WARNING:</strong> Pivotal recommends against reusing LDAP service accounts across environments. LDAP service accounts should not be subject to manual lockouts, such as lockouts that result from users utilizing the same account. Also, LDAP service accounts should not be subject to automated deletions, since disruption to these service accounts could prevent user logins.
</p>
* For **User Search Base**, enter the location in the LDAP directory tree from which any LDAP User search begins. The typical LDAP Search Base matches your domain name.
<br><br>
For example, a domain named "cloud.example.com" typically uses the following LDAP User Search Base: `ou=Users,dc=example,dc=com`
* For **User Search Filter**, enter a string that defines LDAP User search criteria. These search criteria allow 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 PAS, 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 attributes commonly searched for and returned are `mail`, `uid` and, in the case of Active Directory, `sAMAccountName`.
<p class="note"><strong>Note:</strong> For instructions for testing and troubleshooting your LDAP search filters, see the [Configuring LDAP Integration with Pivotal Cloud Foundry](https://discuss.zendesk.com/hc/en-us/articles/204140418-Configuring-LDAP-Integration-with-Pivotal-Cloud-Foundry-) Knowledge Base article.</p>
* For **Group Search Base**, enter the location in the LDAP directory tree from which the LDAP Group search begins.
<br><br>
For example, a domain named "cloud.example.com" typically uses the following LDAP Group Search Base: `ou=Groups,dc=example,dc=com`
<br><br>
Follow the instructions in the [Grant Admin Permissions to an External Group (SAML or LDAP)](../uaa/uaa-user-management.html#external-group) section of _Creating and Managing Users with the UAA CLI (UAAC)_ to map the groups under this search base to admin roles in PAS.
<p class="note"><strong>Note:</strong> See <a href="../opsguide/external-user-management.html">Adding Existing SAML or LDAP Users to a PCF Deployment</a> to on-board individual LDAP users and map them to PAS Roles.</p>
* For **Group Search Filter**, enter a string that defines LDAP Group search criteria. The standard value is `member={0}`.
* For **Server SSL Cert**, paste in the root certificate from your CA certificate or your self-signed certificate.
* For **First Name Attribute** and **Last Name Attribute**, enter the attribute names in your LDAP directory that correspond to the first and last names in each user record, for example `cn` and `sn`.
* For **Email Attribute**, enter the attribute name in your LDAP directory that corresponds to the email address in each user record, for example `mail`.
* For **Email Domain(s)**, enter a comma-separated list of the email domains for external users who will receive invitations to Apps Manager.
1. For **LDAP Referrals**, select how the UAA handles LDAP server referrals out to other external user stores. The UAA can:
* **Automatically follow any referrals**.
* **Ignore referrals and return partial result**.
* **Throw exception for each referral and abort.**
* Click **Save**.
* Return to the **Installation Dashboard** by clicking the link.
* On the Installation Dashboard, click **Review Pending Changes**, then **Apply Changes**.
<%=image_tag("uaa/apply-changes.png")%>