PingAM 7.5.1

Authenticate Thing node

This node authenticates a thing. A thing represents an IoT device, service, or the IoT Gateway.

Before you configure this node, ensure that the ref:pingam:reference:global-services-configuration.adoc#global-iot[IoT Service] IoT Service is configured for the realm.

Support for this node is provided by the IoT SDK.

The node supports two methods of authentication:

  1. Proof of Possession JWT

    The node collects a proof-of-possession JWT from the request and does the following:

    • Checks that the claims are valid.

    • Checks that an identity with the same ID as the name of the JWT subject exists.

    • Checks that the identity contains a confirmation key that matches the JWT kid.

    • Validates the JWT signature, using the confirmation key stored in the identity.

  2. Client Assertion

    The node collects a JWT Bearer token from the request for authentication and validates the request according to the JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants.

Compatibility

Product Compatible?

PingOne Advanced Identity Cloud

No

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Outcomes

  • Success

  • Failure

  • Requires Registration

If all checks are successful, evaluation continues through the Success path, and adds the username and the verified claims to the shared node state.

If the identity does not exist, or AM cannot match the identity with the confirmation key, evaluation continues through the Requires Registration outcome.

If any other check fails, evaluation continues through the Failure outcome.

Properties

Property Usage

JWT Authentication Method

Choose the required JWT authentication method:

Proof of Possession

Prove that the signer of the JWT is the owner of the key by including a challenge nonce in the JWT. Validation is according to the JWT Proof of Possession specification.

Client Assertion

Present a JWT Bearer token for authentication and validate the request according to the JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants.

Issue Restricted Token

If this setting is enabled, the node adds a Proof of Possession restriction to the session token issued on successful authentication.

Any requests accompanied by the token must be signed with the key that was used to sign the authentication JWT.

Additional Audience Values

Specify any additional audience values that will be permitted when verifying JWTs.

These audience values are in addition to the AM base, issuer and token endpoint URIs for the Client Assertion authentication method or the realm path for Proof of Possession.

Examples

The following example shows how to authenticate a thing when the identity already exists in the identity store and when its profile contains a confirmation key:

trees-node-authenticate-thing-example1

The following example shows how to authenticate a thing when the identity does not exist, or when it needs to refresh its confirmation key:

trees-node-authenticate-thing-example2