76 lines
3.9 KiB
Text
76 lines
3.9 KiB
Text
[[_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
|
|
|
|
==== Script Mapper
|
|
|
|
The `Script Mapper` allows you to map claims to tokens by running a user-defined JavaScript code. For more details about how to
|
|
deploy scripts to the server, please take a look at link:{developerguide_jsproviders_link}[{developerguide_jsproviders_name}].
|
|
|
|
Once you have your scripts deployed, you should be able to select the scripts you deployed from the list of available mappers.
|