PingAM 7.5.1

Configure IdPs, SPs, and CoTs

To implement SAML v2.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 AM, a hosted provider is one served by the current AM instance; a remote provider is one hosted elsewhere.

Create a hosted IdP or SP

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

To create other roles, use the /realm-config/federation/entityproviders/saml2 REST endpoint. Learn more about this endpoint in the Online REST API reference.

Use the AM admin UI to create a hosted IdP or SP.

  1. Go to Realms > Realm Name > Dashboard, and click SAML Applications.

  2. Click Add Entity Provider, and select Hosted.

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

    AM 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.

    AM uses the Entity Provider Base URL value for all SAML v2.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.

    Ensure the aliases for providers are unique in a circle of trust and in the realm.

  5. Click Create.

    How do I switch between SP and IdP configuration for a given provider?

    AM only displays the configuration of a single role. 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 (Name in Assertion) to local attribute names.

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

    The default mapping implementation has additional features beyond simply 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. Configure other properties to customize your SAML 2.0 application as required, for example:

    Learn about configuring a hosted provider in:

  8. Save your changes.

  9. You can now export the metadata from your hosted provider.

Export metadata

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

$ curl \
--output metadata.xml \
"https://openam.example.com:8443/openam/saml2/jsp/exportmetadata.jsp\
?entityid=myHostedProvider\
&realm=/mySubRealm"

If you have configured your provider in the Top Level Realm, omit the realm query parameter.

You may also be able to provide the URL in the above example to remote providers, if they can load the metadata by using a URL rather than a file.

Import a remote IdP or SP

The following procedure provides steps for importing and configuring one or more remote entity providers:

  1. Get the entity provider metadata as an XML-formatted file.

  2. Go to Realms > Realm Name > Dashboard, and click SAML Applications.

  3. From the Add Entity Provider drop-down menu, select Remote.

  4. On the New Remote Entity Provider page, perform one of the following steps to import the XML file:

    1. Drag and drop the XML file into the dotted box.

    2. Click within the dotted box to open a file browser to select the XML file.

    You can import multiple remote entities in a single operation, as long as the entity ID is unique within each.

    Note that AM 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.

  5. 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.

  6. Click Create.

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

    How do I switch between SP and IdP configuration for a given provider?

    AM only displays the configuration of a single role. Click on the labels to select the role view:

    saml-roles

    Customize your SAML 2.0 application as required, for example, to Sign and encrypt messages.

    Learn about configuring a remote provider in:

Create a circle of trust (CoT)

A CoT is an AM concept that groups at least one IdP and at least one SP who agree to share authentication information.

  1. Go to Realms > Realm Name > Applications > Federation > Circles of Trust, and click Add Circle of Trust.

  2. Provide 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 add entity providers later if you haven’t created them yet.

  4. Customize any other properties as required and save your changes.

    Learn about configuring a CoT in CoT configuration.