There are largely two ways user profile information can get added to the issued JWT Tokens

User Attribues

This is where long lived profile information should be saved.These are best used for static data about a user. Once created, data unlikely to change frequently.

Realm > Realm Settings > User profile

By default – username, firstname, lastname and email are there.

You may add for example – employeeID, Date of Birth, account expiry date, mobile number, department, type of employment etc etc.

Create Attribute > Complete the form and fill in all details.

Few things of note

1. Who Can View
2. Who Can Edit – Can user themsleves edit the data…..
3. Validations: Length of data, regex patterns, emaiulk form,at etc. Thonf of this as enforing valdiation on data submitted
4. Annotations: Typcially I use it to control how the data entry fiueld appears in a HTML form for this field – Example Input Type may be text, textarea, radiobuttons multiselect-checkboxes etc

Remeber: If its multiselect, then the option “Multivalued” should be On

Client Scopes

This governs whihc attributes will appear in tokens

Realm > Client Scopes > Create Client Scope

Create a new Client Scope

1. Name – “realm-user-profile“.
2. Descrition – User Information mapped from User Attributes
3. Type – Default
4. Include in OpenID Provider Metadata- On
5. Save.

Then add mappers for user attributes to this client scope. mappers are bvasically mapping any defined property to something that is included in tokens. Think of it as a mechanism to ensure only the required information is sent to third party applications that connect to your SSO. Rest all is only part of the user identity but not shared with third parties.

Mappers – Map the attribute to a Client Scope

Client Scopes > realm-user-profile > Mappers > Add Mapper

Select “By Configuration“. In the pop-up that appears, select “User Attribute“

1. Name: Name of the mapper – suggested – attributename_mapper
2. User Attribute: Link to a user attribute defined above
3. Token Claim Name – Name of the claim to insert into the token. This can be a fully qualified name such as ‘address.street’. In this case, a nested JSON object is created. To prevent nesting and use dot literally, escape the dot with a backslash (\.).
4. Claim JSON Type: JSON type that should be used to populate the json claim in the token. long, int, boolean, String and JSON are valid values.. I normally use String.
5. Add to ID token: Should the claim be added to the ID token? On
6. Add to access token – Should the claim be added to the access token?: Off
7. Add to lightweight access token – : Off
8. Add to userinfo – Should the claim be added to the userinfo : On
9. Add to token introspection: Off
10. Multivalued: Indicates if attribute supports multiple values. If true, the list of all values of this attribute will be set as claim. If false, just first value will be set as claim – On / Off <– PAY CAREFULL ATTENTION. DEPENDS ON USER ATTRIBUTE.
11. Aggregate attribute values: Indicates if attribute values should be aggregated with the group attributes. If using OpenID Connect mapper the multivalued option needs to be enabled too in order to get all the values. Duplicated values are discarded and the order of values is not guaranteed with this option. OFF

Keep adding mappers one by one for each user attribute.

Clients – add client scope to the client

In this step, we ensure that the client apps receive teh just configured parameters in the tokens

Realm > Clients > Client Scopes

Click “Add Client Scope” button. Select the “realm-user-profile” client scope that was just created. Add it as a “Default” scope for the data to always appear for that client app in tokens.

Groups

Groups are another good way to easly visually manage users in the realm.

1. Groups may have child-groups – forming a branching hierarchy
2. Groups and child-groups may have group/child-group level attributes
3. One user may be a part of multiple Groups and Child-groups

This features make groups incredibly versatile. Example – Departments (with each department as sub-group), User type (resident, faculty, lab tech), IT Roles (user_manager, app_admins) etc. One user can be part of one department group, may be a doctor and may also be an app_admin.

1. Realm > Groups > Create Group say Departments was created
2. Realm > Groups > Departments > Child Groups . Click Create Group to add admin, finance, stores, engioneering, etc departments as sub-groups/child-groups
3. Realm > Groups > Departments > finance > Atttributes . Click “Add attributes” . Type the key/attribute name and its value that may be mapped as part of token. Ensure same key is used for all child groups of a main group. Eg. dept_id key is used for all inidvidual departments. The value will vary for each department.
4. Realm > Groups > Departments > finance > Members – To add users / members to that child-group

Now lets add the dept_id to the mapper

Add Groups to mapper

Client Scopes > realm-user-profile > Mappers . You will already be having somne user attribute mappers created above.

Add Mapper > By Configuration > Group Membership

1. name: groups_mapper
2. Token Clam name: groups
3. Add to ID token: On

This will add group Information to the token

Add Group Attributes to mapper

Add Mapper > By Configuration > User Atttribute

1. name: groups_dept_id_mapper
2. User Attribute: Custom Attribute. Type a key = dept_id
3. Token Claim name: department_id
4. Claim JSON Type = String
5. Multivalued = On

Thats it folks.

Now you have a way of expertly adding various user attributes to the ID tokens issued after successful auth in KeyCloak. You can also assign users to multiple groups and expose their group memberships and group attributes. You may create two types of Client Scopes – Brief, detailed and choose to assign bief scope to certain clients and detailed scope to others !