AuthZEN JWT Profile proposal

Author: Omri Gazitt
Initial draft: Jan 13 2025

Context

The AuthZEN 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": "john.doe@acmecorp.com",
  "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, john.doe@acmecorp.com), 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": "john.doe@acmecorp.com",
  "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, john.doe@acmecorp.com), 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.