Single Sign On (SSO) - SAML2 Setup Guide

Modified on Tue, 23 Apr 2024 at 06:27 PM

Projectal includes built-in Single Sign-On (SSO) features to let your users log into Projectal and their other applications via a single email address or identity.

SSO enables users of Projectal to securely log in and authenticate using your company's preferred Identity Provider (IdP). This saves the user from remembering multiple usernames and passwords, while still providing strong authentication for your company.

For your IT department, SSO is useful because all applications and accounts can be managed in one central secure location.

Projectal supports all popular SAML2-based Identity Providers (IdP) such as Google, Microsoft Azure, Okta and OneLogin.

When SSO has been enabled, an additional button for each SSO provider is displayed on Projectal's login screen.

Configuring SSO / SAML2

Tip: These configuration steps only apply for on-premises installations of Projectal.  If your Projectal is hosted and managed by JanusKS, then contact the Projectal Support team and they will configure your SSO / SAML2 providers for you.

To configure SSO / SAML2 for your Projectal installation, you need to edit the Projectal properties file that is located on each Projectal API server.

On each API server where Projectal is installed, go the /data/projectal folder.
Edit the application.properties file using a text editor such as nano.
After making changes to the application.properties file, save your changes and then restart the API server using the following command:

sudo systemctl restart projectal-web-api

Sample SSO/SAML2 section in Projectal properties file

# Login methods
saml.enabled=true
login.saml2.okta=name:Okta,icon:okta.svg,assertingPartyUri:https://123456.okta.com/app/abcdefg/sso/saml/metadata login.saml2.onelogin=name:OneLogin,icon:onelogin.png,assertingPartyUri:https://app.onelogin.com/saml/metadata/57ac3726-ddc5-4cf3-5345-c9dd8fc3e38e,logoutBinding:REDIRECT

Important: User accounts must already have been created and activated in Projectal for the users that wish to use your company's SAML2 IdP for SSO authentication.

Important: The user name identifier entered by users into your company's SAML2 IdP when logging into Projectal using SSO authentication must be an email address, and must match the same email address for the user account already created and activated in Projectal.

saml.enabled

Set this value to true to turn SSO / SAML2 authentication on.

Set this value to false to turn SSO / SAML2 authentication off.

login.saml2.{identifier}

This is a unique identifier for the SSO / SAML2 provider that you wish to include in Projectal. This identifier is required.

Examples:

name:

This is the display name for the SSO / SAML2 provider that you wish to include in Projectal. The name will appear alongside the icon on the button on the Projectal login screen. This name is required.

Examples:

Google
Okta
OneLogin
Azure

icon:

This is the display icon for the SSO / SAML2 provider that you wish to include in Projectal. The icon will appear alongside the name on the button on the Projectal login screen. This icon is required. Supported image formats are jpeg, png, gif and svg.

Examples:

google.png
okta_logo.jpg
onelogin.svg
azure.png

All icons should be placed into the file_storage root folder. See the property file.upload.dir to location the folder for storing icons.

assertingPartyUri:

This is the URL of the SSO / SAML2 provider that Projectal will contact to allow users to authenticate themselves using the SSO / SAML2 provider. This URL is required.

Examples:

https://123456.okta.com/app/abcdefg/sso/saml/metadata
https://app.onelogin.com/saml/metadata/57ac3726-ddc5-4cf3-5345-c9dd8fc3e38e
file:///data/file_storage/projectal_okta.xml

Tip: The URL can point to an XML file located on your Projectal API servers or in a common file storage area using the file:/// protocol.

logoutIgnoreIdp:

This setting allows you to skip logging out of the SSO / SAML2 provider. This should be set to true for SSO / SAML2 providers that do not support logging out. The default value is false. This setting is optional.

logoutBinding:

This is the communication method for logging out of the SSO / SAML2 provider. The values can be either be POST, REDIRECT or SOAP. The default value is POST. This setting is optional.

Okta Configuration Instructions

If your company is using Okta as your preferred Identity Provider (IdP), then follow these additional instructions to configure Okta to operate correctly with your Projectal.

Single Sign On URL should be set in your Okta configuration. The value entered should be:

https://<projectal_server>/saml2/sso/okta

where <projectal_server> is your Projectal server's URL.

Audience URI (SP Entity ID) should be set in your Okta configuration. The value entered should be:

https://<projectal_server>/saml2/service-provider-metadata/okta

where <projectal_server> is your Projectal server's URL.

Name ID Format should be set to Email Address.

Application username should be set to Email.

Single Logout needs to be enabled in your Okta configuration. This can be enabled in your Okta configuration by viewing SAML Settings and clicking Show Advanced Settings. Upload the Projectal Signature Certificate by clicking the Browse button. Once uploaded, then the Single Logout checkbox will be enabled. Select the Single Logout checkbox.

After selecting the Single Logout checkbox, then set the URLs for both Single Logout and SP Issuer.

Single Logout URL:

https://<projectal_server>/saml2/slo

where <projectal_server> is your Projectal server's URL.

SP Issuer:

https://<projectal_server>/saml2/service-provider-metadata/okta

where <projectal_server> is your Projectal server's URL.

Tip: You can obtain the Projectal Signature Certificate using your web browser.  In your web browser, go to your Projectal's login page.  On your web browser's address bar, click the Lock icon to view site information.  Click the "Connection is secure" and click "Certificate is valid".  This will display the Certificate Viewer dialog.  Click the Details tab and click Export to create a .CRT file containing the Projectal Signature Certificate. Note: Your Projectal Signature Certificate will begin with -----BEGIN CERTIFICATE---- and end with -----END CERTIFICATE-----.