Use different ID for the sub

Is it possible to use something other that the UUID from Keycloak as the ‘sub’ field in the token? I have a different unique identifier for my users that I would prefer to have as the ‘sub’ if possible.

You have multiple options, for example one of them is just adding an attribute for each user with the value for uuid you would like.

There is another option that includes a script, in old Keycloak versions you could add a script mapper from the UI and then override the value of ‘sub’ for example, in the latest versions you will have to check out how to enable this feature, haven’t tried it my self yet.

The latter of the two would be ideal. Do you have any links or references the script mapper? I will do some investigation to see what I can find. Many thanks for the suggestions.

No sorry, I don’t have some links with a good documention about this but I have found that it is called ‘custom authenticator’ nowadays.
So just search for this and I’m sure you will find what you need.

content of your script could be (untested):

//The user and the username attribute always should be there and not be empty, so the null checks could be omitted…
if (user && user.username && user.username.trim()) {
token.setOtherClaims(“sub”, user.username);

You have to start Keycloak with the
-Dkeycloak.profile.feature.scripts=enabled -Dnashorn.args=–no-deprecation-warning
options to have the script mapper in the list of the available mapper types.

In the mapper options configure the mapper as singlevalue string type.
But I am not sure if it is a good idea to overwrite the sub claim…



You can create a script mapper. The code :


But special features need to be enabled :

-Dkeycloak.profile.feature.scripts=enabled  -Dkeycloak.profile.feature.upload_scripts=enabled

if you use docker, same settings can be passed to keycloak with the JAVA_OPTS_APPEND environment variable.

Script mapper looks like a workaround to solve a keycloak issue : if you try to create a “user property” mapper to override the default value for the sub claim (based on the “username” property for instance), you will end up with two “sub” claims : one with the keycloak id, one with the username.

Couple of quick questions, and for clarification, I am using Red Hat Single Sign-On v7.4, which is Keycloak v9.0.3 under the hood.

I have enabled the preview features by adding the file and I can confirm that the SCRIPTS Preview Feature is enabled in the Server Info view. However, in my Realm Clients under that Mappers section I do not see where I can add a Script Mapper. Am I looking in the right place to add a Script Mapper? Where should that option appear when enabled?

I have added a Script Mapper to my deployment JAR successfully and it does show up in the Admin UI when I “Create Protocol Mapper” but my script does not appear to do anything when added. If I use the route of deploying my own Script Mapper in my deployment JAR what is the correct way to enable a Script Mapper in the UI and then debug it if needed?