# Integrate Cloud Voice with Red Hat SSO

Linking Cloud Voice to Red Hat SSO (single sign-on) lets your organization manage voice-service identities alongside the rest of your Red Hat accounts. Once the trust is established, staff sign in to the Cloud Voice App with their Red Hat credentials, and you can pull those user records into Cloud Voice. This guide covers the full setup: preparing resources in Red Hat SSO, importing that configuration into Cloud Voice, and registering Cloud Voice back as a SAML client. SAML (Security Assertion Markup Language) is the standard the two systems use to exchange the sign-in information that proves who a user is.

:::note
The examples here use Keycloak 20.0.5. Menu labels and navigation paths in your Red Hat SSO console may look slightly different, but the settings you configure are identical.
:::

## Requirements

| Platform | Requirement |
| --- | --- |
| Red Hat SSO | Version 7.6 or later recommended |
| Cloud Voice | **Firmware:** 84.21.0.16 or later (see the [firmware dependency reference](/pbx/integrations/red-hat/firmware-dependency-reference/) for feature-specific minimums)<br />**Plan:** Enterprise or Ultimate |

## Step 1: Prepare resources and credentials in Red Hat SSO

Before Cloud Voice can talk to Red Hat SSO, you need to build out a few resources on the Red Hat side and collect the credentials that authorize the two systems to exchange data. Working in the Red Hat SSO admin console, you will:

1. Create a realm and add signing keys.
2. Add the users who will sign in to the Cloud Voice App with Red Hat credentials.
3. Create an OpenID Connect (OIDC) client so Cloud Voice can synchronize users.
4. Export the realm metadata for later import into Cloud Voice.

### Create a realm and add realm keys

A realm gives you a dedicated space to manage user identities and single sign-on.

1. Sign in to the Red Hat SSO admin console with an administrator account.
2. Create the realm:
   1. At the top of the left pane, click **master**, then choose **Create Realm**.

      ![Create Realm option in the Red Hat SSO realm selector](/images/pbx/create-realm.png)
   2. Type a name in the **Realm name** field and click **Create**. The console switches to the new realm automatically.

      ![Naming a new realm in the create-realm form](/images/pbx/realm-name.png)
3. Add realm keys so the realm can sign and encrypt messages:
   1. In the left navigation bar, click **Realm settings**.
   2. Open the **Keys** tab and click **Providers**.
   3. Click **Add provider** and select **rsa-generated** to create an RSA key pair with a self-signed certificate.

      
      ![Cloud Voice, adding an rsa-generated key provider to the realm](/images/pbx/rsa-provider.png)

      :::note
      Cloud Voice accepts at most **5** certificates. Metadata that contains more than five certificates cannot be imported.
      :::

### Add users

1. In the left navigation bar, click **Users**.
2. On the **User list** tab, click **Create new user**.

   ![Create new user button on the user list](/images/pbx/create-user.png)
3. Fill in the details for the user.

   :::caution
   The email address is the unique key Red Hat SSO uses to decide whether a user is eligible for single sign-on, so set it carefully.

   - To match on the built-in **Email** field, enter the address there.

     ![Entering an address in the built-in Email field](/images/pbx/builtin-email.png)
   - To match on a custom email attribute instead, add the attribute and set its key and value.

     ![Adding a custom email attribute with key and value](/images/pbx/user-attribute.png)
   :::
4. Click **Save**.

### Create an OIDC client

The OIDC client is what allows Cloud Voice to synchronize users from Red Hat SSO.

1. In the left navigation bar, click **Clients**.
2. Create the client:
   1. On the **Clients list** tab, click **Create client**.

      ![Create client button on the clients list](/images/pbx/create-oidc%20-client.png)
   2. Configure the client using the values below, then click **Save**.

      
      ![Cloud Voice, OIDC client configuration form](/images/pbx/ocid-setup.png)

      | Setting | Value |
      | --- | --- |
      | Client type | Choose **OpenID Connect**. |
      | Client ID | Enter a name that identifies the client. |
      | Client authentication | Turn this on. |
      | Authentication flow | Select **Service accounts roles** so the client can obtain an access token. |
3. Record the client credentials:
   - **Client ID**: copy it from the **Settings** tab.

     
     ![Cloud Voice, client ID shown on the Settings tab](/images/pbx/client-id.png)
   - **Client Secret**: copy it from the **Credentials** tab.

     
     ![Cloud Voice, client secret shown on the Credentials tab](/images/pbx/client-secret.png)
4. Grant the service account its permissions:
   1. On the **Service accounts roles** tab, click **Assign role**.

      
      ![Cloud Voice, Assign role button on the service accounts roles tab](/images/pbx/assign-role.png)
   2. In the top-left corner, choose **Filter by clients** from the drop-down.

      
      ![Cloud Voice, filtering assignable roles by client](/images/pbx/filter-by-clients.png)
   3. Find and select each of these roles:

      
      ![Cloud Voice, the five service-account roles being assigned](/images/pbx/assign-permission.png)

      - query-groups
      - query-users
      - view-groups
      - view-users
      - manage-realm
   4. Click **Assign**.

### Export the realm metadata

1. In the left navigation bar, click **Realm settings**.
2. Scroll to the bottom and click **SAML 2.0 Identity Provider Metadata**.

   ![SAML 2.0 Identity Provider Metadata link in realm settings](/images/pbx/realm-endpoint.png)
3. Capture the metadata one of two ways:
   - Copy the metadata URL from your browser's address bar, or
   - Save the metadata XML file to your computer.

## Step 2: Import the metadata and configure Cloud Voice

