Identity Assertion node

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

You can find more information in the PingGateway documentation for:

The node adds 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:

PingAM/Advanced Identity Cloud and PingGateway share a symmetric key for encryption and decryption at both ends of the flow.

Compatibility

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

Product

Compatible?

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 prerequisites:

An Identity Assertion service must be configured in the same realm, with at least one server configuration that can be selected for use with the Identity Assertion node.

For PingAM deployments, the service can be configured globally.
The Identity Assertion service server must have a valid shared secret encryption key configured in a secret store.

In Advanced Identity Cloud the encryption key must be configured as an ESV.
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 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

Advanced Identity Cloud
PingAM

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

Advanced Identity Cloud 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; Advanced Identity Cloud uses it to decrypt the Identity Assertion JWT.

Provide the encryption key as a PEM-encoded AES secret key or base64aes-encoded secret key ESV.

The example route in Configure PingGateway as an Identity Assertion Server uses PEM for PingGateway and imports the secret key value as an ESV into Advanced Identity Cloud or AM.

Configure a key for that route as described in this section. Learn more in Map ESV secrets to secret labels.

Create a PEM key and import it into the tenant ESV

Generate a random 32-byte AES secret-key:

$ head -c32 /dev/urandom | base64
Rf8...Ig=

Put the key string into a .pem file called idassert.pem, for use on the PingGateway side.
```
-----BEGIN AES SECRET KEY-----
Rf8...Ig=
-----END AES SECRET KEY-----
```
In the following steps, you import the raw key as an ESV and configure it in an ESV secret store.
Using information in Authenticate to Identity Cloud REST API with access token, get an access token for your tenant.

Using the access token, import the new ESV into your tenant. The following example imports an ESV named esv-idassert:

$ export VALUE=$(echo -n Rf8…Ig= | base64)

$ curl -X PUT "<tenant-env-fqdn>/environment/secrets/esv-idassert" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-API-Version: protocol=1.0;resource=1.0" \
  --data-raw "{\"encoding\":\"base64aes\",\"useInPlaceholders\":false,\"valueBase64\":\"$VALUE\"}"

Consider the following points for ESVs:

Prefix the name with esv-.
Don’t suffix the name with a number.
Use base64aes encoding. PEM encoding is also available.

Using information in Tenant settings, check that the ESV is displayed in the Environment Secrets and Variables panel.

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

PingAM 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; PingAM 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

Advanced Identity Cloud
PingAM

In the Advanced Identity Cloud admin console, go to Native Consoles > Access Management > 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.

In the AM admin console, 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: Advanced Identity Cloud and AM use 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 in the Identity Assertion service documentation for:

Map the secret label to the encryption key

Advanced Identity Cloud
PingAM

The example route in Configure PingGateway as an Identity Assertion Server uses PEM for PingGateway and imports the secret key value as an ESV into Advanced Identity Cloud or AM .

Log in to your Advanced Identity Cloud admin console, and go to Native Consoles > Access Management.
In the Realm Overview page, click Secret Stores.
Map the secret label used by the Identity Assertion service to the ESV secret store.

In the Mappings tab, enter the following information:
- Secret Label: Enter the value for the Shared Encryption Secret you created in the Identity Assertion Service. For example, enter idassert.
  
  You can configure the secret only after you have named it in the Identity Assertion service secondary configuration.
  
  The full-length secret label is automatically constructed from the value. In this example, the full-length secret label is am.services.identityassertion.service.idassert.shared.secret.
- Aliases: Enter the alias to the secret you created earlier. For example, enter esv-idassert.

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 Advanced Identity Cloud or AM.

The PingGateway configuration includes two routes:

Authentication filter route

Directs unauthenticated requests to an authentication journey.

For testing purposes, configure Advanced Identity Cloud or AM and PingGateway for cross-domain single sign-on:

Advanced Identity Cloud
PingAM

Follow the steps in Cross-domain single sign-on.

The setup configures a demo user and validation service required for the example.
In cdsso-idc.json, the CrossDomainSingleSignOnFilter uses Advanced Identity Cloud’s default authentication service. Add the property authenticationService to the CrossDomainSingleSignOnFilter to direct requests to the journey. ---

Follow the steps in Cross-domain single sign-on (CDSSO).

The setup configures a demo user and validation service 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 PingAM / Advanced Identity Cloud setup described in this worked example.
That the IdentityAssertionHandler's peerIdentifier property refers to the host:port part of the deployment URL (PingAM deployments) or the host part of the tenant URL (Advanced Identity Cloud tenants).
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

Figure 1. Advanced Identity Cloud

Add a Failure URL node to manage the journey flow if assertion fails. Configure the node with a URL to use for failed requests. For example, the following URL returns PingGateway to the CDSSO redirect endpoint:

https://ig.ext.com:8443/home/cdsso/callback?error=Login%20failed&error_description=Identity%20Assertion%20Failure

Figure 2. PingAM

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.