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.