PingAM 7.5.0

Reference

This reference section covers service provider, identity provider, and circle of trust configuration properties. For the global services reference, see Reference.

Hosted identity provider configuration properties

After you have set up a hosted identity provider (IdP), you can configure it through the AM admin UI under Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion content

The following groups appear on the Assertion Content tab:

Signing and Encryption
Request/Response Signing

Specifies which parts of messages the identity provider requires the service provider to sign digitally.

Encryption

When selected, the service provider must encrypt NameID elements.

Secret Label and Algorithms
Secret Label Identifier

An identifier for the secret label AM uses for this entity provider when resolving secrets.

For example, if you set this value to demo, the entity provider uses the following secret labels:

  • am.applications.federation.entity.providers.saml2.demo.signing

  • am.applications.federation.entity.providers.saml2.demo.encryption

If not specified, AM uses the entity provider role-specific, default global secret labels. Learn more in Secret label mappings for SAML v2.0 signing and encryption.

Signing Algorithm

The algorithms the provider can use to sign the request/response attributes selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Digest Algorithm

The digest algorithms the provider can use when signing the requests and responses selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Encryption Algorithm

This field specifies two types of encryption algorithms for the provider:

  • Symmetric algorithms, which the provider can use to encrypt the objects selected in the Encryption group. Select one or more AES algorithms from the drop-down list.

    Default: http://www.w3.org/2001/04/xmlenc#aes128-cbc

  • Asymmetric algorithms, advertised as the provider’s transport key algorithm. When SAML 2.0 token encryption is enabled, hosted providers should use the algorithm the remote provider is advertising when encrypting symmetric encryption keys.

    Select one or more algorithms from the list:

    Key transport algorithms
NameID Format
NameID Format List

Specifies the supported name identifiers for users that are shared between providers for single sign-on (SSO).

The following diagram shows how the hosted IdP decides which of the supported NameID formats is used:

nameid-format-flow-hosted-idp
NameID Value Map

Maps name identifier formats to user profile attributes. The persistent and transient name identifiers don’t need to be mapped.

NameID mapping supports Base64-encoded binary values. With this flag set, AM Base64-encodes the profile attribute when adding it to the assertion.

Authentication Context
Mapper

Specifies a class that implements the IDPAuthnContextMapper interface and sets up the authentication context.

Default value: com.sun.identity.saml2.plugins.DefaultIDPAuthnContextMapper

Authentication Context

Specifies the authentication context classes the IdP supports, and any AM authentication mechanisms that are used when an SP specifies the respective class in a SAML 2.0 authentication request.

  • The Predefined Reference list specifies the list of context references.

  • The Key list specifies the authentication mechanism that AM uses when an SP specifies an authentication context class in a SAML 2.0 authentication request.

    Authentication Mechanisms Reference for the Key List
    Service

    AM uses the specified authentication chain or tree to authenticate the user.

    For example, in the Value field, enter HmacOneTimePassword to use the built-in one-time passcode (OTP) example authentication tree, or ldapService to use the built-in chain that authenticates against the default identity store.

    Module

    AM uses the specified authentication module to authenticate the user.

    Authentication Level

    AM authenticates the user with a method that has an associated authentication level equal to or higher than the specified value.

    If there is more than one suitable method, AM presents the available options by using a ChoiceCallback.

    Learn more about using and returning callbacks during authentication in Authenticate over REST.

    The Role, User, and Resource URL options are deprecated and should not be used.

  • The Value field specifies the name relative to the authentication mechanism you chose in the previous step. For example, if you chose the Service authentication mechanism, add the name of an authentication tree or chain in the Value field.

  • The Level field specifies the numeric value of precedence of the supported context reference classes.

    Classes with higher numbers are considered stronger than lower numbered classes. The values determine which authentication classes can be used when the SP makes an authentication request that uses a comparison attribute; for example, minimum or better.

    Note that the value in the Level field should match the auth level of the specified chain, module, or tree. For example, if the specified authentication chain sets an auth level of 10, set the same value in the Level field in the Authentication Context table. Because AM compares the current auth level against the level specified in Authentication Context table, if the two values do not match, AM could require a logged in user to re-authenticate unnecessarily.

    Example
    Choose the authentication mechanisms AM uses when receiving authentication requests that specify an authentication context class.

    Learn more about authentication context classes in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard.

    Default value: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

