ScreenSteps Help

How to Set up Single Sign-on with Keycloak

Updated on

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.

  1. Start the SAML configuration in ScreenSteps

    Change the login method to SAML for the area you are configuring:

    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.

  2. Create a SAML client in Keycloak
    1. In the Keycloak admin console, select the realm and go to Clients > Create client.
    2. Set Client type to SAML.
    3. Set Client ID to the Entity ID from ScreenSteps, exactly as shown, including https:// and the number at the end.
    4. Set Name to ScreenSteps or another label your users will recognize.
  3. Configure access settings

    On the client's Settings tab, enter these values under Access settings:

    Keycloak settingValue
    Root URLYour ScreenSteps site address, for example https://yoursite.screenstepslive.com
    Home URLYour ScreenSteps site address
    Valid redirect URIsThe SAML consumer URL from ScreenSteps
    IDP-Initiated SSO URL nameLeave blank
    Master SAML Processing URLThe 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.

  4. Configure SAML capabilities and signatures

    On the Settings tab:

    Keycloak settingValue
    Name ID formatemail
    Force POST bindingOn
    Include AuthnStatementOn
    Sign documentsOn
    Sign assertionsOn
    Signature algorithmLeave the default (RSA_SHA256)

    On the client's Keys tab:

    Keycloak settingValue
    Client signature requiredOff
    Encrypt assertionsOff

    Save the client.

  5. Stop Keycloak from repeating the Role attribute

    By default, Keycloak's role_list client scope sends a separate Role attribute 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_list to Optional.
    • Or open the role_list scope, go to Mappers, open the role list mapper, and turn on Single Role Attribute. This sends one Role attribute 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.

  6. Send the user's first and last name

    Without name attributes, ScreenSteps uses the email address as the user's name.

    1. On the client's Client scopes tab, open the dedicated scope. Its name is the Client ID followed by -dedicated.
    2. Go to Mappers > Add mapper > By configuration > User Property.
    3. Create one mapper for each row below and save it.
    NamePropertySAML Attribute NameSAML Attribute NameFormat
    First namefirstNamegivenNameBasic
    Last namelastNamesnBasic

    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.

  7. Download the Keycloak SAML metadata

    Keycloak publishes the realm's SAML metadata at:

    https://keycloak.example.com/realms/your-realm/protocol/saml/descriptor

    Replace the host and realm with your own. Some Keycloak installations include /auth in the path, for example https://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 .xml extension, for example keycloak-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 example https://keycloak.example.com/realms/your-realm/protocol/saml.
    • Certificate: go to Realm settings > Keys and click Certificate on the RS256 key. Save it to a .pem file, with -----BEGIN CERTIFICATE----- on the first line and -----END CERTIFICATE----- on the last line.
  8. Finish the configuration in ScreenSteps

    Return to the SAML configuration in ScreenSteps:

    1. 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.
    2. Confirm that the SSO or Login URL ends in /protocol/saml.
    3. Select the ScreenSteps group users should join when they sign in through Keycloak.
    4. Save the configuration.
  9. Test before activation
    1. Open the Activation tab in ScreenSteps and copy the SAML Test URL.
    2. Open a private or incognito browser window, paste the test URL, and sign in through Keycloak.
    3. Confirm that you arrive in ScreenSteps signed in, and that your name and email are correct.
    4. 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.

Previous Article How to Set up Single Sign-on with Google Workspace
Next Article How to update your certificate from Azure/Entra and add it to ScreenSteps