> For the complete documentation index, see [llms.txt](https://docs.keyless.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keyless.io/web-sdk/web-sdk-reference/user-authorization.md).

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

```json
{
  "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](https://docs.keyless.io/web-sdk/web-sdk-guide/enrollment#headless-integration)
* [Authentication Headless Integration](https://docs.keyless.io/web-sdk/web-sdk-guide/authentication#headless-integration)

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](https://docs.keyless.io/web-sdk/web-sdk-guide/enrollment#web-component-integration)
* [Authentication Web Component Integration](https://docs.keyless.io/web-sdk/web-sdk-guide/authentication#web-component-integration)

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

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