Assertion Time
Not-Before Time Skew

Grace period in seconds for the NotBefore time in assertions.

Effective Time

Validity in seconds of an assertion.

Basic Authentication
Enabled, User Name, Password

When enabled, authenticate with the specified user name and password at SOAP endpoints.

Assertion Cache
Enabled

When enabled, cache assertions.

Assertion processing

The following properties appear on the Assertion Processing tab:

Attribute Mapper
Attribute Mapper Plugin

This extension point is used to map the IdP attributes that are inserted into the SAML assertion.

The plugin can be implemented either in JavaScript or as a Java class. If defined, the scripted implementation takes precedence, otherwise AM invokes the Attribute Mapper class.

Learn more in IDP attribute mapper.

The following plugin properties determine which implementation is used:

Attribute Mapper

Specifies the Java class for the Attribute Mapper plugin. This class is not invoked if a script is selected for Attribute Mapper Script.

Default: com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper

Attribute Mapper Script

Specifies the scripted implementation of the Attribute Mapper plugin.

Select from a list of all the Saml2 IDP Attribute Mapper type scripts saved to this realm, including the default template script, SAML2 IDP Attribute Mapper Script.

You can find details in saml2-idp-attribute-mapper.js.

Attribute Map

Maps SAML attributes to user profile attributes.

The user profile attributes used here must both be allowed in user profiles, and also be specified for the identity repository.

See Adding User Profile Attributes, for instructions on allowing additional attributes in user profiles.

To see the profile attributes available for an LDAP identity repository, log in to the AM admin UI, and go to Realms > Realm Name > Identity Stores > User Configuration. Check the LDAP User Attributes list.

