In this use case, you need to support consumer registration where users complete a self-service registration process to create their accounts and then access resources protected by multiple service providers. For a registration to complete successfully, a user must provide an email address, a first name, a last name, an optional mobile phone number, and a password. The email address is the user identifier. All attributes are sent to the service providers as per the partner agreements.
Additionally, this use case must also allow users to take advantage of their existing accounts at ACME, a major social network, for registration and authentication. It happens that you have already established an IdP connection to this social network, from which you received the same set of attributes: SAML_SUBJECT for the user's email address, ssoFirstName, ssoLastName, and ssoMobile.
For registration, you can optionally allow users to leverage their existing identities from third-party identity providers. Any identity provider (IdP) connection or IdP adapter, such as the LinkedIn Cloud Identity Connector, can be used as an authentication source to a third-party identity provider.
Using the Administrative console, enable third-party IdP. This configuration involves the same five components to set up registration, plus the IdP connections or IdP adapter instances to connect with the third-party identity providers. This capability enables a mapping configuration between the attributes returned by the identity provider and the fields within the registration page, streamlining the registration process. See the following configuration steps.
- IdP connections or IdP adapter instances
- A PingDirectory installation (step 1)
- An authentication policy contract (step 2)
- A local identity profile (step 3)
- An HTML Form Adapter instance (step 4)
- An IdP authentication policy (step 5)
If you know how to set up PingDirectory to connect with PingFederate and an authentication policy contract shown in Setting up self-service registration, you can skip to step 3 to create a local identity profile.
- Install PingDirectory.
-
Create an authentication policy contract.
- Go to Authentication > Policies > Policy Contracts.
- In the Policy Contracts window, click Create New Contract.
- On the Contract Attributes tab, in the Extend the Contract field, extend the authentication policy contract with three additional attributes, such as firstName, lastName, and mobileNumber.
- After each entry add, click Add. Click Next.
- On the Summary tab, review your changes. Click Done.
- In the Policy Contracts window, click Save.
For more information, see Managing policy contracts. -
Create a local identity profile using the Authentication > Policies > Local Identity Profiles. Click Create New Profileto access the
Local Identity Profile window and configuration wizard.
- On the Profile Info tab, enter a name in theLocal Identity Profile Name field, select the authentication policy from step 2, and select the Enable Registration check box. Click Next.
-
On the Authentication Sources tab, enter
ACME
in the Authentication Source field. Click Add.Note:To support additional third-party identity providers, enter a value for each. At runtime, the sign-on page displays them in the order defined on this window.
Tip:If you know how to set up a local identity profile and an HTML Form Adapter instance for customer identities shown in Setting up self-service registration), you can skip to step 5 to create an IdP authentication policy.
-
On the Fields tab, define four local identity fields
as shown in the following table.
Type
ID
Label
Parameters
Email
lipEmail
Email address
Select the Required and Unique ID check boxes.
Note:The Unique IDcheck boxes are on the Fields tab.
Text
lipFirstName
First name
Select the Required check box.
Text
lipLastName
Last name
Select the Required check box.
Phone
lipMobile
Mobile number
None required.
As needed, select the Mask Log Values check box for any of the four local identity fields, and select the Mask all OGNL-expression generated log values check box for all fields.
- On the Email Verification tab, click Next.
- On the Registration tab, click Next.
- On the Data Store Configuration tab, click Configure Data Store.
- In the Data Store Configuration window, on the Data Store tab, from the Data Store list, select the LDAP datastore that has been set up to connect to your PingDirectory. Click Next.
- In the Data Store Configuration window, on the LDAP Configuration tab, specify the branch of your directory hierarchy where you want PingFederate to store customer identities in the Base DN field and the LDAP attributes to be associated with fields defined in this local identity profile under Attribute.
-
In the Data Store Configuration window, on the
Identity Creation tab, define the RDN pattern in the
Relative DN Pattern field, and select your object, such as
class aPerson for this sample use case, from the Object
Class list.
The pattern is as follows.
attribute1=value1[, ..., attributeN=valueN]
If you want to use the ${entryUUID} variable to guarantee the uniqueness of the relative DNs for all users, you must use it with the entryUUID LDAP attribute.
entryUUID=${entryUUID}
-
In the Data Store Configuration window, on the Data
Store Mapping tab, configure the mapping between the local identity
profile fields and the datastore attributes. See the following table.
Mapping entries for local identity profile fields and datastore attributes Field Data Store Attribute lipEmail mail lipFirstName givenName lipLastName sn lipMobile mobile - In the Data Store Configuration window, on the Summary tab, click Done.
- On the Summary tab of the local identity profile, click Save.
For more information, see Configuring local identity profiles.
-
Configure an HTML Form Adapter instance for customer identities.
- Go to the Authentication > Integration > IdP Adapters.
- Create a new HTML Form Adapter instance or reuse an existing one by clicking its name.
- On the IdP Adapter tab, in the Password Credential Validator Instance section add the LDAP Username Password Credential Validator instance that has been set up to validate credentials stored on your PingDirectory.
- On the IdP Adapter tab, select the newly created local identity profile in the Local Identity Profile list.
- Complete the rest of the configuration and save all changes.
(For more information, see Configuring the HTML Form Adapter for customer identities.) -
Create an IdP authentication policy.
- Go to the Authentication > Policies > Policies.
- Under Policy, select the HTML Form Adapter instance configured in step 4.
-
In the Policy window, under the
Value section, select the drop-down arrow to show the
Fail and Success fields.
- For the Fail path, select Done.
- For the Success path, select the local identity profile created in step 3. Click Done.
-
Click Local Identity Mapping underneath the selected
local identity profile, which opens the Inbound Mapping &
Contract Fulfillment configuration wizard.
Note:
The next few steps configure the fulfillment of the authentication policy contract for the scenario where users choose to register directly without going through ACME.
Tip:If you know how to setup the inbound mapping and contract fulfillment of an authentication policy contract through a local identity profile shown in Setting up self-service registration, you can skip to step i to create a rule for the scenario where users choose to register and subsequently authenticate via ACME.
-
On the Inbound Mapping & Contract Fulfillment
Inbound Mapping window, configure the
pf.local.identity.unique.id built-in local identity field for
the registration process.
At runtime, PingFederate fulfills the value of the pf.local.identity.unique.id built-in local identity field based on this configuration and passes the value to PingDirectory. PingDirectory uses this value to determine whether such identity has already been created. The pf.local.identity.unique.id field value should therefore be mapped from the subject identifier of the preceding authentication source, namely the username attribute from the HTML Form Adapter.
For this sample use case, configure the Inbound Mapping window as in the following table.
Inbound Mapping Fulfillment Source Value pf.local.identity.unique.id Adapter username - On the Attribute Sources & User Lookup tab, click Next.
- On the Attribute Sources & User Lookup tab, click Next.
- On the Issuance Criteria tab, click Next.
-
On the Inbound Mapping & Contract Fulfillment > Summary window, click Done.
The Inbound Mapping & Contract Fulfillment configuration wizard brings back the Manage Authentication Policies window.Note:
The remaining steps configure the fulfillment of the authentication policy contract for the scenario where users choose to register and subsequently authenticate through ACME.
- Click Rules underneath the Success path of the HTML Form Adapter instance.
-
On the Rules dialog, create a policy path for users
who choose to register and authenticate via ACME. For this sample use case,
configure as in the following table.
Authentication policy rules fields and entries Attribute Name
Condition
Value
Result policy.action
equal to
ACME
Important:The value here must match the value defined on the Authentication Sources window. See step 3b.
ACME users The Result field controls the label shown for the policy path of this rule. The value does not need to match the value defined on the Authentication Sources window.
Important:If you have defined multiple third-party identity providers on the Authentication Sources window, you must repeat these steps to add a policy.action rule to create a policy path for each.
In addition, select the Default to Success check box, the default behavior. When selected, the Success path remains, which is important for this sample use case where users are free to choose whether to register and subsequently authenticate via ACME.
When finished, click Done, which brings you back to the Authentication Policies window.
-
For the ACME users path, select the IdP connection to
ACME under Action.
Tip:
Generally speaking, any IdP adapter instance or IdP connection that connects to the third-party identity provider can be used here.
- For its Fail path, select
Done.Note:
If you have defined multiple third-party identity providers and added rules to create a policy path for each, you may select Restart. The Restart policy action provides users the opportunity to do over. When triggered, the policy engine routes the requests back to the first checkpoint of the invoked authentication policy.
By selecting Restart for the Fail path, you give users the opportunity to choose another third-party identity provider when they fail to authenticate through ACME.
Undesirable looping behaviors can occur if you select Restart for the Fail path at the root of an authentication policy tree. PingFederate mitigates this risk by automatically limiting the number of policy restarts per transaction.
- For its Success path, select the local identity profile created in step 3.
- For its Fail path, select
Done.
- Click Local Identity Mapping underneath the selected IdP connection, which opens the Inbound Mapping & Contract Fulfillment configuration wizard.
-
On the Inbound Mapping & Contract
FulfillmentInbound Mapping window,
configure the pf.local.identity.unique.id built-in local
identity field for the registration process and optionally other fields so that
PingFederate can pre-populate values for these fields on the registration
page.
At runtime, PingFederate fulfills the value of the pf.local.identity.unique.id built-in local identity field based on this configuration and passes the value to PingDirectory. PingDirectory uses this value to determine whether such identity has already been created. The pf.local.identity.unique.id field value should therefore be mapped from the subject identifier of the preceding authentication source, namely the subject identifier from the IdP connection.
For this sample use case, the Inbound Mapping window is configured as in the following table.
Inbound Mapping fields and entries Inbound Mapping Fulfillment
Source
Value
pf.local.identity.unique.id
IdP Connection
SAML_SUBJECT
lipEmail
IdP Connection
SAML_SUBJECT
lipFirstName
IdP Connection
ssoFirstName
lipLastName
IdP Connection
ssoLastName
lipMobile
IdP Connection
ssoMobile
- On the Attribute Sources & User Lookup tab, click Next.
- On the Attribute Sources & User Lookup tab, click Next.
- On the Issuance Criteria tab, click Next.
-
On the Inbound Mapping & Contract Fulfillment
Summary tab, click Done.
The Inbound Mapping & Contract Fulfillment configuration wizard brings back the Manage Authentication Policies window.Important:
If you have defined multiple rules, each forming a policy path for a third-party identity provider, ensure you complete the Inbound Mapping & Contract Fulfillment configuration for each of them.
-
In the Policies window, on the
Policies tab, select the IdP
Authentication Policies check box.
Note:
Other IdP authentication policies, if any, are enabled as well.
- Click Save to keep your changes.
For more information, see Applying policy contracts or identity profiles to authentication policies.
You have now successfully set up self-service registration with an option for users to register and subsequently authenticate via ACME. When users sign on through this HTML Form Adapter instance, they have two registration options:
- Click the Register now link, fill in the registration page, and register.
- Click the social sign-on link, authenticate via ACME, review the registration page, and register.
Based on the configuration of this sample use case, the following screen capture of a sign-on page is presented.
If you have added Facebook, Google, LinkedIn, and Twitter as the authentication sources, the following sign-on page is presented.
Suppose a user chooses to register through ACME. Once authenticated and redirected back to PingFederate, PingFederate pre-populates the registration page with values it receives from ACME, as illustrated in this screen capture.
This registration option streamlines the self-service registration process.