Identity Assertion node

The Identity Assertion node provides a secure communication channel for authentication journeys to communicate directly with PingGateway.

The node extends AM by adding PingGateway’s routing capabilities and supporting identity assertion with third-party authentication services. Authentication services include Windows Desktop SSO and Kerberos.

The following image shows the flow of an authentication request:

AM and PingGateway share a symmetric key for encryption and decryption at both ends of the flow.

Compatibility

Product	Compatible?
PingOne Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Compatible?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

All shared node state properties listed in Mapping to server claims are valid optional inputs to this node.

To allow the node to validate that an Identity Assertion JWT is the result of an identity request, the nonce must be present in the shared node state as identityAssertionNonce. This isn’t required for the initiating authentication request.

Dependencies

The Identity Assertion node relies on the following:

An Identity Assertion service must be configured globally or in the same realm, with at least one server configuration that can be selected for use with the Identity Assertion node.
The Identity Assertion service server must have a valid shared secret encryption key configured in a secret store.
The Identity Assertion server must be deployed, running, and accessible to the Identity Assertion node.

It must also be configured with the shared secret encryption key.

PingGateway can fulfil the role of the Identity Assertion server.

To use the Identity Assertion node in your AM environment, you must complete the following steps, as described in detail in the worked Example :

Create and import a secret encryption key
Configure the Identity Assertion service
Map the secret label to the encryption key
Configure PingGateway as an Identity Assertion Server

Configuration

The configurable properties for this node are:

Property Usage

Property	Usage
Node name	The name given to this node in the Journey. Default: `Identity Assertion`.
Identity Assertion server ID	The ID of the Identity Assertion server that handles assertion requests. The ID is composed of the server’s ID and realm (if realm-scoped).
Mapping to server claims (optional)	Mapping of: Key: Shared node state key Value: Identity request JWT claim Required only if the server requires additional data. When a shared node state attribute has a value for a mapped key, the value is added to the identity request JWT claims according to the corresponding claim.
Mapping from server result (optional)	Mapping of: Key: Identity Assertion JWT claim Value: Shared node state key Required only if the server requires additional data. Default: the JWT `principal` claim is mapped to the shared node state `username` attribute. When an Identity Assertion JWT claim has a value for a mapped claim, the value is added to the shared node state according to the corresponding shared node state key.

Node name

The name given to this node in the Journey.

Default: Identity Assertion.

Identity Assertion server ID

The ID of the Identity Assertion server that handles assertion requests. The ID is composed of the server’s ID and realm (if realm-scoped).

Mapping to server claims (optional)

Mapping of:

Key: Shared node state key
Value: Identity request JWT claim

Required only if the server requires additional data.

When a shared node state attribute has a value for a mapped key, the value is added to the identity request JWT claims according to the corresponding claim.

Mapping from server result (optional)

Mapping of:

Key: Identity Assertion JWT claim
Value: Shared node state key

Required only if the server requires additional data.

Default: the JWT principal claim is mapped to the shared node state username attribute.

When an Identity Assertion JWT claim has a value for a mapped claim, the value is added to the shared node state according to the corresponding shared node state key.

Outputs

Any data mapped from the claims returned by the Identity Assertion server stored in the shared node state of the journey.

Successful Identity Assertion: The configuration Mapping from server result (optional) determines the shared node state property to set for the mandatory claim principal. The value of the shared node state property is set with the value of the principal claim.

For example, if principal is mapped to usernameReceived, the attribute usernameReceived is set in the shared node state. By default, principal is mapped to username.

Other values mapped in Mapping from server result (optional) are set in the shared node state only if the claim exists in the resulting Identity Assertion JWT.
Failed Identity Assertion: The shared node state property error is set with the value of the error claim in the resulting Identity Assertion JWT.

Outcomes

Success: The Identity Assertion server indicates that authentication was successful. It provides the authenticated principal.
Error: The Identity Assertion server indicates that authentication failed. It provides information about the error.

Troubleshooting

If the node logs an error, review the log to find the reason for the error.

Example

The following worked example describes how to use the Identity Assertion node to authenticate internal access.

Create and import a secret encryption key