The default IDP mapping implementation allows you to add static values in addition to values taken from the user profile. You add a static value by enclosing the profile attribute name in double quotes ("), as in the following example:

Example of Static Attribute Mapping. Notice that the static value is enclosed in double quotes.
Account Mapper
Account Mapper

Specifies a class that implements AccountMapper to map remote users to local user profiles.

Disable NameID Persistence

Disables the storage of the NameID values in the identity repository for all NameIDs issued by the IdP instance as long as the NameID format is anything but the persistent NameID format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent. That is, you can disable the storage of NameID values with persistent NameID-Format if and only if there is a NameID value mapping set up for the NameID-Format.

By preventing the storage of the NameID values, the ManageNameID and the NameIDMapping SAML profiles will no longer work when using any persistent NameID formats. Existing account links that have been established and stored are not removed when disabling NameID persistence.

Default value: false

Local Configuration
Auth URL

If present, overrides the default UI login URL used to authenticate users during federation.

Use this property to specify an alternative URL for authenticating users, for example, if you have created a custom user interface other than the UI.

The specified authentication URL is responsible for authenticating the federated user and must establish a session in AM, and return the SSO token value in the configured cookie name, usually iPlanetDirectoryPro.

The domain of the authentication URL must be configured in AM so that the cookie is accepted, and if host cookies are configured in AM, then the fully qualified domain name of the authentication URL must be identical to that of the AM instance.

Learn more about configuring the domains AM accepts in the SSO cookies in Change the cookie domain.

AM redirects users to the URL specified and appends a goto parameter. The parameter contains the URL the user must be redirected to after authentication. The specified authentication URL must not override the goto parameter, as that would redirect the user elsewhere and federation will fail.

Learn more in Success and failure redirection URLs.
Reverse Proxy URL

When a reverse proxy is used for SAML endpoints, it is specified here.

External Application Logout URL

URL to which to send an HTTP POST including all cookies when receiving a logout request. To add a user session property as a POST parameter, include it in the URL query string as a appsessionproperty parameter.

Services

The following properties appear on the Services tab:

MetaAlias
MetaAlias

Used to locate the provider’s entity identifier, specified as [/realm-name]*/provider-name, where provider-name cannot contain slash characters (/). For example: /myRealm/mySubrealm/idp.

Ensure the MetaAlias is unique for each provider configured in a CoT and in the realm.

IDP Service Attributes
Artifact Resolution Service

Specifies the endpoint to manage artifact resolution. The Index is a unique number identifier for the endpoint.

Single Logout Service

Specifies the endpoints to manage single logout (SLO), depending on the SAML binding selected.

Manage NameID Service

Specifies the endpoints to manage name identifiers, depending on the SAML binding selected.

Single SignOn Service

The endpoints to manage SSO.

These endpoints are used only for SP-initiated flows but are included as a requirement of the SAML V 2.0 Metadata specification.

Assertion ID Request Service

Specifies the endpoints to request for an specific assertion by referring to its assertion ID.

NameID Mapping
URL

Specifies the endpoint to manage name identifier mapping.

Advanced settings

The following properties appear on the Advanced tab:

SAE Configuration
IDP URL

Specifies the endpoint to manage Secure Attribute Exchange requests.

Application Security Configuration

Specifies how to handle encryption for Secure Attribute Exchange operations.

ECP Configuration
IDP Session Mapper

Specifies the class that finds a valid session from an HTTP servlet request to an identity provider with a SAML Enhanced Client or Proxy profile.

Session Synchronization
Enabled

When enabled, the identity provider sends a SOAP logout request over the back channel to all service providers when a session times out. A session can time out when the maximum idle time or maximum session time is reached, for example.

IDP Finder Implementation
IDP Finder Implementation Class

Specifies a class that finds the preferred identity provider to handle a proxied authentication request.

IDP Finder JSP

Specifies a JSP that presents the list of identity providers to the user.

Enable Proxy IDP Finder For All SPs

When enabled, apply the finder for all remote service providers.

Relay State URL List
Relay State URL List

List of URLs permitted for the RelayState parameter. For SLO operations, AM validates the redirection URL in the RelayState parameter against this list. If the RelayState parameter’s value is in the list, AM allows redirection to the RelayState URL. If it is not in the list, a browser error occurs.

Use the pattern matching rules described in Success and failure redirection URLs to specify URLs in the list.

If you do not specify any URLs in this property, AM only allows redirection to RelayState URLs that match the domain of the instance. Any other URL will cause a browser error.

This property does not apply to IdP-initiated SSO, where the validation of the RelayState parameter should be performed on the service provider.
IDP Adapter
IDP Adapter Plugin

This plugin is invoked immediately before sending a SAML 2.0 response.

The plugin can be implemented either in JavaScript or as a Java class. If defined, the scripted implementation takes precedence, otherwise AM invokes the IDP Adapter Java class.

Learn more in IDP adapter.

IDP Adapter Class

Specifies the Java class for the IdP Adapter plugin.

This class is not invoked if a script is selected for IDP Adapter Script.

IDP Adapter Script

Specifies the script for the IdP Adapter plugin.

Select from a list of all the Saml2 IDP Adapter type scripts saved to this realm, including the default template script, SAML2 IDP Adapter Script.

Learn more in saml2-idp-adapter.js.

Remote identity provider configuration properties

After you’ve set up a remote identity provider, configure it through the AM admin UI under Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion content

The following properties appear under the Assertion Content tab:

Signing and Encryption

Request/Response Signing

The requests and responses that the IDP requires the SP to sign digitally.

Encryption

  • NameID Encryption – When selected, the SP must encrypt NameID elements.

Algorithms

Select the signing, encryption and digest algorithms that the SP will use.

NameID Format

  • NameID Format List – The supported name identifiers for users who are shared between providers for single sign-on.

Secrets

  • Secret Label Identifier – Identifier used to create a secret label for mapping to a secret in the secret store. AM uses this label to create a specific secret label for this entity provider. The secret label takes the form am.applications.federation.entity.providers.saml2.identifier.basicauth where identifier is the value of Secret Label Identifier. The label can only contain characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

    If you change the Secret Label Identifier for a specific entity provider, any corresponding mappings are deleted, unless they’re referenced by other entity providers.

Basic Authentication

  • Enabled – Authenticate with the specified username and password when making requests to this entity provider’s SOAP endpoints.

  • User Name – The username with which to authenticate at SOAP endpoints.

  • Password – The password with which to authenticate at SOAP endpoints.

    If you set a value for Secret Label Identifier, and AM finds a mapping to this secret label in the secret store, the value of this Password field is ignored. For example, if you set the Secret Label Identifier to demo and AM finds a secret mapping to am.applications.federation.entity.providers.saml2.demo.basicauth, AM uses this secret and ignores the value of the Password field. For basic authentication, there is no default secret label for the realm, or globally.

Client Authentication

These settings let an SP authenticate to the IDP using mutual TLS (mTLS).

When you enable client authentication for any request type in this section, you must configure a secret mapping from one of the following secret labels to a valid certificate in the secret store:

  • am.default.applications.federation.entity.providers.saml2.sp.mtls – the global or realm-specific mapping for hosted SPs

  • am.applications.federation.entity.providers.saml2.identifier.mtls – a mapping for a specific SP, where identifier is the value of the Secret Label Identifier you set in the Secrets panel in the SP configuration.

If you configure a global mapping, a realm-specific mapping, and a mapping for a specific SP, the order of precedence is as follows:

  • Hosted SP-specific mapping

  • Realm-level default

  • Global default

The certificates mapped to these labels are included in the SP metadata export with <KeyDescriptor use="signing">.

Currently, you can enable mTLS for the following request:

  • Artifact Resolve – For artifact resolution requests, the IDP instructs the SP to send a client certificate along with the request.

Services

The following properties appear under the Services tab:

IDP Service Attributes

Artifact Resolution Service

The endpoint to manage artifact resolution. The Index is a unique identifier for the endpoint.

Single Logout Service

The endpoints to manage single logout, depending on the selected SAML binding.

Manage NameID Service

The endpoints to manage name identifiers, depending on the selected SAML binding.

Single SignOn Service

The endpoints to manage single sign-on.

These endpoints are used only for SP-initiated flows but are included as a requirement of the SAML V 2.0 Metadata specification.

NameID Mapping

Location

The endpoint to manage name identifier mapping.

Hosted service provider configuration properties

Once you have set up a hosted service provider, you can configure it through the AM admin UI by navigating to Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion content

The following properties appear under the Assertion Content tab:

Signing and Encryption

Request/Response Signing

The parts of messages the service provider requires the identity provider to sign digitally.

Encryption

The identity provider must encrypt selected elements.

Secret Label and Algorithms
Secret Label Identifier

An identifier for the secret label AM uses for this entity provider, when resolving secrets.

For example, if you set this value to demo, the entity provider uses the following secret labels:

  • am.applications.federation.entity.providers.saml2.demo.signing

  • am.applications.federation.entity.providers.saml2.demo.encryption

If not specified, AM uses the entity provider role-specific, default global secret labels. Learn more in Secret label mappings for SAML v2.0 signing and encryption.

Signing Algorithm

The algorithms the provider can use to sign the request/response attributes selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Digest Algorithm

The digest algorithms the provider can use when signing the requests and responses selected in the Request/Response Signing group.

These algorithms are exposed in the provider’s metadata extension.

This property has no default.

Encryption Algorithm

The two types of encryption algorithms for the provider:

  • Symmetric algorithms, which the provider can use to encrypt the objects selected in the Encryption group. Select one or more AES algorithms from the drop-down list.

    Default: http://www.w3.org/2001/04/xmlenc#aes128-cbc

  • Asymmetric algorithms, advertised as the provider’s transport key algorithm. When SAML v2.0 token encryption is enabled, hosted providers should use the algorithm the remote provider is advertising when encrypting symmetric encryption keys.

    Select one or more algorithms from the drop-down list:

    Key Transport Algorithms

NameID Format

NameID Format List

The supported name identifiers for users that are shared between providers for single sign-on.

The following diagram shows how the hosted SP decides which of the supported NameID formats is used:

nameid-format-flow-hosted-idp
Disable NameID Persistence

Disables the storage of NameIDs in the user data store, even if the NameID format is urn:oasis:names:tc:SAML:2.0:nameid-format:persistent in the received assertion and the account mapper has identified the local user.

You may want to disable storage of NameID values if you are using a read-only data store, or an external identity store that does not have the AM identity schemas applied.

When local authentication is utilized for account linking purposes, disabling federation persistence requires end users to authenticate locally for each SAML-based login.

Default value: false

Authentication Context

Mapper

A class that implements the SPAuthnContextMapper interface and sets up the authentication context.

Default: com.sun.identity.saml2.plugins.DefaultSPAuthnContextMapper

Authentication Context

The authentication context classes the SP supports, and any AM authentication mechanisms used when an IDP specifies the respective class in a SAML v2.0 authentication request.

  • The Predefined Reference drop-down list specifies the list of context references.

  • The Key drop-down list specifies the authentication mechanism that AM uses when an SP specifies an authentication context class in a SAML v2.0 authentication request.

    Authentication Mechanisms Reference for the Key Drop-down List
    Service

    AM will use the specified authentication chain or tree to authenticate the user.

    For example, in the Value field, enter HmacOneTimePassword to use the built-in one-time password example authentication tree, or ldapService to use the built-in chain that authenticates against the default identity store.

    Module

    AM will use the specified authentication module to authenticate the user.

    Authentication Level

    AM will authenticate the user with a method that has an associated authentication level equal to or higher than the specified value.

    If there is more than one suitable method, AM presents the available options by using a ChoiceCallback.

    Learn about using and returning callbacks during authentication in Authenticate over REST.

    The Role, User, and Resource URL options are deprecated. Don’t use them.

  • The Value field specifies the name relative to the authentication mechanism you chose in the previous step. For example, if you chose the Service authentication mechanism, add the name of an authentication tree or chain in the Value field.

  • The Level field specifies the numeric value of precedence of the supported context reference classes.

    Classes with higher numbers are considered stronger than lower numbered classes. The values determine which authentication classes can be used when the SP makes an authentication request that uses a comparison attribute; for example, minimum or better.

    Note that the value in the Level field should match the auth level of the specified chain, module, or tree. For example, if the specified authentication chain sets an auth level of 10, set the same value in the Level field in the Authentication Context table. As AM compares the current auth level against the level specified in Authentication Context table, if the two values do not match, AM may require a logged in user to re-authenticate unnecessarily.

    Example
    Choose the authentication mechanisms AM uses when receiving authentication requests that specify an authentication context class.

    Learn about authentication context classes in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard.

    Default value: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

Comparison Type

Used in conjunction with the Default Authentication Context to specify the possible range of authentication mechanisms the IDP can choose from.

For example, if the Comparison Type field is set to better, and the PasswordProtectedTransport authentication context class is selected in the Default Authentication Context field, the IDP must select an authentication mechanism with a higher level assigned.

Default: exact

Include Request Authentication Context

Whether to include an authentication context class as the Requested Authentication Context in the SAML v2.0 Authentication Request.

Default: Enabled

Assertion Time
Assertion Time Skew

Grace period in seconds for the NotBefore time in assertions.

Basic Authentication

Enabled, User Name, Password

When enabled, authenticate with the specified user name and password at SOAP endpoints.

Assertion processing

The following properties appear under the Assertion Processing tab:

Attribute Mapper

Attribute Mapper

A class that implements the attribute mapping.

Attribute Map

Maps SAML attributes to session properties, or user profile attributes.

The value of Key is a SAML attribute sent in an assertion, and the value of Value is a property in the user’s session, or an attribute of the user’s profile.

By default, the SP maps the SAML attributes it receives to equivalent-named session properties. However, when the SP is configured to create identities during autofederation and the identity does not exist yet, the SP maps the SAML attributes to their equivalents in the newly-created user profile.

The special mapping Key: *, Value: * means that the SP maps each attribute it receives in the assertion to equivalent-named properties or attributes. For example, if the SP receives mail and firstname in the assertion, it maps them to mail and firstname respectively.

Remove the special mapping and add key pairs to the map if:

  • (During autofederation) The attributes in the IdP’s and the SP’s identity stores do not match.

  • You need control over the names of the session properties.

  • You need control over which attributes the SP should map, because the IdP adds too many to the assertion.

For example, if the SAML attribute is firstname and you want the SP to map it to a session property/user profile attribute called cn, create a mapping similar to Key: firstname, Value: cn.

Auto Federation

Enabled

When enabled, automatically federate user’s accounts at different providers based on the specified SAML attribute.

Attribute

The SAML attribute to match accounts at different providers.

Account Mapper

Account Mapper

A class that implements AccountMapper to map remote users to local user profiles.

Use Name ID as User ID

When selected, fall back to using the name identifier from the assertion to find the user.

Transient User

The user profile to map all identity provider users when sending transient name identifiers.

Artifact Message Encoding

Artifact Message Encoding

The message encoding format for artifacts.

URL

Local Authentication URL

Use this property to specify an alternative URL to redirect the user to after validating the SAML2 assertion from the IDP. For example, if you have created a custom user interface other than the AM UI.

When in integrated mode, the query parameters are appended to the configured URL. Typically, these parameters contain all the information necessary for AM to continue the authentication journey.

When in standalone mode, AM redirects users to the specified URL, and appends a goto parameter. This parameter contains the URL the user must be redirected to next.

Intermediate URL

The URL to redirect the user to after authentication but before the original URL requested.

External Application Logout URL

The URL to send an HTTP POST to including all cookies when receiving a logout request. To add a user session property as a POST parameter, include it in the URL query string as a appsessionproperty parameter.

Default Relay State URL

Default Relay State URL

The URL to redirect users to after the request has been handled. Used if not specified in the response.

Adapter

Adapter

A class that implements the FederationSPAdapter interface and performs application specific processing during the federation process.

Adapter Environment

Environment variables passed to the adapter class.

Services

The following properties appear under the Services tab:

MetaAlias
MetaAlias

Used to locate the hosted provider’s entity identifier, specified as [/realm-name]*/provider-name, where provider-name can not contain slash characters (/). For example: /myRealm/mySubrealm/sp.

Ensure the MetaAlias is unique for each provider configured in a CoT and in the realm.

SP Service Attributes

Single Logout Service

The endpoints to manage single logout, depending on the SAML binding selected.

Manage NameID Service

The endpoints to manage name identifiers, depending on the SAML binding selected.

Assertion Consumer Service

The endpoints to consume assertions, with Index corresponding to the index of the URL in the standard metadata.

The scheme, FQDN, and port configured must exactly match those of the service provider as they appear in its metadata.

To determine the service provider’s endpoint URL, AM uses the Base URL service, if configured.

If the URL does not match, the SAML v2.0 flow will fail and AM will log Invalid Assertion Consumer Location specified in the audit log file.

Advanced settings

The following properties appear under the Advanced tab:

SAE Configuration

SP URL

The endpoint to manage Secure Attribute Exchange requests.

SP Logout URL

The endpoint of the service provider that can handle global logout requests.

Application Security Configuration

How to handle encryption for Secure Attribute Exchange operations.

ECP Configuration

Request IDP List Finder Implementation

A class that returns a list of preferred identity providers trusted by the SAML Enhanced Client or Proxy profile.

Request IDP List Get Complete

A URI reference used to retrieve the complete identity provider list if the IDPList element is not complete.

Request IDP List

A list of identity providers for the SAML Enhanced Client or Proxy to contact, used by the default implementation of the IDP Finder.

IDP Proxy

IDP Proxy

When enabled, AM includes a Scoping element in the authentication request to enable the request to be proxied.

Introduction

When enabled, use introductions to find the proxy identity provider.

Proxy Count

The maximum number of proxy identity providers.

IDP Proxy List

A list of URIs identifying preferred proxy identity providers.

Session Synchronization

Enabled

When enabled, the service provider sends a SOAP logout request over the back channel to all identity providers when a session times out. A session may time out when the maximum idle time or maximum session time is reached, for example.

Relay State URL List

Relay State URL List

List of URLs permitted for the RelayState parameter. AM validates the redirection URL in the RelayState parameter against this list. If the RelayState parameter’s value is in the list, AM allows redirection to the RelayState URL. If it is not in the list, a browser error occurs.

Use the pattern matching rules described in Success and failure redirection URLs to specify URLs in the list.

If you DO NOT specify any URLs in this property, AM only allows redirection to RelayState URLs that match the domain of the instance. Any other URL will cause a browser error.

Remote service provider configuration properties

After you’ve set up a remote service provider, configure it through the AM admin UI under Realms > Realm Name > Applications > Federation > Entity Providers > Provider Name.

Assertion content

The following properties appear under the Assertion Content tab:

Signing and Encryption

Request/Response Signing

The requests and responses that the SP requires the IDP to sign digitally.

Encryption

The elements that the SP requires the IDP to encrypt.

  • Attribute Encryption – When selected, the IDP must encrypt SAML attributes.

  • Assertion Encryption – When selected, the IDP must encrypt SAML assertions.

  • NameID Encryption – When selected, IDP must encrypt NameID elements.

Algorithms

  • Signing Algorithm – The signing algorithm the SP will use.

  • Digest Algorithm – The digest algorithm the SP will use.

  • Encryption Algorithm – The encryption algorithm the SP will use.

NameID Format

  • NameID Format List – The supported name identifiers for users who are shared between providers for single sign-on.

  • NameID Value Map – Map the NameID format to a user profile attribute, for example:

    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress=mail or urn:oasis:names:tc:SAML:2.0:nameid-format:persistent=objectGUID;binary.

    • Key – The Name ID format to map, for example: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    • Value – The profile attribute, for example: mail.

    • Binary – Indicates that the profile attribute is binary and should be Base64-encoded when used as the NameID value.

    If the specified NameID format is used in the protocol, the corresponding profile attribute value is used as the NameID in the Subject assertion element. This mapping overrides all the values defined in the NameID Value Map on the hosted IDP. For example, if a NameID Value Map is defined for the SP and a request is made with a specific NameID Format that only exists on the IDP, it will fail.

  • Disable NameID Persistence Disables the storage of NameID values at the IDP when generating an assertion for this remote SP.

    Default value: false

Secrets

  • Secret Label Identifier – Identifier used to create a secret label for mapping to a secret in the secret store.

    AM uses this label to create a specific secret label for this entity provider. The secret label takes the form am.applications.federation.entity.providers.saml2.identifier.basicauth where identifier is the value of Secret Label Identifier. The label can only contain characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

    If you change the Secret Label Identifier for a specific entity provider, any corresponding mappings are deleted, unless they’re referenced by other entity providers.

    If you specify a value for Secret Label Identifier, and AM finds a mapping to this secret label in the secret store, the value of the Password field is ignored. For basic authentication, there is no default secret label for the realm, or globally.

Basic Authentication

  • Enabled – Require authentication with the specified username and password at SOAP endpoints.

  • User Name – The username used to authenticate at SOAP endpoints.

  • Password – The password used to authenticate at SOAP endpoints.

    If you specify a value for Secret Label Identifier, and AM finds a mapping to this secret label in the secret store, the value of the Password field is ignored. For basic authentication, there is no default secret label for the realm, or globally.

Assertion processing

The following properties appear under the Assertion Processing tab:

Attribute Mapper

Attribute Map

Override any mappings of attributes to user profile attributes at the IDP.

Artifact Message Encoding

Artifact Message Encoding

The message encoding format for artifacts.

Services

The following properties appear under the Services tab:

SP Service Attributes

Single Logout Service

The endpoints to manage single logout, depending on the selected SAML binding.

Manage NameID Service

The endpoints to manage name identifiers, depending on the selected SAML binding.

Assertion Consumer Service

The endpoints to consume assertions. Index corresponds to the index of the URL in the standard metadata.

Advanced settings

The following properties appear under the Advanced tab:

Skip Endpoint Validation For Signed Requests

When enabled, AM doesn’t verify Assertion Consumer Service URL values in SAML authentication requests. For example, this lets the Assertion Consumer Service URL contain dynamic query parameters.

Because assertion consumer service URL verification is part of the SAML v2.0 specification, you can only skip validation if the authentication request is digitally signed by the SP. To digitally sign authentication requests, in the remote SP configuration go to Assertion Content > Signing and Encryption > Request/Response Signing, and select Authentication Requests Signed.

You must configure the remote SP to sign the authentication request.

AM returns an error if it receives an unsigned authentication request and this option is enabled.

SAE Configuration

SP URL

The endpoint to manage Secure Attribute Exchange requests.

SP Logout URL

The endpoint of the service provider that can handle global logout requests.

IDP Proxy

IDP Proxy enabled

When enabled, the authentication requests from this service provider can be proxied.

Proxy all requests

When enabled, AM proxies every authentication request from the SP, whether it contains a Scoping element or not.

IDP Proxy enabled must be set to true for this option to take effect.

Introduction enabled

When enabled, use introduction cookies to find the proxy identity provider.

This property only works with a non-default SAML2IDPProxyFRImpl implementation, and will be deprecated in a future release.
Use IDP Finder

When enabled, use the IDP finder service to determine the IDP to which authentication requests are proxed.

Proxy Count

Specifies the maximum number of proxy identity providers. AM sets the specified value in the Scoping element of the authentication request it proxies for this SP.

You must enable the Proxy all requests option for this option to take effect.

IDP Proxy List

A list of URIs identifying preferred proxy identity providers.

Circle of trust configuration properties

Once you have set up a circle of trust, you can configure it through the AM admin UI under Realms > Realm Name > Applications > Federation > Circle of Trust > Circle of Trust Name.

Name

String that refers to the circle of trust.

Once you have set up a circle of trust, the name cannot be configured.

Description

Short description of the circle of trust.

Status

Whether this circle of trust is operational.

Entity Providers

Known hosted and remote identity and service providers participating in this circle of trust.

SAML2 Writer Service URL

SAML v2.0 service that writes identity provider entity identifiers to Common Domain cookies after successful authentication, used in identity provider discovery. Example: https://discovery.example.com:8443/openam/saml2writer.

SAML2 Reader Service URL

SAML v2.0 service that reads identity provider entity identifiers from Common Domain cookies, used in identity provider discovery. Example: https://discovery.example.com:8443/openam/saml2reader.

SAML v2.0 advanced properties

To configure SAML v2.0 advanced properties, in the AM admin UI, go to Configure > Server Defaults > Advanced.

openam.saml.decryption.debug.mode

When enabled, AM decrypts SAML v2.0 messages that are sent and received, and writes the content to the debug logs.

Don’t enable this property in production environments as these messages may contain user information.

Default: False

org.forgerock.openam.saml2.authenticatorlookup.skewAllowance

The allowable time difference, in seconds, between any existing session the user may have, and the current time when an authentication request specifies ForceAuthn.

If the authenticated user’s session was created outside of the allowable time range, AM rejects the assertion, and re-authentication is required.

Default: 60

org.forgerock.openam.saml2.tls.handler.cache.size

The size of the cache that holds HTTP Client handlers to facilitate mTLS authentication for artifact resolution.

The default should suffice for most deployments. Increase the cache size if you have a large number of remote IDPs that each use a separate secret alias.

The entire cache is invalidated when a secret store changes in a realm.

Default: 50

Copyright © 2010-2024 ForgeRock, all rights reserved.