1. Open the Red Hat SSO integration page in Cloud Voice.

   
   ![Cloud Voice, Red Hat SSO card on the collaboration integrations page](/images/pbx/red-hat-integration.png)

   1. Sign in to the Cloud Voice web portal and go to **Integrations > Collaboration**.
   2. Next to **Red Hat SSO**, click **Integrate**.
2. Bring in the Red Hat SSO configuration using either the metadata file or the metadata URL. Either method parses the key details and fills them in automatically.

   **From a metadata file**

   ![Importing configuration from a metadata XML file](/images/pbx/import-metadata-file.png)

   1. In the **Quickly Import Red Hat Configuration** section, choose **Import From Metadata File**.
   2. Click **Import**.
   3. Click **Browse** and pick the `.xml` file.

      :::note
      The file must be 4 MB or smaller.
      :::
   4. Click **Upload**.

   **From a metadata URL**

   
   ![Cloud Voice, importing configuration from a metadata URL](/images/pbx/metadata-url.png)

   1. In the **Quickly Import Red Hat Configuration** section, choose **Import From Metadata URL**.
   2. Enter the metadata URL in the **URL** field.
   3. Click **Import**.
3. Review and finish the fields in the **General** section.

   
   ![Cloud Voice, General settings for the Red Hat SSO integration](/images/pbx/general-setting.png)

   | Setting | Description |
   | --- | --- |
   | Identity Provider Entity ID | The unique identifier for Red Hat SSO. Parsed from the metadata and filled in automatically. |
   | Single Sign-on URL | The endpoint of Red Hat's SAML SSO service where Cloud Voice sends authentication requests. Parsed from the metadata and filled in automatically. |
   | Request Signature Method | The hashing algorithm used to sign SAML requests. |
   | SAML Bindings | The mechanism for exchanging SAML messages between Cloud Voice and Red Hat SSO. Only **Redirect** binding is supported today: when a Red Hat user signs in to the Cloud Voice App, Cloud Voice sends base64- and URL-encoded SAML messages as URL parameters. |
   | Connection Protocol | The protocol used to exchange authentication and authorization data with Red Hat SSO. |
   | Sign SAML Request | Whether to sign SAML requests and responses. |
   | Support Encrypted SAML Assertion | Whether to encrypt SAML assertions. |
4. In the **Attribute Mapping** section, choose the attribute that identifies Red Hat users for SSO. This must match the choice you made when adding users.
   - For the built-in **Email** field, select **SAML_SUBJECT** and confirm every user has an email address in Red Hat SSO.

     ![Selecting SAML_SUBJECT for built-in email mapping](/images/pbx/builtin-email-attribute.png)
   - For a custom email attribute, select **Custom** and configure the same attribute in both Cloud Voice and the Red Hat SSO user settings.

     ![Configuring a custom email attribute for mapping](/images/pbx/custom-email-attribute.png)
5. **Optional:** In the **Certificate Management** section, add or manage certificates.

   
   ![Cloud Voice, Certificate Management section of the integration](/images/pbx/certificate.png)

   :::note
   - Certificates found in the imported metadata are uploaded and listed here automatically.
   - Certificates you upload by hand must be:
     - **Format:** `.pem`, `.crt`, `.cer`, or `.cert`
     - **Size:** 4 MB or smaller
   - Up to **5** certificates are supported. Cloud Voice tries them in listed order, moving to the next only when one fails.
   :::
6. In the **App Registration** section, pick the URL that users will use to sign in to the Cloud Voice App with their Red Hat credentials.

   
   ![Cloud Voice, App Registration sign-in URL selection](/images/pbx/app-registration-pce.png)
7. In the **User Synchronization** section, paste the Client ID and Client Secret from the OIDC client you created earlier.

   
   ![Cloud Voice, User Synchronization fields for the OIDC credentials](/images/pbx/user-sync.png)
8. Click **Save**.
9. In the pop-up, click **Service Provider Metadata File** to download the metadata you will need to register Cloud Voice as a SAML client in Red Hat SSO.

   ![Downloading the service provider metadata file](/images/pbx/sp-metadata.png)

## Step 3: Register Cloud Voice as a SAML client in Red Hat SSO

1. In the left navigation bar, click **Clients**.
2. On the **Clients list** tab, click **Import client**.

   ![Import client button on the clients list](/images/pbx/import-client.png)
3. In the **Resource file** section, click **Browse** and upload the service provider metadata file you downloaded from Cloud Voice.

   ![Browsing for the Cloud Voice metadata file to import](/images/pbx/browse-saml-client.png)
4. Click **Save**.
5. Set the user attribute for the SAML client:
   1. On the **Client scopes** tab, open the client's dedicated scope and mappers.

      
      ![Cloud Voice, dedicated client scope on the Client scopes tab](/images/pbx/saml-pce.png)
   2. On the **Mappers** tab, open the email attribute (built-in or custom).

      ![Opening the email mapper on the Mappers tab](/images/pbx/email-attribute.png)
   3. Enter the attribute in the **User Attribute** field.

      ![Setting the User Attribute value for the email mapper](/images/pbx/email-user-attribute.png)
   4. Click **Save**.

## Result

The integration status shows **Connected**, confirming that Cloud Voice is linked to Red Hat SSO.

![Cloud Voice, integration status showing Connected](/images/pbx/integration-success.png)

## What to do next

- [Synchronize Red Hat SSO users to Cloud Voice and assign extensions](/pbx/integrations/red-hat/synchronize-users-from-red-hat-sso-to-cloud-voice/) so they can use their office extensions.
- [Enable Red Hat SSO](/pbx/integrations/red-hat/allow-users-to-log-in-to-cloud-voice-app-uc-clients-with-red-hat-sso/) so users can sign in to the Cloud Voice App with their Red Hat credentials.