Integrate Yeastar P-Series Software Edition with Red Hat SSO

This topic describes how to integrate Yeastar P-Series Software Edition with Red Hat SSO.

Note: This topic takes Keycloak 20.0.5 as an example to demonstrate how to implement the integration. The configuration paths may differ from Red Hat SSO, but the required settings are the same.

Requirements

Platform Requirement
Red Hat SSO Recommended version: 7.6 or later
Yeastar PBX
  • Firmware: Version 83.21.0.16 or later
  • Plan: Enterprise Plan or Ultimate Plan

Step 1. Create resources and obtain credentials from Red Hat SSO

Create the necessary resources and obtain the required credentials from Red Hat SSO, so as to authenticate and authorize interactions between Yeastar PBX and Red Hat SSO.

You need to perform the following operations in the Red Hat SSO portal.

  1. Create a realm and configure realm key(s) for centralized management and authentication of user identities and SSO.
  2. Add users who need to sign in to Linkus clients with their Red Hat credentials.
  3. Create an OpenID Connect(OIDC) Client to enable user synchronization to Yeastar PBX.
  4. Obtain metadata from Red Hat SSO for subsequent import into Yeastar PBX.
1. Create a realm and configure realm key(s)
  1. Log in to the Red Hat SSO admin console using the administrator account.
  2. Create a realm.
    1. On the top of the left pane, click master, then select Create Realm.

    2. In the Realm name field, enter a name, then click Create.

      The current realm is now set to the realm you just created.

  3. Configure realm keys for cryptographic signatures and encryption.
    1. On the left navigation bar, click Realm settings.
    2. Under Keys tab, click Providers.
    3. Click Add provider, then select rsa-generated provider to generate a key pair with a self-signed certificate.

      Note: Yeastar PBX supports a maximum of 5 certificates. Metadata with more than 5 certificates can NOT be imported into Yeastar PBX.
2. Add users
  1. On the left navigation bar, click Users.
  2. Under the User list tab, click Create new user.

  3. Enter the details for the new user.
    Important: Since user's email address is used as the unique identifier to determine user's eligibility for Red Hat SSO, make sure the email address is properly configured.
    • If you use the built-in Email field as the unique identifier for SSO, enter the user's email address in the Email field.

    • If you use a custom email-related attribute as the unique identifier for SSO, add the attribute and specify the key and value.

  4. Click Save.
3. Create an OpenID Connect(OIDC) Client
  1. On the left navigation bar, click Clients.
  2. Create an OIDC Client.
    1. Under Clients list tab, click Create client.

    2. Set the client, then click Save.

      Item Description
      Client type Select OpenID Connect.
      Client ID Enter a name to help you identify the client.
      Client authentication Enable this option.
      Authentication flow Select the checkbox of Service accounts roles to authorize the client to obtain an access token.
  3. Check and note down client credentials.
    • Client ID: Under Settings tab, copy the client ID.

    • Client Secret: Under Credentials tab, copy the client secret.

  4. Assign permissions to the service account.
    1. Under Service accounts roles tab, click Assign role.

    2. On the top-left corner, select Filter by clients from the drop-down list.

    3. Search for and assign the following permissions.
      Illustration Permission

      • query-groups

      • query-users

      • view-groups

      • view-users

      • manage-realm
    4. Click Assign.
4. Obtain metadata from Red Hat SSO
  1. On the left navigation bar, click Realm settings.
  2. Scroll down to the bottom, click SAML 2.0 Identity Provider Metadata.

  3. Obtain metadata in either of the following ways:
    • Copy the metadata URL from the browser's address bar
    • Save the metadata XML file to your computer

Step 2. Import Red Hat SSO metadata and configure settings on Yeastar PBX

  1. Access the configuration page of Red Hat SSO.

    1. Log in to PBX web portal, go to Integrations > Collaboration.
    2. On the right of Red Hat SSO, click Integrate.
  2. Import Red Hat SSO configurations via metadata XML file or metadata URL.
    Import from metadata XML file
    1. In the Quickly Import Red Hat Configuration section, select Import From Metadata File.
    2. Click Import.
    3. Click Browse and select the .xml file.
      Note: The file size must not exceed 4MB.
    4. Click Upload.

      The key metadata will be parsed from the file and automatically populated in Yeastar PBX.

    Import from metadata URL
    1. In the Quickly Import Red Hat Configuration section, select Import From Metadata URL.
    2. In the URL field, enter the metadata URL.
    3. Click Import.

      The key metadata will be parsed from the file and automatically populated in Yeastar PBX.

  3. In the General section, check and complete the following settings.

    Item Description
    Identity Provider Entity ID The unique identifier for Red Hat SSO. This value is parsed from the metadata and automatically populated.
    Single Sign-on URL The URL of the Red Hat's SAML SSO service, where Yeastar PBX will send SAML authentication requests. This value is parsed from the metadata and automatically populated.
    Request Signature Method Select the hashing algorithm used to sign SAML requests.
    SAML Bindings

    Select the binding mechanism for SAML message exchange between Yeastar PBX and Red Hat SSO.

    Currently, only Redirect binding is supported. When a Red Hat user attempts to sign in to Linkus clients, PBX sends base64-encoded and URL-encoded SAML messages as URL parameters to Red Hat SSO.
    Connection Protocol Specify the protocol used to exchange authentication and authorization data between Yeastar PBX and Red Hat SSO.
    Sign SAML Request

    Specify whether to sign SAML requests and responses.
    Support Encrypted SAML Assertion Specify whether to encrypt SAML assertions.

  4. In the Attribute Mapping section, specify the attribute that will be used to identify Red Hat users for SSO.

    • If you use the built-in Email field as the unique identifier for SSO, select SAML_SUBJECT, and ensure users' email addresses are configured in Red Hat SSO.

    • If you use a custom email-related attribute as the unique identifier for SSO, select Custom, and configure the custom attribute in PBX as well as in the Red Hat SSO user settings.

  5. Optional: In the Certificate Management section, add or manage certificates as needed.

    Note:
    • Certificates parsed from metadata will be automatically uploaded and displayed here.
    • If you manually upload certificates, the certificates must meet the following requirements:
      • Format: .pem, .crt, .cer, or .cert
      • File Size: No more than 4MB
    • Up to 5 certificates are supported. PBX will try the certificates in the order they are listed, using the next one only if the previous certificate fails.
  6. In the App Registration section, select the URL via which users can sign in to Linkus clients using their Red Hat credentials.

  7. In the User Synchronization section, paste the client ID and client secret of OIDC Client.

  8. Click Save.
  9. In the pop-up window, click Service Provider Metadata File to download the metadata file for SAML client configuration on Red Hat SSO.

Step 3. Create an SAML client on Red Hat SSO

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

  3. In the Resource file section, click Browse to upload the metadata file obtained from Yeastar PBX.

  4. Click Save.
  5. Set user attribute for the SAML Client.
    1. Under Client scopes tab, click the dedicated scope and mappers for the client.

    2. Under Mappers tab, click the email attribute or the custom email-related attribute.

    3. In the User Attribute field, enter the user attribute.

    4. Click Save.

Result

The status of the integration displays Connected, indicating that the PBX is successfully connected to Red Hat SSO.

What to do next