Contents x
    Keycloak
      • Print
      • Dark
        Light
      • PDF
      Contents

      Keycloak

        • Print
        • Dark
          Light
        • PDF
        Article summary

        Keycloak is an open-source identity and access management solution supporting user federation, OAuth, SAML, and OpenID Connect protocols. QuickMeet.Chat integrates with Keycloak using SAML, enabling secure management of users and resources. This guide explains how to configure Keycloak with QuickMeet.Chat using SAML for users to log in with their Keycloak credentials.

        Prerequisites

        • A QuickMeet.Chat workspace (e.g., https://test-quickmeet.chat).

        • A Keycloak server (e.g., https://keycloak.test.com).

        • A Keycloak realm set up for use (e.g., master). This guide references the realm using the placeholder <realm>.

        • Your Keycloak realm must have the SAML identity provider and the RS256 algorithm configured as the keystore provider.

        Set up Keycloak in QuickMeet.Chat

        To begin, configure Keycloak in your QuickMeet.Chat workspace. Follow these steps in the SAML configuration section of QuickMeet.Chat settings:

        1. Go to Administration > Workspace > Settings > SAML

        2. Enable the SAML connection in QuickMeet.Chat.

        3. Set the Custom Provider to keycloak.

        4. Configure the Custom Entry Point and IDP SLO Redirect URL:

          1. In your Keycloak server, go to Realm Settings.

          2. Under the General tab, select SAML 2.0 Identity Provider Metadata from the Endpoints section. This will open an XML file containing the necessary URLs.

          3. Copy the appropriate URL, such as https://<your-keycloak-server>/realms/<realm>/protocol/saml, and paste it into both the Custom Entry Point and IDP SLO Redirect URL fields in QuickMeet.Chat.

        5. Set the Custom Issuer to https://<your-workspace>/_saml/metadata/keycloak.

        Configure certificates

        To ensure secure communication between Keycloak and QuickMeet.Chat, configure the required certificates under QuickMeet.Chat SAML settings:

        1. Obtain the RS256 certificate:

          1. In Keycloak, navigate to Realm Settings and open the Keys tab.

          2. Copy the RS256 certificate and paste it into the Custom Certificate field in QuickMeet.Chat.

        2. Generate a certificate pair for QuickMeet.Chat:

          • Run the following OpenSSL command to generate a public certificate and a private key:

          openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

          1. This command creates two files:

            • saml.crt: The public certificate.

            • saml.pem: The private key.

          2. Copy the contents of these files and update the respective fields in QuickMeet.Chat:

            1. Public Cert Contents: Paste the contents of saml.crt.

            2. Private Key Contents: Paste the contents of saml.pem.

        3. Set the Signature Validation Type to Validate Either Signature.

        4. Click Save Changes.

        Configure Keycloak client

        After setting up SAML in QuickMeet.Chat, the next step is to configure a Keycloak client that will handle authentication between users on your Keycloak server and QuickMeet.Chat workspace. This client will manage the exchange of user information, allowing users to authenticate securely on QuickMeet.Chat using their Keycloak credentials.

        Follow the steps below to configure the Keycloak client:

        Download the SAML metadata XML file

        1. Go to https://<workspace-url>/_saml/metadata/keycloak. You’ll get an XML file. Ensure SAML is enabled in your QuickMeet.Chat workspace to access this file.

        2. Save the raw XML file to your device.

        Import the client in keycloak

        1. Navigate to the Clients section in your Keycloak server.

        2. Click Import Client and upload the XML file you saved as the Resource file.

        3. The client Type will be set to saml, and the ClientID will be populated based on the metadata URL.

        4. Enable Client Signature Required.

        5. Click Save to create the new client. You will be redirected to a partially pre-filled client settings page.

        Configure the client settings

        1. Ensure the Client ID matches the metadata URL.

        2. Verify the Valid Redirect URIs field is set to https://<workspace-url>/_saml/validate/keycloak.

        3. Set the Name ID Format to email.

        4. Set SAML Signature Key to KEY_ID.

        5. Click Save.

        Verify the public key (certificate)

        1. Go to the Keys tab in the client and verify that the public key matches the Public Cert Contents you set in QuickMeet.Chat SAML settings.

          The -----BEGIN/END CERTIFICATE----- header/footer is not displayed in Keycloak, but the rest of the certificate should match.

        2. If the certificates do not match, click Import Key. Select Certificate PEM as the archive format and upload the saml.crt certificate file generated earlier. Then, click Import.

        Configure client scopes and attribute mappers

        1. Navigate to the Client Scopes tab for the client.

        2. Select the dedicated scope and mappers for the client (https://<workspace-url>/_saml/metadata/keycloak-dedicated).

        3. Go to the Mappers tab to create mappers for the required data that your QuickMeet.Chat workspace expects. Typically, email or username mappers aren't needed, but cn (common name) may be required.

        4. Click Configure a new mapper and select User Property as the Mapper Type.

        5. Set the SAML Attribute NameFormat to basic.

        6. For the first name:

          1. Set Name and Property to firstName.

          2. Set SAML Attribute Name to cn.

        7. Click Save.

        Authenticating Keycloak users to QuickMeet.Chat

        After completing the configuration, users can click the SAML button on the workspace login page. This action will redirect them to Keycloak’s authentication page, where they can log in with their credentials. Upon successful login, users are redirected back to their account on the workspace. You can monitor active sessions of your Keycloak users on QuickMeet.Chat by checking the Sessions tab in Keycloak.

        Creating users in Keycloak

        If you don’t have users set up in Keycloak yet, follow these basic steps to create a new user:

        1. Navigate to the Users section in Keycloak and click Create User.

        2. Fill in the required fields, then click Create.

        3. Go to the user's Credentials tab and set a password.

        You can also configure the user interface, behavior, and mapping settings according to your requirements.

        Troubleshooting

        You may run into some problems for various reasons:

        • Q: I keep getting the Unable to validate response url: Error: Status is: urn:oasis:names:tc:SAML:2.0:status:Responder error.

          • A: Make sure that the respective Keycloak user has an e-mail address. This may not be the case. For example, for the Keycloak admin.

        Was this article helpful?
        What's Next
        QuickMeet.Chat versions receive support for six months after release. End-of-life for any version is the last day of the month when support ends.