ID token

An ID token can be used to extract the unique user ID after the user has successfully authorised. You can also opt-in to bypass the use of a resource server by using a custom claim in the ID token payload.

Specifications

To use an ID token, you must verify that:

• The ID token follows the JWT specification (RFC 7519).

• The ID token follows the OpenID Connect Core specification.

• The ID token contains the required claims (see OpenID specification for details).

• The ID token validation complies with the specification.

Issuer and Discovery

Prenly requires knowledge of the issuer ("iss" in the ID token payload), where the issuer must be a valid URI.

You may also require to meet the Discovery specification.

In particular:

OpenID Providers supporting Discovery MUST make a JSON document available at the path formed by concatenating the string /.well-known/openid-configuration to the Issuer.

– section Obtaining OpenID Provider Configuration Information

This path is formed by concatenating the issuer:

{issuer}/.well-known/openid-configuration

Notes:

• The issuer must not include a trailing slash.

• The issuer must be a valid, functional URL.

Validation

The ID token must be verifiable before its payload can be trusted.

Prenly requires access to the JSON Web Key Set (JWKS), typically referenced as:

• JKU

• JWKS URI

This is commonly available via:

{issuer}/.well-known/jwks (or specified in the OpenID configuration)

Additional requirements:

• If multiple signing keys are used, the "kid" header claim must be included in the ID token.

• If only one key is used, Prenly assumes that key is valid for verification.

You can test and verify ID tokens using tools such as:

• https://jwt.io

Testing via JWT.io

1. Go to https://jwt.io

2. Paste your ID token into the Encoded field

3. Review decoded sections:

   • Header

   • Payload

   • Signature

If verification fails:

• Paste your JWK (JSON) into the field:

  "Public Key in SPKI, PKCS #1, X.509 Certificate, or JWK string format"

Payload

In addition to required claims, Prenly primarily uses:

• "sub"

Optional supported claims:

• "email"

• "given_name"

• "family_name"

• "name"

for a full list of claims see the specification for required and optional claims.

If name and email are available:

• They will be displayed in the UI after login

Otherwise:

• A placeholder will be shown

Custom Claims (Subscriptions)

Prenly supports custom claims in the ID token:

• Must be a string array

• Each value represents a subscription product code

• Used to grant access to protected content

Scopes

Required scope:

• openid

Recommended scope:

• offline_access (for details see specification for offline access)

Benefits:

• Allows longer-lived authentication sessions

Important behavior:

• Prenly uses the access token to determine authentication status

• Session duration depends on:

  • Token expiry

  • Prenly cache duration (minimum: 20 minutes)