Configuring SSO with Keycloak
Before configuring SSO, make sure that in config.env the APP_URL parameter matches the current Passwork domain, example — APP_URL=https://passwork.example.com
This is needed so that IDP can download the metadata. Also, the Passwork server must be running the HTTPS protocol.
The following server names are used for the example:
- Provider (IDP) — keycloack.passwork.local
- Passwork Server (SP) — passwork.example.com
Get and edit a file to create an IDP-side application.
Open the Keycloack web interface and go to — Clients → Import client:
Perform the following actions:
- Import the modified application file;
- Set the name of the application to be created;
- Disable — Encrypt assertions;
- Disable — Client signature required.
Save the changes made:
If necessary, you can change the unique user identifier (NameID) inside the SAML-assertion after saving the previous actions:
It is recommended to specify username or email, depending on the selected value the user login in Passwork can have the following formats:
- username
Navigate to and create a common set of settings for the application (SP) — Client scopes → Create client scope:
Perform the following steps:
- Set Name;
- Type — Default;
- Protocol — SAML.
Open the Mappers tab and create an attribute statement to transfer additional user attributes from Keycloak (IDP) to Passwork (SP):
- Adding an assertion for email transmission:
- Add predefined mapper → X500 email;
- Open the added statement from the template and modify:
- SAML Attribute Name — email;
- SAML Attribute NameFormat — Basic.
- Adding an assertion to pass firstName:
- Add mapper → From predefined mappers → X500 surname;
- Open the added statement from the template and modify:
- Property — firstName;
- SAML Attribute Name — firstName;
- SAML Attribute NameFormat — Basic.
Assign the created scopes set (Client scope) to the created application (SP) — Clients → Passwork → go to the Client scopes tab → Add client scope:
Select from the list the created passwork_client_scope set with Assigned type — Default:
Authenticate in the Passwork web interface, go to — Settings and Users → SSO Settings and fill in the mapping attributes:
- Attribute for email — email;
- Attribute for full name — firstName;
Open the service provider (IDP) configuration — Realm settings → General → Endpoints:
Copy the following parameter values:
Open — Settings and Users → SSO Settings and fill in the values:
- Identifier (Entity ID) — https://keycloack.passwork.local/realms/master
- Reply URL — https://keycloack.passwork.local/realms/master/protocol/saml
- Logout URL — https://keycloack.passwork.local/realms/master/protocol/saml
Open and copy the generated SSL certificate in base64 format — Realm settings → Keys → Certificate:
Place the copied SSL certificate in the appropriate field — Settings and users → SSO settings.
Open the authentication window in the Passwork web interface and log in via SSO to verify the correct configuration:
In case of errors, they will be recorded in the PHP log
The response from SSO cannot be correctly decrypted because the certificate fingerprint has been copied incorrectly or is the fingerprint of an incorrect certificate.
The current host value in the config.env parameter APP_URL is specified incorrectly.
The user lacks the attribute required for authentication.
