mappers

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.
+