...

• Setup of SAML SSO in Keycloak for Folio via the Keycloak Administrative Console
• Keycloak is very flexible in regards to how SSO is configured.  This guide focuses on providing the behavior Folio users are already accustomed to using.  Other behavior/flows are out of scope for this guide.
• While the necessary steps can most likely be performed via API calls, that is out of scope for this guide.
• Keycloak v22.x or v23- v25.x.  The steps documented here have not been tested/verified on other versions.
• Creation/management of users in Folio is out of scope for this guide.

...

Use the "EmailAddress" attribute from the SAML response, to match the "email" attribute on the Keycloak user record

• Give the mapper a "Name", e.g. "external_system_idemail"
• "Sync mode override":  "Force"
• "Mapper type":  "Attribute Importer"
• "Attribute Name":  "EmailAddress"
  1. This will select the SAML Response's EmailAddress attribute 
• "Friendly Name":  <leave blank>
• "Name Format":  "ATTRIBUTE_FORMAT_BASIC"
• "User Attribute Name":  "email"

Open Questions

...

NOTE: In order for this to work, we need to also set the following on the main "Provider Details" form:

• Principal type:  "Attribute [Name]"
• Principal attribute:  "EmailAddress"

Recipe (externalSystemId):

Use the "Subject NamdID" from the SAML response, to match the "external_system_id" attribute on the Keycloak user record

• Give the mapper a "Name", e.g. "external_system_id"
• "Sync mode override":  "Force"
• "Mapper type":  "Attribute Importer"
• "Attribute Name":  "Subject NameID"
  1. This will select the SAML Response's Subject → NameID (Hint: in the example SAML response above this value is LxyImDFLVb4jnlOayJIybA77mZw6)
• "Friendly Name":  <leave blank>
• "Name Format":  "ATTRIBUTE_FORMAT_BASIC"
• "User Attribute Name":  "external_system_id"

N.B.  As of 29 Jan 2024 the external_system_id user attribute is not currently set/migrated from user records in Folio to Keycloak.  However, there are plans to add this soon.  Keep in mind that you can always manually add/set arbitrary user attributes in Keycloak for testing purposes.

Tips/Tricks

This section provides some tips/tricks which may or may not be helpful to you, based on various factors.

I can't find my Subject NameID

This one may be specific to SSOCircle...  In some cases I've seen that the SAML response doesn't include the expected information, including assertions and even the Subject's NameID, until you do something like the following:

1. In step 6 of "Add an Identity Provider", you specify "Allow Create": "off" and specify the "Detect and Set Existing User" flow you created earlier in the process.  The trick here is to basically undo those changes, setting "Allow Create": "on", and change the flow to "First broker login".  
2. Attempt to login again.  
3. Keycloak will probably present you with a form for creating a new user since one couldn't be found.  The form will be prepopulated with the Subject's NameID.  Copy this for later use.
4. Repeat step 6 of "Add an Identity Provider" to turn Allow Create off and specify your Detect and Set Existing User flow.
5. Now when you login, if you inspect the SAML response, you should see the assertions and the Subject's NameID. 

Explore options for the automatic creation of Identity Provider links in Keycloak (SSO)

Custom extension to map folio user to identity provider's subject name id 

Currently, Keycloak cannot map SubjectNameId to any custom user attributes; it can only compare it with a username or email address. That's why we need to build our own custom external provider to map the external_system_id attribute of the Keycloak user to the SubjectNameId.

POC extension implementation for detecting Keycloak users by custom attribute

Link on the code https://github.com/folio-org/folio-keycloak/tree/KEYCLOAK-14-investigate-options-for-automatic-creation-of-identity-provider-links-in-keycloak-sso

The extension has been implemented to find the user based on a custom attribute. The attribute name is currently hardcoded but needs to be made configurable. The rest can be used as is. 

How to install an extension into Keyclok 

To add extensions, you need to build a .jar file. An example can be found as an outcome from the POC. Place this file into the libs folder of the folio-keycloak project. The rest will happen automatically."

How to configure the authorization flow to use the new extension

To detect Folio users, a custom flow must be created using two steps. The first step is our custom extension, which finds an existing user by the externalId attribute, and the second step is the default step to link the identity provider to the user.

Image Added

Open Questions

• TBD
• Is there a way for Folio admins (who don't have access to Keycloak Administrative Console) to see some basic info? e.g. IdP Mappers - which SAML attr maps to which Folio user field