Where are all of the Keycloak Protocol Mapper Config Options documented?

Question

I'm using Keycloak's Java keycloak-admin-client and I'm wanting to set up some protocol mappers for my realm's client.

The Java API exposes this class to create a protocol mapper and then the following method to set the config options:

    ProtocolMapperRepresentation protocolMapperRep = new ProtocolMapperRepresentation();
    protocolMapperRep.setConfig(Map.of("some.mapper.config.option", "mapper-value"));

I've looked at the javadoc documentation and it's, well, completely useless unfortunately. :( I have not looked at the rest-api documentation, but I just looked at it and it doesn't do anything to enumerate the config options for the protocol mapper representation: https://www.keycloak.org/docs-api/12.0/rest-api/index.html#_protocolmapperrepresentation

I saw a few options from another StackOverflow question here: Add protocol-mapper to keycloak using kcadm.sh

However, there has to be a better place where these are documented.

Artist

Answer 1

Typically, what you can do is to first look at Rest API Documentation and the Keycloak API.

Alternatively, and this almost always work, you just create the protocol Mapper using the Keycloak Admin API, for instance:

Then before clicking Save, open your browser developer network console and look at the network requests. Then click save:

You will have two post request, one for the token, another for the creation of the mapper:

Look at the request payload, you will see something as:

{
  "protocol": "openid-connect",
  "config": {
    "multivalued": "true",
    "id.token.claim": "true",
    "access.token.claim": "true",
    "userinfo.token.claim": "true",
    "claim.name": "asdas"
  },
  "name": "asdas",
  "protocolMapper": "oidc-usermodel-realm-role-mapper"
}

Now you can infer the options from there. Not ideal I know.

Apprentice

Answer 2

The list for Keycloak 15 is the following (missing only the Pairwise Subject Identifier):

• oidc-usersessionmodel-note-mapper
• oidc-group-membership-mapper
• oidc-usermodel-attribute-mapper
• oidc-usermodel-realm-role-mapper
• oidc-audience-mapper
• oidc-usermodel-property-mapper
• oidc-hardcoded-claim-mapper
• oidc-hardcoded-role-mapper
• oidc-allowed-origins-mapper
• oidc-audience-resolve-mapper
• oidc-claims-param-token-mapper
• oidc-usermodel-client-role-mapper
• oidc-full-name-mapper
• oidc-address-mapper
• oidc-role-name-mapper

Caucasus

hey jeremie, source? – Mansell

Answer 3

I found myself here as I was looking for documentation about the different Keycloak protocol mapper types, and for anyone else who is doing the same, I can confirm that it's difficult.

The protocol mappers section in the Keycloak Server Admin guide is pretty clear that it is not going to walk users through all of the details. See the excerpt below (emphasis mine).

Protocol mappers map items (such as an email address, for example) to a specific claim in the identity and access token. The function of a mapper should be self-explanatory from its name. You add pre-configured mappers by clicking Add Builtin.

Each mapper has a set of common settings. Additional settings are available, depending on the mapper type. Click Edit next to a mapper to access the configuration screen to adjust these settings.

This is the closest thing I've found to documentation of the different protocol mapper types.

I like @dreamcrash's approach to the problem.

Byer