This guide covers the Keycloak-specific settings. For details on NameID mappings, supported assertion attributes, and how ScreenSteps matches users, see Configure a custom SAML identity provider.
Before you begin
You will need:
- Administrator access to the Keycloak realm your users sign in to
- Account Admin access in ScreenSteps
- A ScreenSteps subscription that includes Single Sign-on
- A ScreenSteps group that grants the appropriate site permissions
Turn on user events in Keycloak so you can see why a sign-in fails: go to Realm settings > Events > User events settings, turn on Save events, and save. Failed sign-ins then appear under Events > User events.
- Start the SAML configuration in ScreenSteps
Change the login method to SAML for the area you are configuring:
- The Admin/Content Management Area/Primary Site (without a custom domain)
- The Primary Site (requires a custom domain)
- Your other sites
On the Configuration tab, copy the SAML consumer URL and Entity ID. In ScreenSteps both usually have the form
https://yoursite.screenstepslive.com/saml/consume/1234.Set the NameID mapping to Email and the requested NameID format to EmailAddress. Keycloak sends the user's email address as NameID with this configuration.
- Create a SAML client in Keycloak
- In the Keycloak admin console, select the realm and go to Clients > Create client.
- Set Client type to SAML.
- Set Client ID to the Entity ID from ScreenSteps, exactly as shown, including
https://and the number at the end. - Set Name to
ScreenStepsor another label your users will recognize.
- Configure access settings
On the client's Settings tab, enter these values under Access settings:
Keycloak setting Value Root URL Your ScreenSteps site address, for example https://yoursite.screenstepslive.comHome URL Your ScreenSteps site address Valid redirect URIs The SAML consumer URL from ScreenSteps IDP-Initiated SSO URL name Leave blank Master SAML Processing URL The SAML consumer URL from ScreenSteps IDP-Initiated SSO URL name is a short name that Keycloak adds to its own address. It is not a ScreenSteps URL. ScreenSteps starts sign-in from its own side, so this field is not needed.
- Configure SAML capabilities and signatures
On the Settings tab:
Keycloak setting Value Name ID format emailForce POST binding On Include AuthnStatement On Sign documents On Sign assertions On Signature algorithm Leave the default ( RSA_SHA256)On the client's Keys tab:
Keycloak setting Value Client signature required Off Encrypt assertions Off Save the client.
- Stop Keycloak from repeating the Role attribute
By default, Keycloak's
role_listclient scope sends a separateRoleattribute for each of the user's roles. ScreenSteps rejects an assertion that repeats an attribute name, and the sign-in fails with Found an Attribute element with duplicated Name.ScreenSteps does not use Keycloak roles. Do one of the following:
- On the client's Client scopes tab, change the Assigned type of
role_listto Optional. - Or open the
role_listscope, go to Mappers, open the role list mapper, and turn on Single Role Attribute. This sends oneRoleattribute with all of the user's roles as its values.
If the client's dedicated scope also has a role list mapper, change it the same way.
- On the client's Client scopes tab, change the Assigned type of
- Send the user's first and last name
Without name attributes, ScreenSteps uses the email address as the user's name.
- On the client's Client scopes tab, open the dedicated scope. Its name is the Client ID followed by
-dedicated. - Go to Mappers > Add mapper > By configuration > User Property.
- Create one mapper for each row below and save it.
Name Property SAML Attribute Name SAML Attribute NameFormat First name firstNamegivenNameBasic Last name lastNamesnBasic You do not need email or username mappers. With the Email NameID mapping, ScreenSteps uses the NameID as both the user's email and login.
- On the client's Client scopes tab, open the dedicated scope. Its name is the Client ID followed by
- Download the Keycloak SAML metadata
Keycloak publishes the realm's SAML metadata at:
https://keycloak.example.com/realms/your-realm/protocol/saml/descriptorReplace the host and realm with your own. Some Keycloak installations include
/authin the path, for examplehttps://keycloak.example.com/auth/realms/your-realm/protocol/saml/descriptor. Use the form your Keycloak server uses.Open the URL in a browser and save the page as a file with an
.xmlextension, for examplekeycloak-metadata.xml. The file contains the Keycloak sign-in URL and the realm's signing certificate.If you cannot use the metadata file, enter the values manually instead:
- SSO URL: the metadata URL without
/descriptor, for examplehttps://keycloak.example.com/realms/your-realm/protocol/saml. - Certificate: go to Realm settings > Keys and click Certificate on the
RS256key. Save it to a.pemfile, with-----BEGIN CERTIFICATE-----on the first line and-----END CERTIFICATE-----on the last line.
- SSO URL: the metadata URL without
- Finish the configuration in ScreenSteps
Return to the SAML configuration in ScreenSteps:
- Upload the Keycloak metadata file. ScreenSteps fills in the SSO URL and certificate from it. If you are entering the values manually, enter the SSO URL and upload the certificate file instead.
- Confirm that the SSO or Login URL ends in
/protocol/saml. - Select the ScreenSteps group users should join when they sign in through Keycloak.
- Save the configuration.
- Test before activation
- Open the Activation tab in ScreenSteps and copy the SAML Test URL.
- Open a private or incognito browser window, paste the test URL, and sign in through Keycloak.
- Confirm that you arrive in ScreenSteps signed in, and that your name and email are correct.
- If the sign-in fails, check Events > User events in Keycloak, then see the troubleshooting section below.
After the test passes, activate the identity provider in ScreenSteps.
Troubleshooting
Keycloak logs client_not_found
The Keycloak event shows client_not_found, often with the reason Cannot_match_source_hash. The client's Client ID does not match the ScreenSteps Entity ID. Set the Client ID to the exact Entity ID shown in ScreenSteps.
Keycloak logs invalid_signature
Keycloak is requiring a signed sign-in request. On the client's Keys tab, turn off Client signature required and save.
ScreenSteps shows "Found an Attribute element with duplicated Name"
Keycloak sent the Role attribute once per role. Set the role_list client scope to Optional or turn on Single Role Attribute, as described in step 5.
Users sign in but their name is their email address
Keycloak is not sending name attributes. Add the givenName and sn mappers described in step 6. ScreenSteps updates the user's name the next time they sign in.
Keycloak returns to ScreenSteps without signing the user in
If the user lands back on ScreenSteps without being signed in, Keycloak rejected the request before sending a response. Check Events > User events in Keycloak for the error.
The certificate or signature is rejected
Confirm that ScreenSteps has the current certificate from the realm's RS256 key. If the realm's keys were rotated, download the metadata again and upload it to ScreenSteps.