search string side menu

ELMA365 Store solutions > SAML integration  / SAML integration with Keycloak

SAML integration with Keycloak

SAML integration lets you utilize Keycloak for authentication and automatic creation of internal and external users in ELMA365.

When someone authenticates in ELMA365, a new internal user gets created, and their record is added to the Users directory. If the user logs in on the portal, the record appears in the built-in External users directory.

Note that for an unregistered user to access the portal via SAML, you don’t need to send them a personal invite link. Simply provide them the portal page link.

Before you start the integration setup, install Keycloak according to its official documentation.

For everything to work smoothly, you’ll need an encrypted connection with tls certificates on both Keycloak and ELMA365 servers.

Initial setup of the SAML application in Keycloak

  1. Access Keycloak settings at http://my_domain.com:8443, where:
  • my_domain.com. Your site’s address.
  • :8443. Keycloak’s standard port for encrypted connections. Feel free to change it when setting up your configuration.
  1. Go to the Administration Console. To confirm the action, enter the login and password for your account.
  2. On the page that opens, create a new environment. Enter the environment name and click the Create button.
  3. From the left menu, go to the Realm setting section. On the General tab, copy the link to Keycloak metadata for SAML integration from the Endpoints field.

Set up SAML integration in ELMA365

  1. Go to Administration > Modules > SAML.
  2. Enable the module option and click Add Item.
  3. In the opened provider settings window, fill in the fields:
  • Name*. The title for the integration.
  • IdP metadata URL*. The metadata URL of your Keycloak server, which you acquired during the initial setup of the SAML app in Keycloak in step 4.
  • Public key*. The string representation of your public key in .pem format:

-----BEGIN CERTIFICATE-----
…
-----END CERTIFICATE-----

  • Private key*. The string representation of your private key in .pem format:

-----BEGIN PRIVATE KEY-----
…
-----END PRIVATE KEY-----

To generate the public and private keys, use the following command in openssl:

openssl req -x509 -newkey rsa:2048 -keyout service.key -out service.cert -days 365 -nodes -subj "/CN=mydomain.pro"

mydomain.pro here is your Keycloak domain name.

For subsequent integration setup, you’ll need to import the public key in PKCS12 format. To export it, use the following command:

openssl pkcs12 -export -out cert.p12 -in service.cert -inkey service.key -name learn 

  • Create users during authentication. Set this option to Yes to have missing external or internal users created automatically when a user attempts to authenticate in the system.
  • Update existing users. Set this option to Yes if you need to update existing users during authentication. Upon updating, the user will be converted to an external SAML user, and they will lose the ability to authenticate the old way.
  • Use for users. Specify who can authenticate via SAML: external portal users or internal ELMA365 users.
  1. Click Save. After that, a metadata file link will be generated and displayed in the Metadata URL field.
  2. Follow the provided link and save the Service Provider’s metadata file in the .xml format. It will be required for the final setup of the SAML app on Keycloak’s side.

Final setup of the SAML application in Keycloak

  1. Return to the Keycloak setup interface and import the client using the metadata file obtained from the SAML integration setup in ELMA365 at step 5. For this, from the left menu, go to the Clients section and click the Import client button. On the page that appears, upload the metadata file using the Browse button. After saving, the app setup window will open.
  2. Go to the Keys tab and use the Import Key button to import the cert.p12 key storage, created during the SAML integration setup in ELMA365 at step 3. Specify the archive format (in our case, it’s PKCS12), the label indicated after the -name directive when exporting the key, and the storage password.
  3. For the integration to work correctly on the Keycloak side, it's necessary to create two mandatory SAML parameters: windowsaccountname and externalCode. From the left menu, go to the Clients section and select the created app. Then, open the Client scopes tab and select the created app again.
  4. On the page that appears, under the Mappers tab, click the Add predefined mapper button. From the list that appears, select role_list.
  5. In the Mappers tab, click the Add mapper button. From the list, choose By configuration. In the window that appears, select User attributes.
  6. Create two parameters with the following data:

This parameter is mandatory. The attribute will be matched with the user’s login in ELMA365.

This parameter is mandatory. It’s used to identify external users in ELMA365.

  1. As Keycloak will act as an identity provider, it’s necessary to create a new user. From the left menu, go to the Users section and create a user. Then, open the Credentials tab and set a password for them.
  2. In the Attributes tab, specify values for the following attributes:
    • externalCode. User ID, same as objectGUID in ActiveDirectory.
    • windowsaccountname. User login from the ELMA365 interface.

Also, provide the user’s email and name.

  1. Click Save.
saml-with-azure.html audit_service.html

Found a typo? Highlight the text, press ctrl + enter and notify us