ID token - Prenly

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:

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:

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)