When a domain is federated, Entrypage allows for claims transformation. This feature provides several benefits, including:

  • Limiting claims: You can specify which claims are imported into Entrypage, which is particularly useful for GDPR compliance through data minimization.
  • Consolidating claims: When using multiple federated domains with different claim names for similar purposes, claims transformation allows you to create a homogenous claim set.
  • Enriching user context: You can append new claims to the user’s profile, such as information about the user’s origin.
  • Registering the external identifier: This allows for the registration of an external user identifier.

Configuring Claims Transformation in Entrypage

To enable claims transformation, you can provide a claim map in the Settings > External Identity Providers section. Each federated connection allows for a YAML document containing this claim map.

Claim mapping supports two modes:

  • merge: Entrypage keeps all existing claims and applies only the changes specified in the claim map (e.g., renaming claims or appending new ones).
  • filter: In this mode, Entrypage only imports the claims specified in the claim map. All other claims are omitted.

Beyond the mode, you can configure numerous claims transformations. Each transformation defines the following (all properties are optional):

  • Source: The type of the claim to transform.
  • Target: Where to place the new or transformed claim value.
  • Value: The new value for the claim.

Since all properties are optional, you can use this structure to perform a variety of transformations. For example, by specifying a target and a value but omitting a source, you can simply append a new claim to the user’s profile.

Here are some other possibilities this structure allows for:

  • Rename a claim: Specify a source and a new target but omit the value. This renames the claim without changing its content.
  • Add a static claim: Omit the source and provide a target and value. This appends a new, static claim to the user’s profile.
  • Overwrite a claim: Specify a source and provide a new value. The original claim is replaced with the new value.
  • Copy and rename a claim: Specify a source, and then provide a different target. This keeps the original claim and also creates a new one with the same value under a different name.

System-Claims

Entrypage implements the OpenID Connect (OIDC) protocol, which includes several claims with specific, non-negotiable functions. Attempting to modify the values of these claims through a mapping would disrupt the authorization process. For this reason, any claim mappings that target these system claims are automatically ignored.

System claims include:

  • azp
  • amr
  • acr
  • nonce
  • auth_time
  • iat
  • nbf
  • exp
  • aud
  • sub
  • iss
  • at_hash
  • jti

Renaming the Sub-claim

The sub (subject) claim is crucial for Entrypage as it uniquely identifies a user. Entrypage relies on the sub claim to recognize returning users and ensure a consistent authorization process. By default, Entrypage expects to receive a claim named sub from the external identity provider.

However, not all OIDC implementations adhere to this naming convention. For instance, some identity providers use a different claim type, such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier, for the same purpose.

If your identity provider uses a different claim name for the subject identifier, Entrypage’s federated authentication will not function correctly by default. To resolve this, you can provide a mapping to rename the claim to sub.

This mapping ensures that Entrypage receives the correct subject identifier. This is a special exception to the rule that system claims cannot be targeted.

The following claim map demonstrates how to rename a non-standard subject identifier to sub:

mode: merge
claims:
    - source: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
      target: sub

Examples

The following examples illustrate how to use claim-mapping.

Adding a Static Claim

This example uses merge mode to add a new, static claim to the user’s profile. A target of provider is specified with a static value of github. Since there’s no source property, this claim is simply appended without altering any existing claims. This is particularly useful for identifying the origin of a user’s account.

mode: merge
claims:
  - target: provider
    value: github

Data-Minimization Through Claims Mapping

By default, Entrypage imports all claims of a federated user and copies them to your domain. However, under GDPR, this may not be desirable as you must have a valid reason for processing user data.

By using a claim map, you can specify exactly which user attributes are imported and which are omitted.

This example uses filter mode to ensure that only a specific set of claims is imported from the external identity provider; all other claims are omitted.

  • The login, avatar_url, email, and name claims are explicitly included.
  • login is renamed to preferred_username.
  • avatar_url is renamed to picture.

The sub claim, which is used for unique user IDs, is automatically overwritten by Entrypage. To preserve the original external ID, the id claim is mapped to external_id.

A static provider claim with the value github is added. This is a best practice to help you differentiate between users from various identity providers, as sub claims are not guaranteed to be unique across them.

mode: filter

# Omit all claims except:
claims:
  - source: login
    target: preferred_username
  - source: avatar_url
    target: picture
  - source: email
  - source: name

  # The 'sub' claim is overwritten by Entrypage to guarantee
  # unique IDs within the domain. This creates a new claim
  # containing the original external ID:
  - source: id
    target: external_id

  # It is strongly recommended to add a claim that indicates
  # the identity provider, since 'sub' claims are not guaranteed
  # to be unique across different external providers.
  - target: provider
    value: github

Usernames for Federated Users

By default, Entrypage uses the format {external identifier}@{federated domain} as the username for federated users. This is because Entrypage enforces a unique constraint on the combination of identity-provider and username, not on the username alone. This default ensures that usernames from different providers won’t clash.

However, you can configure Entrypage to use a different claim as the username through a claim map.

The example you provided uses merge mode to rename the email claim to preferred_username. This transformation effectively makes the user’s email address their username in Entrypage, rather than the default {external identifier}@{federated domain} format.

mode: merge
claims:
  - source: email
    target: preferred_username

This configuration renames the email claim to preferred_username. The original value of the email claim is kept under this new name, while all other claims from the external provider remain unchanged. Functionally, this means the user’s email address will be used as their username in Entrypage.