Skip to main content
Version: 7.0

SSO configuration with Keycloak

danger

Before configuring SSO, make sure that the APP_URL parameter in config.env matches the current Passwork domain, for example — APP_URL=https://passwork.example.com

This is necessary so that the IDP can download the metadata. Also, the Passwork server must operate over the HTTPS protocol.

The following server names are used as examples:

  • Provider (IDP) — keycloack.passwork.local
  • Passwork Server (SP) — passwork.example.com

Creating an application by importing a file into Keycloak

Obtain and edit the file to create an application on the IDP side.

keycloack.json

Your browser does not support JSON viewing

Open in a new tab

"clientId": "https://your_host/api/v1/sso/metadata",
"adminUrl": "https://your_host/api/v1/sso/acs",
"baseUrl": "https://your_host/*",
"saml.logout.url": "https://your_host/api/v1/sso/sls"

Open the Keycloak web interface and go to — ClientsImport client:

Import .json file to create an application in Keycloak

Perform the following actions:

  • Import the modified application file;
  • Set the name of the application being created;
  • Disable — Encrypt assertions;
  • Disable — Client signature required.

Save the changes made:

Select file and edit imported .json

If necessary, you can change the unique user identifier (NameID) inside the SAML assertion after saving the previous steps:

Example of changing NameID in SAML assertion
danger

We recommend specifying username or email, depending on the chosen value the user's login in Passwork may have the following formats:

Configuring user role transmission in SAML assertion

Go and create a common settings set for the application (SP) — Client scopesCreate client scope:

Create a settings template for the application

Perform the following actions:

  • Set the name;
  • Type — Default;
  • Protocol — SAML.
Edit parameters of the created template

Open the Mappers tab and create attribute assertions to transmit additional user attributes from Keycloak (IDP) to Passwork (SP):

  • Adding an assertion to transmit email:
    • Add predefined mapperX500 email;
    • Open the added assertion from the template and change:
      • SAML Attribute Name — email;
      • SAML Attribute NameFormat — Basic.
  • Adding an assertion to transmit firstName:
    • Add mapperFrom predefined mappersX500 surname;
    • Open the added assertion from the template and change:
      • Property — firstName;
      • SAML Attribute Name — firstName;
      • SAML Attribute NameFormat — Basic.
Add user attributes to be sent in the template

Assign the created settings set (Client scope) to the created application (SP) — ClientsPasswork → go to the Client scopes tab → Add client scope:

Add the template to the Passwork application

Select the created set passwork_client_scope from the list with Assigned type — Default:

Select the created template and add it in Default mode

Delete the default added settings template — role_list:

Deleting the default template

Configuring and filling in Single Sign-On (SSO) parameters in Passwork

Filling in the "User Attributes" values

Log in to the Passwork web interface, go to — Settings and UsersSSO Settings and fill in the mapping attributes:

  • Email attribute — email;
  • Full name attribute — firstName.

Filling in the "Identity Provider → Passwork" values

Open the service provider configuration (IDP) — Realm settingsGeneralEndpoints:

Go to location to open Keycloak metadata

Copy the following parameter values:

entityID="https://keycloack.passwork.local/realms/master"
<md:SingleLogoutService Location="https://keycloack.passwork.local/realms/master/protocol/saml"/>
<md:SingleSignOnService Location="https://keycloack.passwork.local/realms/master/protocol/saml"/>
Example of xml output
Example of xml output

Open — Settings and UsersSSO Settings and fill in the values:

Filling in the "Certificate" value

Open and copy the generated SSL certificate in base64 format — Realm settingsKeysCertificate:

Get the public SSL certificate of Keycloak in base64

Paste the copied SSL certificate into the corresponding field — Settings and UsersSSO Settings.

Open the login window in the Passwork web interface and log in via SSO to verify correct configuration:

Authenticate in Passwork using SSO

Possible errors

info

If errors occur, they will be located in the PHP log file

The SSO response cannot be correctly decrypted because the certificate fingerprint was copied incorrectly or it is the fingerprint of the wrong certificate:

OneLogin_Saml2_Error: invalid_response LastErrorReason: Signature validation failed. SAML Response rejected in /var/www/app/modules/Admin/SSO/SsoController.php:78\nStack trace:\n#0 [internal function]: Passwork\\Modules\\Admin\\SSO\\SsoController->acsAction()\n#1 [internal function]: Phalcon\\Dispatcher\\AbstractDispatcher->callActionMethod()\n#2 [internal function]:Phalcon\\Dispatcher\\AbstractDispatcher->dispatch()\n#3 /var/www/public/index.php(91): Phalcon\\Mvc\\Application->handle()\n#4 {main}

The current host value in the APP_URL parameter of the config.env file is incorrect:

OneLogin_Saml2_Error: Invalid array settings: sp_acs_url_invalid, sp_sls_url_invalid in /var/www/app/vendors/php-saml/lib/Saml2/Settings.php:122\nStack trace:\n#0 /var/www/app/vendors/php-saml/lib/Saml2/Auth.php(152): OneLogin_Saml2_Settings->__construct()\n#1 /var/www/app/modules/Admin/SSO/SsoService.php(53): OneLogin_Saml2_Auth->__construct()\n#2 /var/www/app/modules/Admin/SSO/SsoController.php(33): Passwork\\Modules\\Admin\\SSO\\SsoService->getAuth()\n#3 [internal function]: Passwork\\Modules\\Admin\\SSO\\SsoController->loginAction()\n#4 [internal function]: Phalcon\\Dispatcher\\AbstractDispatcher->callActionMethod()\n#5 [internal function]: Phalcon\\Dispatcher\\AbstractDispatcher->dispatch()\n#6 /var/www/public/index.php(91): Phalcon\\Mvc\\Application->handle()\n#7 {main}, referer: 

The user lacks the attribute used for login:

OneLogin_Saml2_Error: invalid_response LastErrorReason: The status code of the Response was not Success,was Responder -> urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy in /var/www/app/modules/Admin/SSO/SsoController.php:78\nStack trace:\n#0 [internal function]:Passwork\\Modules\\Admin\\SSO\\SsoController->acsAction()\n#1 [internal function]: Phalcon\\Dispatcher\\AbstractDispatcher->callActionMethod()\n#2 [internal function]:Phalcon\\Dispatcher\\AbstractDispatcher->dispatch()\n#3 /var/www/public/index.php(91): Phalcon\\Mvc\\Application->handle()\n#4 {main}