Identity Assertion in AM and PingGateway uses a single secret for all encryption and decryption:

AM uses the key to encrypt the identity request JWT; PingGateway uses it to decrypt the identity request JWT.
PingGateway uses the key to encrypt the resulting Identity Assertion JWT; AM uses it to decrypt the Identity Assertion JWT.

Provide the encryption key in PEM format, as a JWK, or in a keystore. For example, create and import an AES PEM key into a secret store.

Configure the Identity Assertion service

Enable the service

In the AM admin UI, go to Configure > Global Services > Identity Assertion Service. Alternatively, to add the service for a realm, go to Realms > Realm name > Services, click +Add a Service and select Identity Assertion Service to create.
In the Identity Assertion Service page, ensure Enable is selected.

Configure a server

In the Secondary Configurations tab, click +Add a Secondary Configuration and enter the following information:
- Name: A unique name for the Identity Assertion server. For example, use IG01.
- Identity Assertion server URL: The Identity Assertion server URL. For example, enter https://ig.ext.com:8443.
- Shared Encryption Secret: AM uses this identifier to create a secret label for encrypting the identity request JWT and resulting Identity Assertion JWT.
  
  The secret label takes the form am.services.identityassertion.service.identifier.shared.secret where identifier is the value of Shared Encryption Secret. For example, use identifier idassert to create a label called am.services.identityassertion.service.idassert.shared.secret.
Click Create.
Keep the default values for JWT TTL (seconds) and Skew Allowance (seconds) and save your changes.

Learn more about the service configuration in Identity Assertion service .

Map the secret label to the encryption key

To map the encryption key in the secret store, follow the steps in Map and rotate secrets using these values:

Secret Label: Find the secret label to map by entering the value of the Shared Encryption Secret you used in the service configuration.

For example, enter idassert to find am.services.identityassertion.service.idassert.shared.secret.

You can find and configure the secret only after you have entered it in the Shared Encryption Secret.
Aliases: Enter the alias to the encryption key secret you created earlier.

Configure PingGateway as an Identity Assertion Server

Configure PingGateway to:

Validate the identity request JWT.
Create an encrypted Identity Assertion JWT to send back to AM.

The PingGateway configuration includes two routes:

Authentication filter route

Directs unauthenticated requests to an authentication journey in AM.

For testing purposes, configure AM and PingGateway as described in Cross-domain single sign-on. The setup configures a demo user and validation service that are required for the example.

In cdsso.json , the CrossDomainSingleSignOnFilter uses AM’s default authentication service. Add the property authenticationService to the CrossDomainSingleSignOnFilter to direct requests to the journey.

The following example redirects unauthenticated requests to a journey called IgCallout.

{
  "name": "CrossDomainSingleSignOnFilter-1",
  "type": "CrossDomainSingleSignOnFilter",
  "config": {
    ...
    "authenticationService" : "IgCallout",
    ...
  }

Identity Assertion service route

Directs unauthenticated requests to a local authentication service such as Kerberos or Windows Desktop SSO.

Consider the example in PingGateway’s Example Identity Assertion service route for Identity Assertion node. The route contains an IdentityAssertionHandler that calls a ScriptableIdentityAssertionPlugin to manage local authentication.

The route requires the following:

The key and AM setup described in this worked example.
That the IdentityAssertionHandler's peerIdentifier property refers to the host:port part of the deployment URL.
That the IdentityAssertionHandler's condition refers to the same path as the Route configured in the node. In this example, it refers to /idassert.

Configure the example authentication journey

Configure the Identity Assertion node as follows:

Identity Assertion server ID: Select the ID and realm configured for the PingGateway server that supports Identity Assertion. For example, enter IG01 [/alpha], where IG01 is the name of the server created in the Configure the Identity Assertion service.
Route: Enter the value of the condition property in the PingGateway route that will handle Identity Assertion requests. For example, enter /idassert, as used for the example route in Configure PingGateway as an Identity Assertion Server.

When a request matches the path /idassert, the journey accesses the PingGateway route in PingGateway’s Example Identity Assertion service route for IdentityAssertionNode.

PingAM 7.5.0