Configure PKCE and Claim Mapping for OIDC Connections

Enterprise connections using OpenID Connect or Okta Workforce as the identity provider can support Proof Key for Code Exchange (PKCE), as well as attribute and token mapping. 

OpenID Connect and Okta Workforce connections are automatically configured to support Proof Key for Code Exchange (PKCE).

If your OIDC identity provider (IdP) supports PKCE through OIDC Discovery metadata, Auth0 will use the strongest algorithm available by default. For more information on OIDC Discovery metadata, review OpenID’s documentation. 

You can view the PKCE configuration for a specific connection through the Auth0 Dashboard:

1. Navigate to Authentication > Enterprise and choose your OIDC provider (either OpenID Connect or Okta Workforce).

2. Select the Settings tab.

3. In the General section, locate the Connection Profile field.

curl --request POST \
--url 'https://{yourDomain}/api/v2/connections' \
--header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
--data '{ 
  "strategy": "oidc", 
   "name": "CONNECTION_NAME", 
   "options": { 
     "type": "back_channel", 
     "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", 
     "client_id" : "IDP_CLIENT_ID", 
     "client_secret" : "IDP_CLIENT_SECRET", 
     "scopes": "openid profile", 
     "connection_settings": { "pkce": "auto" }
               } 
          }'

curl --request POST \
  --url 'https://{yourDomain}/api/v2/connections' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --data '{
    "strategy": "oidc",
    "name": "CONNECTION_NAME",
    "options": {
      "type": "back_channel",
      "client_id": "IDP_CLIENT_ID",
      "client_secret": "IDP_CLIENT_SECRET",
      "connection_settings": { "pkce": "auto" },
      "issuer": "https://IDP_DOMAIN",
      "authorization_endpoint": "https://IDP_DOMAIN/authorize",
      "jwks_uri": "https://IDP_DOMAIN/.well-known/jwks.json",
      "scopes": "openid profile",
      "oidc_metadata": {
        "issuer": "https://IDP_DOMAIN",
        "authorization_endpoint": "https://IDP_DOMAIN/authorize",
        "jwks_uri": "https://IDP_DOMAIN/.well-known/jwks.json",
        "token_endpoint": "https://IDP_DOMAIN/token/refresh",
        "code_challenge_methods_supported": ["plain", "S256"]
      }
    }
  }'

Auth0 supports the following values for PKCE configuration:

OpenID Connect and Okta Workforce connections can automatically map claims received from the identity provider (IdP). You can configure this mapping through a library template provided by Auth0 or by entering your own template directly.

Mapping templates support the options.attribute_map object properties listed below. Templates must be in JSON format with valid key/value pairs.

The mapping_mode property defines the method used to map incoming claims from the IdP to the Auth0 user profile. mapping_mode supports the following values:

Some claims are reserved for use by Auth0; such claims cannot be used as attribute keys for user profiles.

If you set the mapping_mode property to bind_all, your IdP may attempt to map values to one or more of these restricted claims. While this does not prevent users from authenticating on your connection, values associated with restricted claims are not mapped to the Auth0 user profile.

If you set mapping_mode to use_map, you can map the incoming restricted claim to a valid one:

"attribute_map": {
        "mapping_mode": "use_map",
        "attributes": {
            "amr": "{context.tokenset.amr}" // `amr` is a restricted claim and will not be mapped
            "federated_amr": "{context.tokenset.amr}" // `federated_amr` is not a restricted claim and will be mapped
        }
    }

For a complete list of restricted claims, review Create Custom Claims.

The userinfo_scope property defines the scopes that Auth0 sends to the IdP’s UserInfo endpoint when requested.

For example, if you want to send the standard OIDC scopes and the groups scope when requesting the UserInfo endpoint, you can do so as follows:

"attribute_map": {
    . . .
    "mapping_mode": "bind_all",
    "userinfo_scope": "openid email profile groups",
    . . .
}

The attributes property is an object containing mapping information that allows Auth0 to interpret incoming claims from the IdP. Mapping information must be provided as key/value pairs.

The key to the left corresponds to an Auth0 user profile attribute. The value to the right represents the incoming claim from the IdP, which can be expressed as a literal value, a dynamic context object, or a combination of both. Dynamic context objects are template expressions written in the familiar ${variable} format.

"attribute_map": {
    . . .
    "attributes": {
        "name": "${context.tokenset.name}",
        "email": "${context.tokenset.email}",
        "username": "${context.tokenset.preferred_username}"
    }
}

A literal value is a static value mapped to a specific profile attribute for all users on your connection.

For example, if you are configuring a SalesForce OIDC connection and want to assign the same SFDC Community ID to all user profiles, you can do so as follows:

"attribute_map": {
    . . .
    "attributes": {
        …
        "sf_community_id": "3423409219032-32"
    }
}

You can map dynamic values to user profile attributes by using the context object. This allows you to store unique values for individual profiles, as opposed to literal values that are static across all profiles.

The context object supports the following properties:

This example demonstrates how to map common user claims to the Auth0 user profile with data from the ID token:

"attribute_map": {
    . . .
    "attributes": {
        "name": "${context.tokenset.name}",
        "email": "${context.tokenset.email}",
        "username": "${context.tokenset.preferred_username}"
    }
}

This example shows how to map groups to the Auth0 user profile from the incoming IdP:

"attribute_map": {
    . . .
    "attributes": {
        "federated_groups": "${context.userinfo.groups}",
        "federated_locale": "${context.userinfo.locale}",
        "federated_zoneinfo": "${context.userinfo.zoneinfo}"
    }
}

This example demonstrates how to combine literal values and dynamic template expressions to map a complex value to an attribute on the Auth0 user profile:

"attribute_map":{
    . . .
    "attributes": {
        "alt_id": "user_email|${context.tokenset.email}",
        . . .
    }
}