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
201 lines (135 loc) · 11.6 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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
---
breadcrumb: Pivotal Cloud Foundry Documentation
title: Configuring Authentication and Enterprise SSO for Elastic Runtime
owner: Identity
---
<strong><%= modified_date %></strong>
This topic describes [Pivotal Cloud Foundry](https://network.pivotal.io/products/pivotal-cf) (PCF) 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 Elastic Runtime 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](../opsguide/external-user-management.html) topic for information
about managing user identity and pre-provisioning user roles with SAML or LDAP
in PCF.
This [Knowledge Base article](https://discuss.zendesk.com/hc/en-us/articles/204140418-Configuring-LDAP-Integration-with-Pivotal-Cloud-Foundry-) explains the process used by the UAA
Server when it attempts to authenticate a user through LDAP.
##<a id="configure-saml"></a>Configure PCF to Use a SAML Identity Provider
To connect PCF Elastic Runtime with SAML, you must perform the following tasks:
1. [Configure PCF as a service provider for SAML](#configure-pcf-for-saml)
2. [Configure SAML as an Identity Provider for PCF](#configure-saml-for-pcf)
###<a id="configure-pcf-for-saml"></a>Configure PCF as a Service Provider for SAML
Follow the instructions below to configure PCF as a service provider for SAML.
1. From the **Installation Dashboard**, click the **Elastic Runtime** 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. Refer to the [Configure SAML Identity Provider for PCF](#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>: Refer to the <a href="../opsguide/external-user-management.html">Adding Existing SAML or
LDAP Users to a PCF Deployment</a> topic for information about on-boarding SAML users and mapping them to PCF user roles.</p>
1. Select the **Name ID Format** for your SAML Identity Provider. This translates to `username` on PCF Elastic Runtime. 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 PCF, follow the instructions in the [Grant Admin Permissions to an External Group (SAML or LDAP)](../adminguide/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 PCF 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. For **Signature Algorithm**, choose an algorithm from the dropdown menu to use for signed requests and assertions. The default value is `SHA1`.
1. Click **Save**.
1. Return to the **Installation Dashboard** by clicking the link.
1. On the Installation Dashboard, click **Apply Changes**.
<%=image_tag("uaa/apply-changes.png")%>
###<a id="configure-saml-for-pcf"></a>Configure SAML as an Identity Provider for PCF
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 PCF:
<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="./images/CASM-PivotalCloudFoundryFederationRunbook-ver1.0.pdf">PDF</a></td>
</tr>
<tr>
<td><a href='https://www.pingidentity.com/en/products/pingfederate.html'>Ping Federate</a></td>
<td><a href="./images/PingFederate-PCF-SSO-Runbook.pdf">PDF</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="./images/ADFS-PCF-SSO-Runbook.pdf">PDF</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 PCF
To integrate the UAA with one or more LDAP servers, configure Elastic Runtime with your LDAP endpoint information as follows:
1. Log into the Operations Manager web interface.
1. On the Product Dashboard, select **Pivotal Elastic Runtime**.
<%=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**.
1. For **Server URL**, enter the URL(s) that point your LDAP server(s). 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.
1. 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.</p>
1. 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`
1. 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 Elastic
Runtime, 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>: This [Knowledge Base article](https://discuss.zendesk.com/hc/en-us/articles/204140418-Configuring-LDAP-Integration-with-Pivotal-Cloud-Foundry-) provides instructions for testing and troubleshooting your LDAP search filters.</p>
1. 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)](../adminguide/uaa-user-management.html#external-group) section
of the _Creating and Managing Users with the UAA CLI (UAAC)_ topic to map the
groups under this search base to admin roles in PCF.
<p class="note"><strong>Note</strong>: Refer to the <a href="../opsguide/external-user-management.html">Adding Existing SAML or LDAP Users to a PCF Deployment</a> topic to on-board individual LDAP users and map
them to PCF Roles.</p>
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.
1. If you are using `ldaps://` with a self-signed certificate, enter a Subject Alternative Name for your certificate under **Server SSL Cert AltName**. Otherwise, leave this field blank.
1. 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`.
1. For **Email Attribute**, enter the attribute name in your LDAP directory that corresponds to the email address in each user record, for example `mail`.
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 **LDAP Referrals**, choose how the UAA handles LDAP server referrals out to other external user stores. The UAA can follow the external referrals, ignore them without returning errors, or throw an error for each external referral and abort the authentication.
1. Click **Save**.
1. Return to the **Installation Dashboard** by clicking the link.
1. On the Installation Dashboard, click **Apply Changes**.
<%=image_tag("uaa/apply-changes.png")%>