Identity Assertion node

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

The node extends Identity Cloud by adding IG’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:

Identity Cloud and IG share a symmetric key for encryption and decryption at both ends of the flow.

Compatibility

Product	Compatible?
ForgeRock Identity Cloud	Yes
ForgeRock Access Management (self-managed)	Yes
ForgeRock Identity Platform (self-managed)	Yes

Product

Compatible?

ForgeRock Identity Cloud

Yes

ForgeRock Access Management (self-managed)

Yes

ForgeRock 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.

IG can fulfil the role of the Identity Assertion server.

To use the Identity Assertion node in your 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 IG 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 Identity Cloud and IG uses a single secret for all encryption and decryption:

Identity Cloud uses the key to encrypt the identity request JWT; IG uses it to decrypt the identity request JWT.
IG uses the key to encrypt the resulting Identity Assertion JWT; 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 IG as an Identity Assertion Server uses PEM for IG and imports the secret key value as an ESV into 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 IG 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 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: 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 IG as an Identity Assertion Server uses PEM for IG and imports the secret key value as an ESV into Identity Cloud.

Log in to your 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 IG as an Identity Assertion Server

Configure IG to:

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

The IG configuration includes two routes:

Authentication filter route

Directs unauthenticated requests to an authentication journey in Identity Cloud.

For testing purposes, configure Identity Cloud and IG 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 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 IG’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 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 IG 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 IG 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 IG route that will handle Identity Assertion requests. For example, enter /idassert, as used for the example route in Configure IG as an Identity Assertion Server.

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