diff --git a/keycloak-images/add-mapper.png b/keycloak-images/add-mapper.png new file mode 100644 index 0000000000..7aa49a1fb2 Binary files /dev/null and b/keycloak-images/add-mapper.png differ diff --git a/keycloak-images/mapper-config.png b/keycloak-images/mapper-config.png new file mode 100644 index 0000000000..8e7a5b462f Binary files /dev/null and b/keycloak-images/mapper-config.png differ diff --git a/keycloak-images/mappers-oidc.png b/keycloak-images/mappers-oidc.png new file mode 100644 index 0000000000..f202df017d Binary files /dev/null and b/keycloak-images/mappers-oidc.png differ diff --git a/rhsso-images/add-mapper.png b/rhsso-images/add-mapper.png new file mode 100644 index 0000000000..7157ce768f Binary files /dev/null and b/rhsso-images/add-mapper.png differ diff --git a/rhsso-images/mapper-config.png b/rhsso-images/mapper-config.png new file mode 100644 index 0000000000..daa54444e3 Binary files /dev/null and b/rhsso-images/mapper-config.png differ diff --git a/rhsso-images/mappers-oidc.png b/rhsso-images/mappers-oidc.png new file mode 100644 index 0000000000..1f466e314d Binary files /dev/null and b/rhsso-images/mappers-oidc.png differ diff --git a/topics/clients/protocol-mappers.adoc b/topics/clients/protocol-mappers.adoc index a0e3d467c3..971a8229e6 100755 --- a/topics/clients/protocol-mappers.adoc +++ b/topics/clients/protocol-mappers.adoc @@ -1,18 +1,50 @@ [[_mappers]] -= OIDC Token and SAML Assertion Mappings +=== 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. -Keycloak allows you to define what exactly is transferred. +{{book.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" sub-menu item. -This is the place where you can control how a OIDC ID Token, Access Token, and SAML login response assertions look like. -When you click on this you'll see some default mappers that have been set up for you. -Clicking the "Add Builtin" button gives you the option to add other preconfigured mappers. -Clicking on "Create" allows you to define your own protocol mappers. -The tooltips are very helpful to learn exactly what you can do to tailor your tokens and assertions. -They should be enough to guide you through the process. +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:../../{{book.images}}/mappers-oidc.png[] + +Every client has a bunch of built-in mappers that are created for it by default. They 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's +is 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:../../{{book.images}}/mapper-config.png[] + +The best way to find out what a config option is is to moveover the tooltips. There are a few config options that +are common to all mappers. + +Consent:: + If your client requires consent, this mapper will be displayed on the consent screen shown to the user. +Consent Text:: + If your client requires consent and the `Consent` switch is on, this is the text that will be displayed by the user. + The value for this text is localizable by specifying a substitution variable with `$\{var-name}}` strings. The + localized value is then configured within property files in your theme. See the link:{{book.developerguide.link}}[book.developerguide.name] + for more information on localization. + +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. + +Finaly, you can also add other mapper types. if you go back to the `Mappers` tab, click the `Create` button. + +.Add Mapper +image:../../{{book.images}}/add-mapper[] + +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. +