--- title: Identity Assertion node description: Integrates PingGateway into an authentication journey to support identity assertion with third-party services such as Windows Desktop SSO and Kerberos. component: platform version: 7.5 page_id: platform:auth-node-ref:identity-assertion-node canonical_url: https://docs.pingidentity.com/platform/7.5/auth-node-ref/identity-assertion-node.html llms_txt: https://docs.pingidentity.com/platform/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Authenticator", "Identity Gateway"] page_aliases: ["auth-node-identity-assertion-node.adoc"] section_ids: availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs outcomes: Outcomes troubleshooting: Troubleshooting auth-node-gateway-comm-example: Example auth-node-identity-assertion-key: Create and import a secret encryption key auth-node-identity-assertion-service: Configure the Identity Assertion service enable_the_service: Enable the service configure_a_server: Configure a server auth-node-identity-assertion-secret-store: Map the secret label to the encryption key auth-node-identity-assertion-ig-setup: Configure PingGateway as an Identity Assertion Server configure_the_example_authentication_journey: Configure the example authentication journey --- # Identity Assertion node The Identity Assertion node provides a secure communication channel for authentication journeys to communicate directly with [PingGateway](https://docs.pingidentity.com/pinggateway/2024.11/gateway-guide/preface.html). The node extends Ping Identity Platform 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: ``` @startuml /' Copyright 2024 ForgeRock AS. All Rights Reserved Use of this code requires a commercial software license with ForgeRock AS. or with one of its affiliates. All use shall be exclusively subject to such license between the licensee and ForgeRock AS. To generate a sequence diagram from this file, process it with PlantUML, http://plantuml.sourceforge.net/sequence.html '/ autonumber participant "IG\nAuthentication filter route" as IGauthfilter participant "AM\nIdentity Assertion node" as AMassertionnode participant "IG\nIdentity Assertion service route" as IGassertionservice participant "Authentication service\nKerberos/WDSSO" as nodeauthservice IGauthfilter -> AMassertionnode: Authorize AMassertionnode -> AMassertionnode: (Optional) Write claims to the journey's\nshared node state (if configured to do so) AMassertionnode -> IGassertionservice: Request with encrypted\n**identity request JWT** IGassertionservice -> nodeauthservice: Authenticate nodeauthservice -> nodeauthservice: (Optional) Add claims\nto request or response nodeauthservice -> IGassertionservice: Result (Success/Failure) IGassertionservice -> AMassertionnode: Response with encrypted\n**identity assertion JWT**\ncontaining ""principal"" or ""error"" AMassertionnode -> AMassertionnode: (Optional) Write claims to the journey's\nshared node state (if configured to do so) AMassertionnode -> IGauthfilter: Response @enduml ``` Ping Identity Platform and PingGateway share a symmetric key for encryption and decryption at both ends of the flow. ## Availability | Product | Available? | | ------------------------------------- | ---------- | | 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 Ping Identity Platform environment, you must complete the following steps, as described in detail in the worked [Example](#auth-node-gateway-comm-example) : * [Create and import a secret encryption key](#auth-node-identity-assertion-key) * [Configure the Identity Assertion service](#auth-node-identity-assertion-service) * [Map the secret label to the encryption key](#auth-node-identity-assertion-secret-store) * [Configure PingGateway as an Identity Assertion Server](#auth-node-identity-assertion-ig-setup) ## Configuration The configurable properties for this node are: | 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 claimRequired 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 keyRequired 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 Ping Identity Platform and PingGateway uses a single secret for all encryption and decryption: * Ping Identity Platform 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; Ping Identity Platform 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](https://docs.pingidentity.com/pingam/7.5/security/using-pem-keys.html) into a secret store. ### Configure the Identity Assertion service #### Enable the service 1. 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. 2. In the Identity Assertion Service page, ensure Enable is selected. #### Configure a server 1. 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: Ping Identity Platform 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`. 2. Click Create. 3. 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](https://docs.pingidentity.com/pingam/7.5/reference/global-services-configuration.html#global-identity-assertion) . ### 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](https://docs.pingidentity.com/pingam/7.5/security/secret-mapping.html) 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 Ping Identity Platform. The PingGateway configuration includes two routes: * Authentication filter route Directs unauthenticated requests to an authentication journey in Ping Identity Platform. For testing purposes, configure Ping Identity Platform and PingGateway as described in [Cross-domain single sign-on](https://docs.pingidentity.com/pinggateway/2024.11/gateway-guide/sso-cdsso.html#cdsso). The setup configures a demo user and validation service required for the example. In `cdsso.json`, the CrossDomainSingleSignOnFilter uses Ping Identity Platform'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`. ```json { "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](https://docs.pingidentity.com/pinggateway/2024.11/reference/Handlers.html#IdentityAssertionHandler-example-service). The route contains an `IdentityAssertionHandler` that calls a `ScriptableIdentityAssertionPlugin` to manage local authentication. The route requires the following: * The key and Ping Identity Platform 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 ![identity assertion node am](_images/identity-assertion-node-am.png) 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](#auth-node-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](#auth-node-identity-assertion-ig-setup). When a request matches the path `/idassert`, the journey accesses the PingGateway route in PingGateway's [Example Identity Assertion service route for IdentityAssertionNode](https://docs.pingidentity.com/pinggateway/2024.11/reference/Handlers.html#IdentityAssertionHandler-examples).