Auth node reference

Gateway Communication node

The Gateway Communication node provides a secure communication channel for Advanced Identity Cloud authentication journeys to communicate directly with PingGateway.

This secure communication channel extends Advanced Identity Cloud’s capabilities with PingGateway features, such as validating a Kerberos ticket and performing other certificate handshakes.

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

No

Ping Identity Platform (self-managed)

No

Inputs

Any data in the shared state that must be sent to PingGateway.

Dependencies

Before you configure this node on your tenant, set up the following:

Two key pairs

Set up two sets of public and private key pairs; one set each for Advanced Identity Cloud and PingGateway. You can use the mkjwk JSON Web Key generator to generate sample keys in the following format:

  • Type: RSA

  • Key size: 2048

  • Algorithm: RSA1_5: RSAES-PKCS1-v1_5

  • Key ID: Timestamp

Store one set of public and private keys in Advanced Identity Cloud along with the public key from the second set.

Similarly, store the second set of public and private keys in PingGateway, along with the public key from the first set.

PingGateway JWT validation

PingGateway must be configured to validate the JWT sent by Advanced Identity Cloud, and create a signed and encrypted JWT to be sent back to Advanced Identity Cloud.

The example shown here assumes that the public and private keys between Advanced Identity Cloud and PingGateway are in PEM format.

ig jwt route

You can download the sample IdentityAssertion route from here.

The sample route assumes that the keys in PEM format have been added to the config.json heap. The keys are stored in a top-level (at the same level as config/logs/scripts) directory called secrets etc). The key files are named using the convention of secretId.pem.

Gateway Communication service

To configure the Gateway Communication service:

  1. Log in to your Advanced Identity Cloud admin UI, and navigate to Native Consoles > Access Management.

  2. In the Realm Overview page, click Service Management.

  3. Click + Add a Service.

  4. Select Gateway Communication Service from the Choose a service type menu, and click Create.

  5. In the Gateway Communication Service page, ensure that Enable is selected.

  6. In the Secondary Configurations tab, click Add a Secondary Configuration, and provide the following details:

    • Name: A unique name for the PingGateway server. *Identity Gateway Public Key: Enter the public key portion of the PingGateway in JWK format. It is recommended to use an ESV for these keys.

      Here is an example of a public key:

      {
    "kty": "RSA",
    "e": "AQAB",
    "use": "enc",
    "kid": "enc-1697673430",
    "alg": "RSA1_5",
    "n": "lGR1KKw...QOHSRTfQ"
}

    • Identity Cloud Public and Private Key: Enter the public and private keypair for Advanced Identity Cloud in JWK format. We recommend that you use an ESV for these keys.

      Here is an example of a public and private keypair:

      {
    "p": "45DaO0K...cruR85AWc",
    "kty": "RSA",
    "q": "pu8V15...H75-wXs",
    "d": "LSYzj2...bT628Q",
    "e": "AQAB",
    "use": "enc",
    "kid": "enc-1697673430",
    "qi": "YO—​Ox3d...MaHSU2M",
    "dp": "n-Icwbf1...g0khhw8",
    "alg": "RSA1_5",
    "dq": "T_VO8f0W...8X7WGonTsc",
    "n": "lGR1K...1QOHSRTfQ"
}

    • JWT Parameter Name: Enter the name of the parameter that contains the JWT. This name is used for sending the JWT to PingGateway and is the expected name of the JWT returned by PingGateway.

  7. In the COMMCONFIGS CONFIGURATION, enter the additional details:

    • Identity Gateway URL: Full URL of your PingGateway. This should not include a specific route, because the route will be configured in the node.

    • Send to Gateway Security: Security type used for transporting the JWT to PingGateway. The options are:

      • Signed: The JWT sent to PingGateway is signed by the Advanced Identity Cloud private key.

      • SignAndEncrypt - The JWT sent to PingGateway is signed by the Advanced Identity Cloud public and private keys and then encrypted by the PingGateway public key.

      • Milliseconds JWT TTL - Time in milliseconds representing how long the JWT sent to PingGateway has for Time To Live.

  8. Click Save Changes.

Configuration

The configurable properties for this node are:

Property Usage

Identity Gateway Service

PingGateway service set up used for this communication.

IG Route

The name of the route to take when PingGateway is reached.

Mapping to Gateway

Map data sent in a JWT to PingGateway from the shared state in the journey. This is an optional property that is used only when PingGateway needs data.

  • The key is the Shared State Key containing the data to map.

  • The value is the Claim Key Name in the shared state sent in the claim.

Mapping from Gateway

Map data returned from PingGateway to the shared state in the journey.

  • The key is the PingGateway key in the claim.

  • The value is returned by PingGateway and saved to the shared state.

Outputs

Any data mapped from the claims returned by PingGateway that is stored in the shared state of the journey.

Outcomes

Success

The gateway successfully returned a valid signed and encrypted JWT.

Error

Any error that occurred during an attempt to communicate with the gateway.

Troubleshooting

If this node logs an error, review the log messages to find the reason for the error and address the issue appropriately.

Examples

This example journey highlights the use of the Gateway Communication node to authenticate internal accesses.

gateway comm

Advanced Identity Cloud provides sample journeys you can download to understand and address the most common Gateway Communication use cases.