Identity Assertion node

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

The node extends PingOne Advanced Identity Cloud 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:

PingOne 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.
The Identity Assertion service server must have a valid shared secret encryption key configured as an ESV in the 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 PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud and PingGateway uses a single secret for all encryption and decryption:

PingOne 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; PingOne 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 PingOne Advanced Identity Cloud.

Configure a key for that route as described in this section, and learn more from 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.

Configure the Identity Assertion service

Enable the service

In the Advanced Identity Cloud admin UI, 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.

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: PingOne Advanced Identity Cloud 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

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

Log in to your Advanced Identity Cloud admin UI, 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.

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

The PingGateway configuration includes two routes:

Authentication filter route

Directs unauthenticated requests to an authentication journey in PingOne Advanced Identity Cloud.

For testing purposes, configure PingOne Advanced Identity Cloud 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-idc.json , the CrossDomainSingleSignOnFilter uses PingOne Advanced Identity Cloud’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 PingOne Advanced Identity Cloud setup described in this worked example.
That the IdentityAssertionHandler's peerIdentifier property refers to the host part of the tenant 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

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

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.