Skip to main content

 Glossary

A-Z glossary of PageSeeder concepts

ID token

An ID token contains claims that carry information about the user. Information in ID tokens let PageSeeder verify that a user is who they claim to be.

ID tokens are JSON web tokens (JWT) . These ID tokens consist of a header, payload, and signature. The header and signature are used to verify the authenticity of the token, while the payload contains the information about the user requested by your client.

PageSeeder only accepts tokens from identity providers that have been registered in the identity configuration, and verifies the authenticity of every token.

PageSeeder matches users with their email address. If the email address changes on the external identity provider, it needs to be updated on PageSeeder.

Example

The following describe the structure of a sample ID token.

Payload

The payload contains the claims, for example:

{
  "iss": "https://id.example.org",
  "sub": "example-123456",
  "aud": "my_client_id",
  "exp": 1516239022,
  "iat": 1516239022,
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "janedoe@example.org"
}

PageSeeder requires the following claims in the payload:

  • the iss (issuer) claim
  • the aud (audience) claim
  • the exp (expiry) claim
  • the email claim

Header

The header indicates the algorithm and token type. PageSeeder also requires the kid (key ID) and kty (key type) to be specified so that it can look up the public keys. Example: 

{
  "alg": "HS384",
  "typ": "JWT"
}

Encoded token

The ID token is encoded as [header].[payload].[signature], for example:

eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2lkLmV4YW1wbGUub3JnIiwic3ViIjoiZXhhbXBsZS0xMjM0NTYiLCJhdWQiOiJteV9jbGllbnRfaWQiLCJleHAiOjE1MTYyMzkwMjIsImlhdCI6MTUxNjIzOTAyMiwibmFtZSI6IkphbmUgRG9lIiwiZ2l2ZW5fbmFtZSI6IkphbmUiLCJmYW1pbHlfbmFtZSI6IkRvZSIsImVtYWlsIjoiamFuZWRvZUBleGFtcGxlLm9yZyJ9.uUsgJL1mjFYzUZgnmRRNiRmdDdhuDEEGanpmvu7WUzr_TQHs9bBUNX0tK-UI-pVy

This is the value that is sent as the id_token parameter between services.

Token validation

PageSeeder verifies the signature of every ID token, so the OpenID provider must provide a metadata endpoint at /.well-known/openid-configuration so that PageSeeder can retrieve the public keys. PageSeeder supports the RSA and Elliptic Curve (EC) key types.

PageSeeder caches both the metadata information and keys (JWKS) to avoid unnecessary request. The caching period is based on the Cache-Control headers sent by the Identity provider.

The claims must match the following conditions:

ClaimCondition required
issMatches the authority URL in the external identity configuration
audMatches the client ID in the external identity configuration
exp Has not expired
email

Matches the following conditions:

  • Domain is listed in the external identity configuration
  • Email matches an existing user account

Retrictions on API still apply: no authentication if the matching member is listed as API account in the apiAccountUsernames global property and the request IP is not listed in the apiAccountIPs global property.

Supported providers

PageSeeder supports tokens from:

Created on , last edited on