.png){kind=logo}
SSO/SAML Login
Within Valispace, we can log in with Single Sign-On(SSO) using Security Assertion Markup Language version 2(SAML v2). If you have a SAML v2 compatible Identity Provider (IdP), you can connect it to your Valispace instance, and users can log in with their existing accounts.
SSO Login
The SSO set-up for Valispace Application has specificities according to deployment’s type.
01. Server-side configuration:
After the SSO setting has been updated, it can be configured. These settings below don’t require an
application restart.
Step 1: On the deployment, navigate to: https://{your.valispace.deploy}/admin/constance/config/
AUTH_SSO_SP_ENTITY_ID
Replace the default http://127.0.0.1:8000/rest/auth/sso/metadata/ with the URL of the deployment e.g.: https://<url/rest/auth/sso/metadata/>AUTH_SSO_SP_ACS
Replace the URL with the actual one like https://<url/rest/auth/sso/acs/>AUTH_SSO_SP_SLS
Replace the URL with the actual one like https://<url/rest/auth/sso/sls/>AUTH_SSO_X509CERT
It can be left blank as an optional setting. In case the x509 certs are required, send a message to support@valispace.com requesting to enable this feature.The Valispace Support team will respond and assist you in achieving the proper configuration.AUTH_SSO_IDP_XML
IdP metadata XML that connects both. Will be explained further.AUTH_SSO_NAMEID_FORMAT
Different nameId formats are supported by the IdP’s. In the ‘Authentication SSO Attributes’ section of the configuration page, you have the option to define specific names that your Identity Provider (IdP) uses for various fields. Below, we provide an example of how you might name these properties:AUTH_SSO_EMAIL_ATTRIBUTE mail
AUTH_SSO_USERNAME_ATTRIBUTE uid
AUTH_SSO_FIRST_NAME_ATTRIBUTE givenName
AUTH_SSO_LAST_NAME_ATTRIBUTE sn
Note: These names should be documented by your IdP, but if you encounter 500 errors after configuring both the IdP and SP, a helpful tool to use is SAML-tracer. It is an add-on for Chrome or Firefox that displays the information and field names that your IdP sends to Valispace to map them correctly.
Note for Azure Configuration: Valispace only attempts to locate the AUTH_SSO_*_ATTRIBUTE fields within the attributes section of the SAML response. If you decide to set both the email and username as the ‘nameId’ (email), it’s necessary also to designate it under the ‘emailAddress’ property.
When Azure is configured to transmit the ‘nameId’ in the ‘emailAddress’ format, it’s not dispatched as an attribute. Azure’s Claim feature has an attribute known as ‘namespace’. This ‘namespace’ should either be left empty (it’s not empty by default) or matched within Valispace’s admin settings.
For instance, in the case of Microsoft Azure, the ‘namespace’ in the claims should be left empty. Alternatively, it should correspond to the same attribute in the Valispace admin settings.
Initially, if feasible, set your NameIDPolicy Element in the AuthnRequest of Azure to ‘persistent’. After completing this step, adjust the corresponding Valispace setting (AUTH_SSO_NAMEID_FORMAT) to align with this change.
This ensures that each user receives a unique token that establishes a link between Azure and Valispace. This method takes precedence over modifications to email addresses.
Next, consider revising the following settings in Valispace to match the configuration below:
AUTH_SSO_EMAIL_ATTRIBUTE: Set this to ‘emailaddress’
AUTH_SSO_USERNAME_ATTRIBUTE: Set this to ‘emailaddress’
These settings are based on the assumption that the email address is intended to serve as the ‘username’.
02. IdP Setup & Validation:
This is entirely dependent on the specific IdP used in the setup. This document provides some of the most common documentation links for specific IdP’s, as follow:
Azure AD SAML Azure/active-directory-setup-sso
Auth0 Auth0 configure-auth0-saml-identity-provider
Keycloak https://www.keycloak.org/docs/latest/server_admin/#_saml
When adding a new application/configuration in your IdP it will normally ask for the following information about the application you want to add:
ENTITY_ID
https://<url/rest/auth/sso/metadata/>
ACS (Assertion Consumer Service)
https://<url/rest/auth/sso/acs/>
SLS (Single Logout Service)
https://<url/rest/auth/sso/sls/>
It can also allow for configuring which User Fields are sent to the configured application and its names, which then can be added in the Authentication SSO Attributes section of the admin configuration, as stated in the previous section.
Now that the IdP is configured, we need to link our SP to the IdP. For that we need to get an XML formatted file that contains the IdP connection information. This varies from one IdP to another, but there are two ways this can be obtained.
Directly available as XML from the IdP
The IdP shows the connection information but not in XML format. In this case, it is suggested that you go to https://www.samltool.com/idp_metadata.php, which will auto-build the metadata with the provided information.
After having the XML file, copy all of its content and paste it into the field: AUTH_SSO_IDP_XML which was introduced in the previous steps.
A SSO Login button at Valispace’s login page should be shown, after each completed step, to redirect to the newest configured IdP login screen and allow for logging in.
Note: In case your Organization still has registered users inside Valispace Application, they will be validated against the values at the email field in the IdP to be automatically linked, when matched.
The SSO Configuration for Valispace is done.
SSO Login only
Once Single Sign-On (SSO) is enabled, users can log in to the deployment using either SSO or their username and password. If you wish to restrict users from logging in using their username and password, you can do so by toggling a "Flag" within the admin panel. This flag hides the "Username and Password" option on the login page. To activate this feature, the admin must log in to the admin panel, navigate to "Constants," and then to "Config." From there, the admin can uncheck the option "AUTH_USERNAME_PASSWORD.”
Watch this demo to learn how to do it quickly and easily.