Setting up SAML SSO integration with Keycloak

General information

Keycloak is an open-source authentication system that allows controlling user access to applications and data, providing a single sign-on (SSO) entry point.

SSO (Single Sign-On) is the technology used in Keycloak that allows users to authenticate in multiple applications with a single set of credentials.

Realm is an area for clients (applications) where user, application, role, and group management is configured. Each Realm has its own set of security policies, configurations, and authentication mechanisms.

Clients are applications and services that use Keycloak for user authentication and authorization.

Attributes are data from the user profile. Access to attributes and their management is performed through special operations. By default, attributes such as first name, last name, and email address are available for each user in Keycloak.

Mappers allow including user data (email, roles, groups they belong to) in the SAML attributes issued to clients during authentication.

Requirements

To set up Pyrus integration with Keycloak using SAML technology, you will need to:

• install the Keycloak solution - the recommended version is 26 and above; technically, version 17 and above SAML technology is supported in Keycloak;
• create an organization in Pyrus.

Setting up the integration in Pyrus

1. Log in to Pyrus.

2. Click the gear icon in the lower left corner of the screen to access general settings.

   

3. In the SAML Settings block, click Configure.

   

4. Fill in the SAML settings:

• URL IdP: https://{KEYCLOAK_DOMAIN_NAME}/realms/{REALM_NAME}/protocol/saml

• The provider certificate can be obtained via the link: : https://{KEY CLOAK_DOMAIN_NAME}/realms/{REALM_NAME}/protocol/saml/descriptor inside the <ds:X509Certificate> tag. Before inserting it, it must be enclosed in a Pem block:

-----BEGIN CERTIFICATE-----

Certificate

-----END CERTIFICATE-----

Setting up the integration in Keycloak

Creating a client

1. Create a Client:

   • get the client configuration from a link of the form: https://pyrus.com/auth/saml/metadata/{ORG_ID}
   • import the client from the configuration obtained.

   

2. In the client settings, in the SAML capabilities section, set the value of the Name ID format field to email.

Setting up data exchange between Pyrus and Keycloak

To automatically load user data (first name, last name, phone) into Pyrus from the Keycloak service, you need to configure the information exchange between Pyrus and user attributes in Keycloak. Follow these steps:

1. Create a client scope — Client Scope.

   

2. In the Client Scope, create mappers of User Attribute type with the field SAML Attribute NameFormat set to URI Reference for the following attributes:

   • attribute firstName

     SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

     

   • attribute lastName

     SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

     

   • attribute phone

     SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone

     

   Tip: if the phone attribute is missing, it can be created. To do this, go to the Realm settings section, then to User profile.

3. Go to the Clients section, open the Client Name tab, and then Client Scopes. Add the Client scope you created earlier in Default status.

   

Restrictions

• For a user to log into Pyrus via SAML protocol, they must be added to your organization.

  How to add a user to the organization

• The Pyrus Sync application does not support user synchronization from the Keycloak service, but if Keycloak uses Active Directory as the identity provider (IdP), synchronization can be organized through it.