PingOne Advanced Identity Cloud

Configure IdPs, SPs, and CoTs

To implement SAML 2.0 in AM, you share metadata for your hosted providers with other remote providers in a circle of trust (CoT).

You must also configure remote providers by importing their metadata.

In Advanced Identity Cloud, a hosted provider is one served by the current Advanced Identity Cloud tenant, and a remote provider is one hosted elsewhere.

Create a hosted IdP or SP

A hosted IdP or SP is a provider hosted within Advanced Identity Cloud. For example, if Advanced Identity Cloud is the authoritative source for users to a downstream application, then you would configure Advanced Identity Cloud to be a hosted IdP.

With application management, Advanced Identity Cloud acts as a hosted IdP through intuitive screens. Learn more in Create a custom SAML 2.0 application.

This procedure provides steps for creating a hosted IdP or SP:

  1. In Native Consoles > Access Management, go to Realms > Realm Name > Dashboard, and click SAML Applications.

  2. Click Add Entity Provider > Hosted.

  3. Enter an Entity ID, and verify the Entity Provider Base URL value is correct.

    Advanced Identity Cloud truncates sequences of whitespace with a single whitespace character in values such as entity IDs. For example, if MyEntityID value (with one space) exists already, and you add a new entity, My Entity ID value (same name but multiple spaces), then AM will throw an error because the string values are treated as identical.

    Advanced Identity Cloud uses the Entity Provider Base URL value for all SAML 2.0 related endpoints, so ensure other entities in your SAML deployment are able to access the specified URL.

  4. In the Meta Aliases section, provide a URL-friendly value in either the Identity Provider Meta Alias, the Service Provider Meta Alias property, or both.

    The aliases for providers must be unique in a circle of trust and in the realm.

  5. Click Create.

    The UI only displays the configuration of a single role. To switch between SP and IdP configuration for a given provider, click on the labels to select the role view:

    saml-roles

  6. On the Assertion Processing tab, in the Attribute Mapper section, map SAML attribute names to local attribute names. The SAML attribute names are the names in an assertion.

    In this example, we map the SalesForce IDPEmail SAML attribute to the local mail attribute.
    Figure 1. Mapping SAML attributes to local attributes

    The default mapping implementation has additional features beyond retrieving string attributes from the user profile:

    • Add an attribute that takes a static value by enclosing the profile attribute name in double quotes (").

      For example, you can add a static SAML attribute called partnerID with a value of staticPartnerIDValue by adding partnerID as the SAML Attribute with "staticPartnerIDValue" as the Local Attribute name.

    • Select the binary option when dealing with binary attribute values; for example, values that are Base64 encoded.

    • Use the optional Name Format Uri property as required by the remote provider. For example, you may need to specify urn:oasis:names:tc:SAML:2.0:attrname-format:uri.

  7. If you are adding a new attribute map, click Add. If you are updating an existing attribute map, click Update.

  8. Customize any other properties as required, and click Save Changes at the bottom of the screen.

    For in-depth information about hosted IdP and SP properties, refer to:

  9. Export the XML-based metadata from your hosted provider to share with other providers in your circle of trust.

Export provider metadata

SAML 2.0 metadata is an XML document that contains the necessary information to transmit an agreement between identity providers (IdPs) and service providers (SPs). It contains information on setting up federation (through NameID) and specifies the locations of various services. The SAML 2.0 metadata contains settings such as endpoint URLs, supported bindings, identifiers, and public keys.

Exporting SAML 2.0 metadata from PingOne Advanced Identity Cloud lets you share metadata with other entity providers and can be useful for troubleshooting your configuration.

You can access the SAML 2.0 metadata for your entity provider in two ways:

Over REST

Run the following command, including an output filename, the entity provider ID, and the realm:

$ curl \
--output <metadata.xml> \
"https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?\
entityid=<entityid>&realm=/<realm>"
bash
In a browser

Open your tenant environment’s metadata URL in a browser, specifying the entity provider ID and the realm in the following format:

https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=<entityid>&realm=/<realm>
bash

Import a remote IdP or SP

A remote IdP or SP is a provider outside of Advanced Identity Cloud. For example, Azure AD could be the authoritative source for a user profile in your organization. If that’s the case, then Azure AD would be a remote IdP.

The following procedure provides steps for importing and configuring one or more remote IdP or SPs:

  1. Get the remote IdP or SP metadata as an XML-formatted file.

  2. Import the metadata in one of the following ways:

    In the Advanced Identity Cloud admin console

    1. Go to Native Consoles > Access Management > Realms > Realm Name > Dashboard and click SAML Applications.

    2. Click the Add Entity Provider drop-down button, and click Remote.

    3. On the New Remote Entity Provider page, either:

      • Drag and drop the XML file into the box, or

      • Click the box to open a file browser and select the XML file.

    4. If you have already created a circle of trust, you can add the remote providers into one or more of them by using the Circles of Trust property.

    5. Leave the Update Type as empty or set to CREATE.

    6. Click Create.

    Over REST

    1. Convert the XML metadata to a base64url-encoded string.

    2. Get an access token.

    3. Run the following command, specifying the access token and the base64url-encoded metadata:

      $ curl \
--request POST \
--header 'authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--data-raw '{"standardMetadata": "<base64url-encoded metadata>"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/saml2/remote?_action=importEntity'
      bash

    You can import multiple remote entities in a single operation as long as the entity IDs are unique.

    Advanced Identity Cloud truncates sequences of whitespace with a single whitespace character in values such as entity IDs. For example, if ID value (with one space) exists already, a new entity with the same name but multiple spaces would result in an error because the string values are treated as identical.

  3. To edit the configuration of an entity provider, go to Realms > Realm Name > Applications > Federation > Entity Providers, and select the entity provider to edit.

    The UI only displays the configuration of a single role. To switch between SP and IdP configuration for a given provider, click on the labels to select the role view:

    saml-roles

    Learn more about remote entity provider properties in:

Update remote SP certificate

To update all the metadata for a remote IdP or SP, you can import the metadata again. Reimporting the metadata deletes and recreates the entity provider, overwriting all existing provider settings with the values in the metadata XML file.

However, if you only want to update the signing and encryption certificate used by the SP to sign the authentication request without losing existing settings, follow these steps:

  1. Get the SAML 2.0 SP metadata with the updated signed certificate.

    You can find information about exporting provider metadata XML in Export provider metadata.

  2. Update the certificate in one of the following ways:

    In the AM admin console

    1. Import the metadata.

      On the New Remote Entity Provider page, make sure you choose UPDATE_CERTIFICATES as the Update Type.

    2. Click Create.

    Over REST

    1. Convert the XML metadata to a base64url-encoded string.

    2. Get an access token.

    3. Run the following REST API command, specifying the access token and the base64url-encoded SP metadata XML.

      $ curl \
--request POST \
--header 'authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--data-raw '{
    "standardMetadata": "<base64url-encoded metadata>",
    "updateType": "UPDATE_CERTIFICATES"
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/saml2/remote?_action=importEntity'
{"importedEntities":["myProvider"]}
      bash

Configure a SAML 2.0 application journey

Configure the remote SP so that a specific authentication journey is always run for users authenticating with your SAML 2.0 app. The federation flow invokes the associated journey regardless of any existing sessions or requested or configured authentication contexts.

To configure a SAML 2.0 app journey, enable the option to Use a journey to authenticate users to this application when you set up single sign-on.

When you configure an app journey, the processing of the SAML 2.0 request depends on the authentication context requested by the SP. The following table shows the SAML response for each comparison type and the requested authentication context.

Authentication context Comparison type Response

SP requested authn context

Exact / None

Requested authn context included

SP requested authn context

Better / Maximum / Minimum

UNSPECIFIED

SP doesn’t request authn context

-

UNSPECIFIED

IDP-initiated (no requested authn context)

-

UNSPECIFIED

You can’t delete a journey if it’s referenced by a SAML 2.0 app.

Create a circle of trust (CoT)

A CoT groups at least one IdP and at least one SP who agree to share authentication information.

With application management, you can use intuitive screens to create trusted agreements between providers through SAML 2.0 applications.

Learn more in Create a custom SAML 2.0 application.

  1. In Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Circles of Trust, and click Add Circle of Trust.

  2. Enter a name, and click Create.

  3. On the Circle of Trust page, in the Entity Providers property, select at least one IdP and one SP.

    You can create IdPs and SPs at any time and add them later on.

  4. Customize any other properties as required, and click Save Changes.

    Learn about CoT configuration in CoT configuration.