---
title: User authorization
description: Web SDK supports a first factor provided by the integrator during the flow.
component: recognize
page_id: recognize:web-sdk:web-sdk-reference-user-authorization
canonical_url: https://docs.pingidentity.com/recognize/web-sdk/web-sdk-reference-user-authorization.html
llms_txt: https://docs.pingidentity.com/recognize/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
section_ids:
  update-customer-configuration: Update Customer Configuration
  issuing-a-token: Issuing a token
  pass-the-token-to-web-sdk-client: Pass the token to Web SDK client
  headless-integration: Headless Integration
  web-component-integration: Web component integration
  error-handling: Error Handling
---

# 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:

```javascript
{
  "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](web-sdk-guide-enrollment.html)

* [Authentication Headless Integration](web-sdk-guide-authentication.html)

The user authorization can be set in the openKeylessWebSocketConnection options:

```javascript
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](web-sdk-guide-enrollment.html)

* [Authentication Web Component Integration](web-sdk-guide-authentication.html)

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

```javascript
<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.