The Pega 7 Platform can be configured as a SAML 2.0 service provider (SP) by selecting the Type SAML 2.0 when creating a new Authentication Service record. Select one of the names: SAMLAuth, SAMLAuth1, or SAMLAuth2 to use the built-in web contexts sso, sso1, or sso2, respectively.

Creating an Authentication Service

When configuring the Pega 7 Platform as a Service Provider (SP), update the web.xml file with servlet context if a new authentication service is created with any user-defined name.

The following steps explain how to configure the Pega 7 Platform as an SP by using the Authentication Service form.

1. Import IdP metadata by using the IdP metadata endpoint or the file option. In the Authentication Service form, the Pega 7 Platform automatically maps the values from IdP metadata to the fields in the form. The Pega 7 Platform also imports the certificate from the metadata and maps it to the Verification certificate.

Importing IdP metadata

2. Determine if any actions are required for the following fields:

• The Entity Identification (Issuer) field should not be edited until it is changed in the IdP side.
• In the Login (SSO) protocol binding menu, select HTTP POST, HTTP Redirect, or HTTP Artifact.
• The corresponding endpoint for the selected binding is displayed in the Login location field. The SP uses the login location to send the SAML request to the IdP to initiate single sign-on.
• In the Logout (SLO) protocol binding menu, select SOAP or HTTP Redirect.
• The system fetches the endpoint for the Logout location in the Authentication Service form. During run time, the selected binding and corresponding location are used to send the logout request to the IdP.
• The Artifact Resolution Service (ARS) location field is used by the SP to send the artifact resolve request to the IdP if HTTP artifact binding is selected for the Login (SSO) protocol binding under Service Provider (SP) settings.​
• For secure logout and ARS locations, the system uses the certificate in the TLS/SSL truststore field to verify the server credentials in a TLS/SSL handshake. You must provide a truststore if the truststore of your JVM does not contain the TLS/SSL certificate.

Completing IdP provider information

3. By default, the <AuthenticationServiceruleName>IDPCertStore keystore instance is created while importing the metadata with the certificate from the IdP metadata. The Certificate store can be modified, and you can select the Certificate alias from the keystore.

4. In Service Provider (SP) settings on the Authentication Service form, Entity Identification is a unique value to identify the authentication service both in the SP and also in the IdP side. Modifying Entity Identification requires communicating with the IdP administrator using the modified entity ID.

5. ​Endpoints for Assertion Consumer Service, Artifact Resolution Service, and the logout locations for redirect and SOAP bindings are displayed automatically in the Authentication Service form. You can modify the Protocol, Hostname, and Port details for the endpoints, and check that the context path is intact. To undo the changes for the entity IdP and endpoints, click the Reset button.
6. Select the HTTP POST or HTTP Artifact binding under Login (SSO) protocol binding. At run time, the SP sends the binding information and endpoint as part of the SAML request to the IdP.
7. Signing and decryption certificates can be provided in the Authentication Service form, and selecting the Disable request signing check box disables the request signing during run time. The enable or disable signing option is applicable for both authentication request and logout request.
8. Click Download SP metadata to export the metadata information that is configured in the form. SP metadata can be accessed by using the REST URL:
   http://<hostname:port>/prweb/PRRestService/WebSSO/SAML/SPMetadata/<AuthenticationServicerule>

Best practices for configuring single sign-on

With the supported configurations in the authentication service, the Pega 7 Platform supports a number of possible SSO profile variations of SAML Request and Response by fully enabling the following SP-initiated and IdP-initiated flows:

SP-Initiated SSO

• POST-POST
• Redirect-POST
• Artifact-POST
• POST-Artifact
• Redirect-Artifact
• Artifact-Artifact

​IdP-Initiated SSO

• POST
• Artifact

Optimal configuration

POST-POST is the optimal configuration to achieve SSO for a Pega 7 Platform application to avoid the direct communication between the SP and IdP. Artifact binding can be considered to add more secure conversation between the IdP and SP and to avoid the user agent in between to pass the SAML assertions. In artifact binding, the IdP and SP exchange the SAML messages over the backend calls (SOAP).