# AuthZEN JWT Profile proposal

Author: Omri Gazitt
Initial draft: Jan 13 2025

## Context

The [AuthZEN information model](https://openid.github.io/authzen/#name-information-model) defines a **Subject** as a required part of every authorization request. This subject has two required fields: `type` and `id`.

Callers (known as Policy Enforcement Points or PEPs) are responsible for determining the content of the required fields, based on the "contract" between the PEP and the PDP.

## JWTs as common subjects

In web software, JWTs are commonly used to identify subjects. For example, the content of the `Authorization` header of an authenticated HTTP request is often a `Bearer` token that contains a base64-encoded JWT.

The JWT commonly contains a `sub` claim that is typically the subject of the request.

An AuthZEN-compliant PEP would typically need to decode the JWT and extract the `sub` claim to formulate a well-formed AuthZEN payload of the form

{
  "subject": {
    "type": "user",
    "id": "<content-of-the-sub-claim>"
  },
  ...
}

This profile streamlines this (very common) scenario and offloads some of the burden that a PEP has to perform in order to use the contents of a JWT as the subject of an authorization request.

## JWT subject type

This profile defines the `JWT` subject type. Compliant PDPs will recognize this type, and will treat the `id` field as a base64-encoded JWT.

Example:

{
  "subject": {
    "type": "JWT",
    "id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  },
  ...
}

The `id` in the example above contains a base64-encoded JWT that decodes to the following payload:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

A compliant PDP would decode this JWT and extract the `sub` claim (in this case, `1234567890`) as the subject of the authorization request.

### Overriding the default subject claim

Some callers may wish to use a different claim out of the JWT as the subject of the authorization call. To do this, they would pass the `properties.subject_claim` property with the name of the claim to use.

Example:

{
  "subject": {
    "type": "JWT",
    "id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJqb2huLmRvZUBhY21lY29ycC5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.aO9qA3_RZGNiIT_9taln8e4_IoWFuOYUZSC1LbfqPTQ",
    "properties": {
      "subject_claim": "email"
    }
  },
  ...
}

In the example above, `id` contains a base64-encoded JWT that decodes to the following payload:

{
  "sub": "1234567890",
  "email": "[e-mail]",
  "name": "John Doe",
  "iat": 1516239022
}

Because `subject.properties.subject_claim` is set to `"email"`, an AuthZEN-compliant PDP would extract the content of the `email` claim out of the JWT (in this case, `[e-mail]`), and use it as the subject of the authorization request.

## Scoping the extracted subject

Certain PDPs may need to "scope" or "namespace" the subject that is extracted out of the JWT to a certain `type`. This is the underlying intent in providing the `subject.type` mandatory field in the AuthZEN information model.

For example, a Zanzibar / ReBAC-based PDP asks whether a subject identified by the tuple `{ subject_type, subject_id }` has a permission on a resource.

Such a PDP may extract the `subject_id` out of the JWT (e.g. the `sub` claim by default), but still need to provide a `subject_type` to make a well-formed Zanzibar "Check" request.

This profile defines a default type of `"identity"`.

### Overriding the default subject type

A PEP which wants to override the default subject type can specify the `subject.properties.subject_type` property to provide the underlying type to use in a ReBAC "Check" request.

Example:

{
  "subject": {
    "type": "JWT",
    "id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJqb2huLmRvZUBhY21lY29ycC5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.aO9qA3_RZGNiIT_9taln8e4_IoWFuOYUZSC1LbfqPTQ",
    "properties": {
      "subject_claim": "email",
      "subject_type": "user"
    }
  },
  ...
}

In the example above, `id` contains a base64-encoded JWT that decodes to the following payload:

{
  "sub": "1234567890",
  "email": "[e-mail]",
  "name": "John Doe",
  "iat": 1516239022
}

Because `subject.properties.subject_claim` is set to `"email"`, an AuthZEN-compliant PDP would extract the content of the `email` claim out of the JWT (in this case, `[e-mail]`), and use it as the subject of the authorization request.

Because `subject.properties.subject_type` is set to `"user"`, an AuthZEN-compliant PDP would use `"user"` instead of `"identity"` as the subject type of a "Check" call.