Keycloak SAML Identity Provider Configuration

This document outlines the process for configuring SAML identity providers in Keycloak for Willba. It covers the common configuration steps for all SAML providers, with provider-specific details where needed.

Prerequisites

Before configuring Keycloak, you should have:

• SAML metadata file from the identity provider (Google Workspace or Microsoft Entra ID)
• Information about attribute mappings from the identity provider
• Details about group mappings if applicable

Common Configuration Steps

1. Login as realm-admin into Keycloak console
2. Open Identity Providers from main menu
3. Add new provider with option SAML
4. Set Alias with unique name if you have multiple identity providers in one environment
5. Set Display name with descriptive name. It will be shown in the Willba login screen main button. If you have multiple identity providers in one environment, users can select the correct one by this name.
6. Set Display order to 1. If multiple providers, set 2 for the second and so on. Willba Support team Admin login is reserved with Display order 100.
7. Switch Use entity descriptor OFF
8. Import config from the metadata file provided by the customer
9. Specify settings
10. Save
11. Specify mappers
12. Verify connection works

Common Settings

Setting	Value	Description
NameID policy format	Email
Principal type	Subject NameID
Allow create	On	Important, let SAML create Willba users on first login
HTTP-POST binding response	On
HTTP-POST binding for AuthnRequest	On
Comparison	exact
Trust Email	On	Do not require email verification
First login flow	first broker login
Post login flow	None
Sync mode	Force	Important setting to force sync user properties at every login

Common Mappers

The following mappers are common for all SAML providers. Create these mappers to import values from the Identity Provider into Willba.

First Name and Last Name Mappers

Google Workspace

For Google Workspace, create the following mappers:

First Name:

• ID: firstName
• Name: firstName
• Sync mode override: Inherit
• Mapper type: Attribute Importer
• Attribute Name: firstName
• Friendly Name:
• Name Format: ATTRIBUTE_FORMAT_BASIC
• User Attribute Name: firstName

Last Name:

• ID: lastName
• Name: lastName
• Sync mode override: Inherit
• Mapper type: Attribute Importer
• Attribute Name: lastName
• Friendly Name:
• Name Format: ATTRIBUTE_FORMAT_BASIC
• User Attribute Name: lastName

Microsoft Entra ID

For Microsoft Entra ID, create the following mappers:

First Name:

• ID: firstName
• Name: firstName
• Sync mode override: Inherit
• Mapper type: Attribute Importer
• Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
• Friendly Name:
• Name Format: ATTRIBUTE_FORMAT_BASIC
• User Attribute Name: firstName

Last Name:

• ID: lastName
• Name: lastName
• Sync mode override: Inherit
• Mapper type: Attribute Importer
• Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
• Friendly Name:
• Name Format: ATTRIBUTE_FORMAT_BASIC
• User Attribute Name: lastName

Email:

• ID: email
• Name: email
• Sync mode override: Inherit
• Mapper type: Attribute Importer
• Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
• Friendly Name:
• Name Format: ATTRIBUTE_FORMAT_BASIC
• User Attribute Name: email

Group Mappers

Create a mapper for each user group you want to import into Willba from the identity provider.

Google Workspace

For Google Workspace, create group mappers with:

• ID: {groupName}, for example Housekeeping
• Name: User Group {groupName}, for example User Group Housekeeping
• Sync mode override: Force
• Mapper type: Advanced Attribute to Group
• Attributes:
  • Key: groups
  • Value: {group-exact-name-in-google-workspace}
• Regex Attribute Values: Off
• Group: Select correct Willba group name

Microsoft Entra ID

For Microsoft Entra ID, create group mappers with:

• ID: {groupName}, for example Housekeeping
• Name: User Group {groupName}, for example User Group Housekeeping
• Sync mode override: Force
• Mapper type: Advanced Attribute to Group
• Attributes:
  • Key: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
  • Value: {group-identifier-in-entra-id}
• Regex Attribute Values: Off
• Group: Select correct Willba group name

tip

The group identifier in Entra ID is typically a UUID. You can find this by examining the SAML response or checking the group properties in the Microsoft Entra ID portal.