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:

1. Updating the customer configuration

2. Issuing a token on your backend

3. 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:

• Enrollment Headless Integration

• Authentication Headless Integration

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:

• Enrollment Web Component Integration

• Authentication Web Component Integration

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.