Special attribute names in contracts

The SAML_AUTHN_CTX attribute is involved in determining the authentication context value for the flow, which is mapped into the acr claim in the OpenID Connect (OIDC) ID token or the AuthnContextClassRef in the SAML assertion. The authentication context value represents the quality or type of authentication that was performed and may be used by downstream applications to decide what privileges to grant a user. The AuthnContextClassRef is required in SAML assertions and will be set to urn:oasis:names:tc:SAML:1.0:am:unspecified if a value can’t be determined by the procedure below.

PingFederate determines the authentication context value by iterating over each authentication source that was invoked in the flow. Identity provider (IdP) adapters can return an authentication context value by including the org.sourceid.saml20.adapter.idp.authn.authnCtx attribute in the attribute map returned from lookupAuthN().

For IdP connections, the authentication context value comes from the acr claim in the ID token or the AuthnContextClassRef value in the assertion. PingFederate also allows a mapping to be configured in the IdP connection between local and remote authentication context values under Browser SSO → Protocol Settings → Overrides.

PingFederate iterates over the authentication sources that were invoked, pulling an authentication context value from each one. The last authentication context value returned by an authentication source becomes the authentication context value for the overall flow.

Further control over the authentication context value for the flow is available by adding SAML_AUTHN_CTX to an authentication policy contract (APC). Any value mapped into this attribute overrides the authentication context value for the flow and will be passed to downstream applications through the ID token or assertion.

In some cases, you might want to populate the SAML_AUTHN_CTX in the APC with the value from a specific source. For SAML IdP connections, you can add SAML_AUTHN_CTX to the attribute contract. The corresponding attribute for OIDC IdP connections is acr. This will be automatically populated with the authentication context value coming from that IdP connection and you can then map from that attribute into SAML_AUTHN_CTX in the APC.

For IdP adapters that return an authentication context value, you can do the same thing by adding org.sourceid.saml20.adapter.idp.authn.authnCtx to the IdP adapter contract.

Another thing you might want to do is ensure that the authentication context value for the overall flow matches the value that was requested by the client or partner (through the acr_values request parameter, or the RequestedAuthnContext for SAML authentication requests). This can be done by adding a Requested AuthN Context selector to the authentication policy and configuring it to Add or Update AuthN Context Attribute. When you do this, the requested authentication context value is added to the attributes of the first authentication source encountered after the selector in the policy. The key for the added attribute is SAML_AUTHN_CTX. This attribute can then be added to the contract of that authentication source and mapped in the SAML_AUTHN_CTX of the APC to ensure that it becomes the authentication context value for the flow.

There’s a last opportunity to override the authentication context value for a particular flow at the level of the service provider (SP) connection or the OIDC policy. For an SP connection, you can add SAML_AUTHN_CTX to the attribute contract and map the desired value into it. For an OIDC policy, you can add acr to the policy contract and map a value into it.

The SAML_AUTHN_INSTANT attribute is involved in determining the authentication instant value for the flow, which is mapped into the auth_time claim in the OIDC ID token or the AuthnInstant in the SAML assertion. This value is used by downstream applications to determine how recently the end user authenticated. Certain actions may be restricted if the authentication was not recent enough. The AuthnInstant is required in SAML assertions and will be set to the current time if a value can’t be determined by the procedure below.

PingFederate determines the authentication instant value by iterating over each authentication source that was invoked in the flow. IdP adapters can return an authentication instant value by including the org.sourceid.saml20.adapter.idp.authn.authnInst attribute in the attribute map returned from lookupAuthN().

For IdP connections, the authentication instant value comes from the auth_time claim in the ID token or the AuthnInstant value in the assertion.

When an authentication session exists for an authentication source and is used in the flow, the authentication instant value originally obtained from the IdP adapter or connection is used. If the source didn’t return an authentication instant, the creation time of the session is used instead.

PingFederate iterates over the authentication sources that were invoked, pulling an authentication instant value from each one. The most recent authentication instant value returned by an authentication source becomes the authentication instant value for the overall flow.

Further control over the authentication instant value for the flow is available by adding SAML_AUTHN_INSTANT to the APC. Any value mapped into this attribute overrides the authentication instant value for the flow and will be passed to downstream applications through the ID token or assertion.

In some cases, you might want to populate the SAML_AUTHN_INSTANT in the APC with the value from a specific source. For SAML IdP connections, you can add SAML_AUTHN_INSTANT to the attribute contract. The corresponding attribute for OIDC IdP connections is auth_time. This will be automatically populated with the authentication instant value coming from that IdP connection and you can then map from that attribute into SAML_AUTHN_INSTANT in the APC.

For IdP adapters that return an authentication instant value, you can do the same thing by adding org.sourceid.saml20.adapter.idp.authn.authnInst to the IdP adapter contract.

There’s a last opportunity to override the authentication instant value for a particular flow at the level of the OIDC policy. You can add auth_time to the policy contract and map a value into it.

The SAML_AUTHN_RESPONSE_ASSERTION attribute allows you to access the Assertion element of the SAML 2.0 response messages during attribute mapping. This attribute is of type org.sourceid.saml20.xmlbinding.assertion.AssertionType.

When you add the SAML_AUTHN_RESPONSE_ASSERTION attribute to your SAML 2.0 identity provider (IdP) connection attribute contract, PingFederate sets the Assertion element of the SAML 2.0 response message. The SAML_AUTHN_RESPONSE_ASSERTION attribute is available for use during attribute mapping in authentication policies, fragments, and target sessions mapping of SAML 2.0 IdP connections.

To learn more about adding this attribute, see Defining an attribute contract.

You can use OGNL and the SAML_AUTHN_RESPONSE_ASSERTION attribute to retrieve XML attributes of SAML attributes in authentication policies, fragments, and target sessions mapping of SAML 2.0 IdP connections.

The following sample OGNL expression will retrieve the NameFormat attribute from the fname SAML attribute:

To learn more about OGNL, see Construct OGNL expressions.