--- title: Reference description: This reference section covers service provider (SP), identity provider (IdP), and circle of trust (CoT) configuration properties. For the global services reference, see Reference. component: pingam version: 8.1 page_id: pingam:am-saml2:saml2-reference canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/saml2-reference.html keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Algorithm"] page_aliases: ["saml2-guide:saml2-reference.adoc"] section_ids: saml2-hosted-idp-configuration: Hosted IdP configuration idp-assertion-content: Assertion content signing_and_encryption: Signing and Encryption nameid_format: NameID Format hosted-idp-authncontext: Authentication Context assertion_time: Assertion Time assertion-cache: Assertion Cache idp-assertion-processing: Assertion processing attribute_mapper: Attribute Mapper account_mapper: Account Mapper local_configuration: Local Configuration idp-services: Services idp_service_attributes: IDP Service Attributes nameid_mapping: NameID Mapping idp-advanced: Advanced settings sae_configuration: SAE Configuration ecp_configuration: ECP Configuration session_synchronization: Session Synchronization idp_finder_implementation: IDP Finder Implementation relay_state_url_list: Relay State URL List idp_adapter: IDP Adapter application_context: Application Context saml2-remote-idp-configuration: Remote IdP configuration remote-idp-assertion-content: Assertion content signing_and_encryption_2: Signing and Encryption nameid_format_2: NameID Format secrets: Secrets basic_authentication: Basic Authentication client_authentication: Client Authentication remote-idp-services: Services idp_service_attributes_2: IDP Service Attributes nameid_mapping_2: NameID Mapping saml2-hosted-sp-configuration: Hosted SP configuration sp-assertion-content: Assertion content signing_and_encryption_3: Signing and Encryption nameid_format_3: NameID Format hosted-sp-authncontext: Authentication Context basic_authentication_2: Basic Authentication sp-hosted-client-auth: Client Authentication sp-assertion-processing: Assertion processing attribute_mapper_2: Attribute Mapper auto_federation: Auto Federation account_mapper_2: Account Mapper artifact_message_encoding: Artifact Message Encoding url: URL config-redirect-tree: Redirect Tree adapter: Adapter sp-services: Services sp_service_attributes: SP Service Attributes sp-advanced: Advanced settings sae_configuration_2: SAE Configuration ecp_configuration_2: ECP Configuration idp_proxy: IDP Proxy session_synchronization_2: Session Synchronization relay_state_url_list_2: Relay State URL List saml2-remote-sp-configuration: Remote SP configuration remote-sp-assertion-content: Assertion content signing_and_encryption_4: Signing and Encryption nameid_format_4: NameID Format secrets_2: Secrets basic_authentication_3: Basic Authentication remote-sp-assertion-processing: Assertion processing attribute_mapper_3: Attribute Mapper artifact_message_encoding_2: Artifact Message Encoding remote-sp-services: Services sp_service_attributes_2: SP Service Attributes remote-sp-advanced: Advanced settings sae_configuration_3: SAE Configuration idp_proxy_2: IDP Proxy config-treename: Tree Name application_context_2: Application Context saml2-cot-configuration: CoT configuration saml2-advanced-properties: SAML 2.0 advanced properties --- # Reference This reference section covers service provider (SP), identity provider (IdP), and circle of trust (CoT) configuration properties. For the global services reference, see [Reference](../am-reference/preface.html). ## Hosted IdP configuration After you've set up a hosted IdP, you can configure it through the AM admin UI under Realms > *realm name* > Applications > Federation > Entity Providers > *hosted IdP*. ### Assertion content The following groups appear on the Assertion Content tab: #### Signing and Encryption * Request/Response Signing Specifies which parts of messages the IdP requires the SP to sign digitally. * Encryption When selected, the SP 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 2.0 signing and encryption](../security/secret-mapping.html#secrets-saml2-signing-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: > **Collapse: Key transport algorithms** > > * (default). > > * [http://www.w3.org/2009/xmlenc11#rsa-oaep](https://www.w3.org/TR/xmlenc-core1/#sec-RSA-OAEP). > > When this algorithm is configured, AM will use the Mask Generation Function Algorithm property (Configure > Global Services > Common Federation Configuration) to create the transport key. > > You can find a list of supported mask generation function algorithms in [Algorithms](../setup/services-configuration.html#global-federation-common-algorithms). > > * . > > For security reasons, you shouldn't use this option. #### 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: ![Diagram showing how the hosted IdP decides which supported NameID format is used.](_images/nameid-format-flow-hosted-idp.svg) * NameID Value Map Maps a NameID format (Key) to a user profile attribute (Value). The `persistent` and `transient` NameID formats don't have to be mapped. The mapped user profile attribute must exist in your identity store. To find available attributes, go to Realms > *realm name* > Identity Stores > *identity store name* > User Configuration and review the list under LDAP User Attributes. Find the default list of user profiles attributes for DS in [LDAP User Attributes](../setup/data-stores-opendj.html#ldap_user_attributes). NameID mapping supports Base64-encoded binary values. Select the Binary option to Base64-encode the attribute's value before it's added to the assertion. #### Authentication Context * Mapper A class that implements the `IDPAuthnContextMapper` interface and sets up the authentication context. Default value: `com.sun.identity.saml2.plugins.DefaultIDPAuthnContextMapper` * Authentication Context Maps the authentication context classes supported by the IdP and the authentication mechanisms used by AM when an SP specifies an authentication context class in a SAML 2.0 request. * Context Reference Select from the following options to define a context reference: * Predefined Reference to choose from a list of supported context references. * Custom Reference to type your own reference to an authentication context. * Key Select an authentication mechanism from the list for AM to use when the SP specifies an authentication context class in a SAML 2.0 request. > **Collapse: Authentication mechanisms** > > * Service > > Specify an authentication tree for AM to use to authenticate the end user. > > For example, in the Value field, enter `HmacOneTimePassword` to use the built-in one-time passcode (OTP) example authentication tree. > > * Module > > This property was used only for authentication with modules and chains and is no longer documented. > > * 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](../am-authentication/authn-rest.html). > > | | | > | - | ---------------------------------------------------------------------- | > | | The `Role` and `User` options are deprecated. Don't use these options. | * Value The name of the authentication mechanism you selected from the Key list. For example, if you chose `Service` as the authentication mechanism, enter the name of an authentication tree. * Level The order of precedence of the supported context reference classes as a numeric value. 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`. The value of this field should match the auth level of the service. For example, if you configured an authentication mechanism as a tree that sets an auth level of 10, set the same value as you specified in the Level field. Because AM compares the current auth level against the level specified in Authentication Context table, if the two values don't match, AM could require a logged-in user to re-authenticate. > **Collapse: Example** > > ![Choose the authentication mechanisms AM uses when receiving authentication requests that specify an authentication context class.](_images/auth-context-mappings.png) \+ Learn more about authentication context classes in [Authentication Context for the OASIS Security Assertion Markup Language (SAML) 2.0](http://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf) in the *SAML 2.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 Learn more in [IdP attribute mapper](custom-idp-attribute-mapper.html). * Attribute Mapper The Java class for a custom Attribute Mapper. This class isn't invoked if a script is selected for `Attribute Mapper Script`. Default: `com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper` * Attribute Mapper Script The script for a custom Attribute Mapper. 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](../am-scripting/sample-scripts.html#saml2-idp-attribute-mapper-js). * Attribute Map Map SAML attributes to user profile attributes. Before user profile attributes can be mapped, they must be allowed in user profiles and also specified for the identity store. Find more information in [Add custom user profile attributes](../setup/customizing-data-stores.html#sec-maint-datastore-customattr). To see the profile attributes available for an LDAP identity store, log in to the AM admin UI, and go to Realms > *realm name* > Identity Stores > User Configuration. Check the LDAP User Attributes list. By default, you can map single-valued attributes to either user profile attributes or static values. To map a static value, enclose the value in double quotes (`"`), for example: ![The static value is enclosed in double quotes.](_images/static-attr-mapping.png)Figure 1. Example of mapping a static value To map multi-valued attributes, you must implement a [custom IdP attribute mapper](custom-idp-attribute-mapper.html). #### Account Mapper * Account Mapper The class that implements an `AccountMapper` to map remote users to local user profiles. * Disable NameID Persistence Disables the storage of the NameID values in the identity store 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 won't work when using any persistent NameID formats. Existing account links that have been established and stored aren't removed when disabling NameID persistence. | Default value: `false` #### Local Configuration * Auth URL An alternative URL for authenticating users, for example, if you have created a custom user interface other than the UI. If present, this overrides the default UI login URL used to authenticate users during federation. 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](../security/changing-cookie-domain.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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 mustn't override the `goto` parameter, as that would redirect the user elsewhere and federation will fail.Learn more in [Success and failure redirection URLs](../am-authentication/redirection-url-precedence.html). | * Reverse Proxy URL The reverse proxy URL if a reverse proxy is used for SAML endpoints. * External Application Logout URL The 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 The MetaAlias value used to locate the provider's entity identifier, specified as `[/realm-name]*/provider-name`, where *provider-name* can't contain slash characters (`/`). For example: `/myRealm/mySubrealm/idp`. The MetaAlias must be unique for each provider configured in a CoT and in the realm. #### IDP Service Attributes * Artifact Resolution Service The endpoint to manage artifact resolution. The Index is a unique number identifier for the endpoint. * Single Logout Service The endpoints to manage single logout (SLO), depending on the SAML binding selected. * Manage NameID Service 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 2.0 Metadata specification](http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf). * Assertion ID Request Service The endpoints to request for a specific assertion by referring to its assertion ID. #### NameID Mapping * URL The endpoint to manage name identifier mapping. ### Advanced settings The following properties appear on the Advanced tab: #### SAE Configuration * IDP URL The endpoint to manage Secure Attribute Exchange requests. * Application Security Configuration Indicate how encryption for Secure Attribute Exchange operations should be handled. #### ECP Configuration * IDP Session Mapper The class that finds a valid session from an HTTP servlet request to an IdP with a SAML Enhanced Client or Proxy profile. #### Session Synchronization * Enabled Select this option to make the IdP send a SOAP logout request over the back channel to all SPs when an authenticated session times out. An authenticated session can time out when the maximum idle time or maximum session time is reached, for example. #### IDP Finder Implementation * IDP Finder Implementation Class The class that finds the preferred IdP to handle a proxied authentication request. * IDP Finder JSP The JSP that presents the list of IdPs to the user. * Enable Proxy IDP Finder For All SPs Select this option to apply the finder for all remote SPs. #### Relay State URL List * Relay State URL List A 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 isn't in the list, a browser error occurs. Use the pattern matching rules described in [Success and failure redirection URLs](../am-authentication/redirection-url-precedence.html) to specify URLs in the list. If you **don't** specify any URLs in this property, AM only allows redirection to `RelayState` URLs that match the domain of the instance. Any other URL causes a browser error. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------- | | | This property doesn't apply to IdP-initiated SSO, where the validation of the `RelayState` parameter should be performed on the SP. | #### IDP Adapter Learn more in [IdP adapter](custom-idp-adapter.html). * IDP Adapter Class The Java class for a custom IdP Adapter. This class isn't invoked if a script is selected for `IDP Adapter Script`. * IDP Adapter Script The script for a custom IdP Adapter. 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](../am-scripting/sample-scripts.html#saml2-idp-adapter-js). #### Application Context * Enable Application Context When enabled, this setting makes the application context available in all SAML 2.0 flows through the `samlApplication` binding in [Scripted Decision node scripts](../am-scripting/scripting-api-node.html#samlapp-binding). You can override this value by setting [`Application Context Enabled`](#saml-sp-app-context-enabled) in the remote SP configuration. ## Remote IdP configuration After you've set up a remote IdP, configure it through the AM admin UI under Realms > *realm name* > Applications > Federation > Entity Providers > *remote IdP*. ### 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](../security/secret-mapping.html) 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 ``. 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 2.0 Metadata specification](http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf). #### NameID Mapping * Location The endpoint to manage name identifier mapping. ## Hosted SP configuration After you've set up a hosted SP, you can configure it through the AM admin UI under Realms > *realm name* > Applications > Federation > Entity Providers > *hosted SP*. ### Assertion content The following properties appear under the Assertion Content tab: #### Signing and Encryption * Request/Response Signing The parts of messages the SP requires the IdP to sign digitally. * Encryption The IdP 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 2.0 signing and encryption](../security/secret-mapping.html#secrets-saml2-signing-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 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 drop-down list: > **Collapse: Key transport algorithms** > > * (default). > > * [http://www.w3.org/2009/xmlenc11#rsa-oaep](https://www.w3.org/TR/xmlenc-core1/#sec-RSA-OAEP). > > When this algorithm is configured, AM will use the Mask Generation Function Algorithm property (Configure > Global Services > Common Federation Configuration) to create the transport key. > > Learn about the supported mask generation function algorithms in [Algorithms](../setup/services-configuration.html#global-federation-common-algorithms). > > * . > > For security reasons, you should *not* use this option. #### 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: ![Diagram showing how the hosted SP decides which supported NameID format is used.](_images/nameid-format-flow-hosted-sp.svg) * Disable NameID Persistence Disables the storage of ``NameID`s in the user datastore, 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 might want to disable storage of NameID values if you're using a read-only datastore, 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 maps the incoming request parameters to an authentication context. Default: `com.sun.identity.saml2.plugins.DefaultSPAuthnContextMapper` * Authentication Context The authentication context maps the URI references to IdP's supported authentication context classes to authentication levels set on the SP side. * Context Reference Select from the following options to define a context reference: * Predefined Reference to choose from a list of supported context references. * Custom Reference to type your own reference to an authentication context. * Level The order of precedence of the supported context reference classes as a numeric value. 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`. > **Collapse: Example** > > ![Context reference mappings](_images/auth-context-mappings-sp.png) Learn about authentication context classes in [Authentication Context for the OASIS Security Assertion Markup Language (SAML) 2.0](http://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf) in the *SAML 2.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 2.0 Authentication Request. Default: Enabled * 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. #### Client Authentication * Exclude Client Certificate from Metadata When enabled, don't export the client certificate in the SP metadata. ### 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 authenticated 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 IdP 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. To make sure a valid tree is configured, use [Redirect Tree](#config-redirect-tree) instead. However, if configured, the value for `Local Authentication URL` overrides `Redirect Tree Name`. * 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. #### Redirect Tree * Redirect Tree Name If specified, AM redirects to this tree after validating the SAML2 assertion from the IdP. For IdP-initiated SSO, you must set either `Redirect Tree Name` or `Local Authentication URL`, otherwise the SP fails to process the assertion and returns an invalid request error. If you provide a value for both settings, AM prioritizes `Local Authentication URL`. You can't delete a tree if it's set as the value for `Redirect Tree Name`. Find information about setting a redirect tree in [Redirect to a tree on the hosted SP](configure-providers.html#config-redirect-tree). * 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 Used to locate the hosted provider's entity identifier, specified as `[/realm-name]*/provider-name`, where *provider-name* can't contain slash characters (`/`). For example: `/myRealm/mySubrealm/sp`. The MetaAlias must be 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 SP as they appear in its metadata. To determine the SP's endpoint URL, AM uses the Base URL service, if configured. If the URL doesn't match, the SAML 2.0 flow will fail and AM logs `Invalid Assertion Consumer Location specified` in the audit log file. Set the HTTP-Artifact and HTTP-POST service locations to `AuthConsumer` for [integrated mode](saml2-integrated-mode.html). ### 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 SP 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 IdPs trusted by the SAML Enhanced Client or Proxy profile. * Request IDP List Get Complete A URI reference used to retrieve the complete IdP list if the `IDPList` element is not complete. * Request IDP List A list of IdPs 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 IdP. * Proxy Count The maximum number of proxy IdPs. * IDP Proxy List A list of URIs identifying preferred proxy IdPs. #### Session Synchronization * Enabled When enabled, the SP sends a SOAP logout request over the back channel to all IdPs when an authenticated session times out. An authenticated session can 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](../am-authentication/redirection-url-precedence.html) 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 SP configuration After you've set up a remote SP, configure it through the AM admin UI under Realms > *realm name* > Applications > Federation > Entity Providers > *remote SP*. ### 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 2.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 SP that can handle global logout requests. #### IDP Proxy * IDP Proxy enabled When enabled, the authentication requests from this SP 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 IdP. | | | | - | ----------------------------------------------------------------------------------------------------------------------------- | | | 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 The maximum number of proxy IdPs. AM sets the specified value in the `Scoping` element of the authentication request it proxies for this SP. You must enable Proxy all requests for this option to take effect. * IDP Proxy List A list of URIs identifying preferred proxy IdPs. #### Tree Name * Tree Name If configured, AM redirects the remote SP to the specified tree, ignoring the configured authentication contexts and existing sessions. The redirect contains a transaction condition advice to ensure the tree is run. You can access the requested authentication context and mappings by including a [Scripted Decision node](https://docs.pingidentity.com/auth-node-ref/8.1/scripted-decision.html) in the tree that queries the [samlApplication](../am-scripting/scripting-api-node.html#samlapp-binding) script binding. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To prevent users from authenticating directly through this tree, either for security reasons or because the tree is insufficient as a complete authentication service, configure it as a [transactional authentication tree](../am-authentication/configure-auth-trees.html#configure-transactional-auth-tree). | #### Application Context * Application Context Enabled This setting controls the availability of the application context in SAML 2.0 flows through the `samlApplication` binding in [Scripted Decision node scripts](../am-scripting/scripting-api-node.html#samlapp-binding). Choose from the following options: * Default: Inherits the value from [`Enable Application Context`](#saml-idp-enable-app-context) in the hosted IdP configuration. * Enabled: The application context is always available. * Disabled: The application context is never available. ## CoT configuration Once you have set up a CoT, 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 2.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 2.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 2.0 advanced properties To configure SAML 2.0 advanced properties, in the AM admin UI, go to Configure > Server Defaults > Advanced. * `openam.saml.decryption.debug.mode` When enabled, AM decrypts SAML 2.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`