keycloak-scim/server_admin/topics/clients/protocol-mappers.adoc

[[_protocol-mappers]]

=== OIDC Token and SAML Assertion Mappings

Applications that receive ID Tokens, Access Tokens, or SAML assertions may need or want different user metadata and roles.
{project_name} allows you to define what exactly is transferred.
You can hardcode roles, claims and custom attributes.
You can pull user metadata into a token or assertion.
You can rename roles.
Basically you have a lot of control of what exactly goes back to the client.

Within the Admin Console, if you go to an application you've registered, you'll see a `Mappers` tab.  Here's one for
an OIDC based client.

.Mappers Tab
image:{project_images}/mappers-oidc.png[]

The new client does not have any built-in mappers, however it usually inherits some mappers from the client scopes as described
in the <<_client_scopes, client scopes section>>. Protocol mappers map things like, for example, email address to
a specific claim in the identity and access token.  Their function should each be self explanatory from their name.  There
are additional pre-configured mappers that are not attached to the client that you can add
by clicking the `Add Builtin` button.

Each mapper has common settings as well as additional ones depending on which type of mapper you are adding.  Click the `Edit` button
next to one of the mappers in the list to get to the config screen.

.Mapper Config
image:{project_images}/mapper-config.png[]

The best way to learn about a config option is to hover over its tooltip.

Most OIDC mappers also allow you to control where the claim gets put.  You can opt to include or exclude the claim from both the
_id_ and _access_ tokens by fiddling with the `Add to ID token` and `Add to access token` switches.

Finally, you can also add other mapper types.  If you go back to the `Mappers` tab, click the `Create` button.

.Add Mapper
image:{project_images}/add-mapper.png[]

Pick a `Mapper Type` from the list box.  If you hover over the tooltip, you'll see a description of what that mapper type does.
Different config parameters will appear for different mapper types.

==== Priority order

Mapper implementations have _priority order_. This priority order is not the configuration property of the mapper; rather, it is
the property of the concrete implementation of the mapper.

Mappers are sorted in the admin console by the order in the list of mappers and the changes in the token or assertion will be
applied using that order with the lowest being applied first. This means that implementations which are dependent on other
implementations are processed in the needed order.

For example, when we first want to compute the roles which will be included with a token, we first resolve audiences based on
those roles. Then, we process a JavaScript script that uses the roles and audiences already available in the token.

[[_protocol-mappers_oidc-user-session-note-mappers]]
==== OIDC User Session Note Mappers

User session details are via mappers and depend on various criteria. User session details are automatically included when you use or enable a feature on a client. You can also click the `Add builtin` button to include session details.

Impersonated user sessions provide the following details:

* `IMPERSONATOR_ID`: The ID of an impersonating user
* `IMPERSONATOR_USERNAME`: The username of an impersonating user

Service account sessions provide the following details:

* `clientId`: The client ID of the service account
* `clientAddress`: The remote host IP of the service account authenticated device
* `clientHost`: The remote host name of the service account authenticated device