Special attribute names in contracts
PingFederate handles the SAML_AUTHN_CTX
and SAML_AUTHN_INSTANT
attribute names in specific ways.
SAML_AUTHN_CTX
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.
Mapping into the |
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.
SAML_AUTHN_INSTANT
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.
Mapping into the |
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.