User authorization

Web SDK supports a first factor provided by the integrator during the flow, when enforced the user won’t be able to perform an authentication/enrollment operation unless they have a valid user authorization.

This acts as a first defensive measure to stop bad actors from authenticating/enrolling as someone else.

In order to enable and enforce this verification process three steps are required:

Updating the customer configuration
Issuing a token on your backend
Passing the token to Web SDK on the frontend

Update Customer Configuration

There are two configuration items belonging to user authorization:

Name

Type

Description

User Authorization Type

"None" | "RemoteJWKSet"

The verification type, it’s possible to disable it with "None" or enable the verification against a remote JWK set with "RemoteJWKSet"

User Authorization JWKs URI

string

The URI to specify if "RemoteJWKSet" is set in the User Authorization Type

This configuration can only be updated by the Keyless staff, please communicate the desired values and the team will take care of it.

Issuing a token

Before starting a session, your backend generates a short-lived JWT signed with one of the keys published at your JWKS endpoint.

The token must satisfy these requirements:

Claim

Required value

sub

The username passed to the SDK session

aud

authentication-service

iat

Issued-at time (Unix timestamp)

exp

Expiry time (Unix timestamp)

There’s also a few more constraints: * The system tolerates up to 5 minutes of clock skew. * The tokens should be short-lived (5 – 10 minutes is sufficient). * The tokens are single-use for the duration of one session.

Example JWT payload:

{
  "sub": "user-123",
  "aud": "authentication-service",
  "iat": 1718400000,
  "exp": 1718400300
}

Pass the token to Web SDK client

Once the token has been issued it needs to be set in the Web SDK client configuration, here’s how.

Headless Integration

Please base the integration code from the following guides:

The user authorization can be set in the openKeylessWebSocketConnection options:

await openKeylessWebSocketConnection(sym, {
  ...,
  authorization: {
    token: 'USER_AUTHORIZATION_FROM_CUSTOMER'
  }
})

Web component integration

Please base the integration code from the following guides:

The user authorization can be set through the authorization-token attribute:

<kl-auth-or-enroll
  ...
  authorization-token="USER_AUTHORIZATION_FROM_CUSTOMER"
></kl-auth-or-enroll>

Error Handling

In case the token is missing, expired, or the subject does not match the username, the session is rejected with a SERVER_FORBIDDEN error before any biometric processing occurs.

PingOne Recognize