--- title: Identity Assertion node description: The Identity Assertion node provides a secure communication channel for authentication journeys to communicate directly with PingGateway. component: auth-node-ref version: latest page_id: auth-node-ref::identity-assertion-node canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/identity-assertion-node.html keywords: ["Authenticator", "PingGateway", "WDSSO"] page_aliases: ["auth-node-identity-assertion-node.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/identity-assertion-node.html section_ids: auth-node-gateway-comm-example: Example auth-node-identity-assertion-key: Create a shared 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 availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs outcomes: Outcomes --- # Identity Assertion node The Identity Assertion node provides a secure communication channel for authentication journeys to communicate directly with PingGateway. 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: ![cdsso](https://kroki.io/plantuml/svg/eNrNVMFu2zAMvfsrCF_aBm08FMMOPQwwNqzotqLD2qKXXBSbjlnIkkdRzbI_2m_sy0Y5Ttamac_zxZZEPr73SLk4yECfD75fMS1agT-_4fTN6Vs4Sa938I3cAi5qdEKy0jDuPRsh77Ih7zYg-AakpQCVrxEYf0RiDGB03XXIFRkLwTeyNIxgqUKnOUuS9hXsBO15HeXdUIJEMZuGLBnBMIXSWoiKFFqjX3ME_FnZGOgB7QpCnN9jJQOOeF1W7bb0HGWJ6JTzlg6CcfXLdKZrrTceFuhQ9zQeggpFVyHUZBZsOmjYd2sjlCQeQ8--whCGVJJRsTVObi-_HkMr0p8VRZ82YmenwUeusPG8wKlDKTbw01Y6mx0UWWaieBe7OXKW9YaFKuo1GfLE-1xJLc1q5sqoulRBNTBPVAQZ2EfBHEyAi3PFadfbT2HKy6KsH4zWrB-5YH2sZ267LkNAHpCddntALC_NZjPtvcJtD4q-H7QHTwluTsfDHZpPBY4xM_cFWa3xobj7eH19NUAlOkntBkefx_Lh5P0u-TNI8J7pF2Y7R3ujD6_6tDD2CO6YdC4qa6gLaebSeN1rUx2uDsLM6ZiyGjsgBUkjdEiNXhHX0CKmE02pdVL90b7Cz005g-9pQsI4WDoqvOoFtVeTCW185jHk893NZJI9B0nQOyatHRgNxmzndG_CIxPKuh4tmDkVtKmvV1l_CX2quw9xv7oQrcDhdazSLSo-GbLq09ELKp515vtY7zV7tilrg2ZO2yGGXPoP5HnP5NLQ2TxPAvIcmT3n-f82GNt5_ic6-wu2qBj1) Advanced Identity Cloud and PingGateway share a symmetric key for encryption and decryption at both ends of the flow. ## Example The following example describes how to use the Identity Assertion node. ### Create a shared encryption key Identity Assertion in Advanced Identity Cloud uses a shared 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. Generate the key and add it as an ESV secret in Advanced Identity Cloud: 1. Generate a random 32-byte AES secret key and base64-encode it as in the following example command: ```console $ head -c32 /dev/urandom | base64 ``` Record the generated key value for use when configuring Advanced Identity Cloud and PingGateway. 2. Sign on to the Advanced Identity Cloud admin UI. 3. Add the key as a Base64-Encoded AES Key ESV secret. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you're using the [REST API](https://docs.pingidentity.com/pingoneaic/tenants/esvs-manage-api.html) to create the ESV, make sure that your service account has the `fr:idc:esv:*` scope and that you include this scope when requesting the access token. | * Record the ESV name for use when configuring Advanced Identity Cloud secrets and PingGateway routes. * The examples in the documentation use an ESV named `esv-idassert`. * Advanced Identity Cloud and PingGateway use the ESV key name suffix, `idassert`, as the key identifier (`"kid"`) in the encrypted JWT they share. This `"kid"` must match the IdentityAssertionHandler `"encryptionSecretId"` value you will use in the PingGateway [Identity Assertion service route for IdentityAssertionNode](https://docs.pingidentity.com/pinggateway/2026/reference/Handlers.html#IdentityAssertionHandler-examples). * If you choose your own name, don't suffix it with a number. Learn more in [Create secrets](https://docs.pingidentity.com/pingoneaic/tenants/esvs-manage-ui.html#create-secrets). ### Configure the Identity Assertion service #### Enable the service 1. Go to Native Consoles > Access Management > Realms > *Realm name* > Services. 2. Click +Add a Service and select Identity Assertion Service to create. 3. 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 `Gateway01`. * Identity Assertion server URL: The Identity Assertion server URL. For example, enter `https://ig.ext.com:8443`. * Shared Encryption Secret: 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`. 2. Click Create. 3. Keep the default values for JWT TTL (seconds) and Skew Allowance (seconds) and save your changes. Find more information on this service in [Identity Assertion service](https://docs.pingidentity.com/pingoneaic/am-reference/services-configuration.html#realm-identity-assertion). ### Map the secret label to the encryption key 1. Sign on to the Advanced Identity Cloud admin UI and go to Native Consoles > Access Management. 2. In the Realm Overview page, click Secret Stores. 3. 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 Advanced Identity Cloud. The PingGateway configuration includes two routes: * Authentication filter route Directs unauthenticated requests to an authentication journey. For testing purposes, configure Advanced Identity Cloud and PingGateway for cross-domain single sign-on: 1. Follow the steps in [Cross-domain single sign-on](https://docs.pingidentity.com/pinggateway/2026/aic/cdsso.html). The setup configures a demo user and validation service required for the example. 2. 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. 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/2026/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 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 ![identity assertion node](_images/identity-assertion-node.png) | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Add a [Failure URL node](failure-url.html) 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 `Gateway01 [/alpha]`, where `Gateway01` 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/2026/reference/Handlers.html#IdentityAssertionHandler-examples). ## 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 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 in a secret store. The encryption key must be configured as an [ESV](https://docs.pingidentity.com/pingoneaic/tenants/esvs-signing-encryption.html). If you create the ESV using the API, the `fr:idc:esv:*` scope is required. * 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](#auth-node-gateway-comm-example): * [Create a shared 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.