Single sign-on
Required Permission: Settings management (Read more about permissions in User Groups)
Table of Contents
Graphlytic supports Single sign-on integration with external Identity Providers (IdP) using the SAML2 protocol.
1. How it works
When the SAML2 integration is enabled the Login page includes an SSO login option (the title of the button is configurable).
After clicking on the "External SSO" option the user is redirected to the login page of the Identity Provider.
After successful login on the Identity Provider side and redirect back to the Graphlytic application the user is logged into the application with these possible scenarios:
The user already exists in Graphlytic: then the user is logged into the application and his user group mappings are updated according to the information received from IdP and mapping defined in the SAML2 integration configuration.
The user is not yet created in Graphlytic: then the user is created (if the licensed amount of users has been not reached yet) and his user group mappings are updated according to the information received from IdP and mapping defined in the SAML2 integration configuration. To correctly log in, a user has to be assigned to at least one User Group based on group (LDAP) mapping. If you want to make sure that the user can always log in, please fill out the "Fallback group", which will be assigned to users with no group during the identity provisioning process.
2. Configuration
2.1. Identity Provider connection configuration
To update SSO settings use the Single Sign-On panel on the Settings page.
Form element | Example value | Description |
|---|---|---|
Single Sign-On enabled | Switch for turning on/off the Single Sign-On functionality. | |
Login Label | Sign in with SSO | Title of the Login page button. If missing the Name of IdP will be used instead. |
Federation Metadata URL | https://idp-url.com/some-id/sso | Publicly accessible URL with the SAML2 federation document (XML) that can be used to automatically set up the SSO connection. |
Verifying certificate | -----BEGIN CERTIFICATE----- MIIDBTCCAe2gAwIBAgIQH4Fl... | IdP certificate for IdP signing verification. This certificate is used to verify that the response is correct and that it was sent from the contacted IdP. |
Decryption certificate | -----BEGIN CERTIFICATE----- MIIDBTCCAe2gAwIBAgIQH4FI... | IdP certificate for decryption. Can be empty for no encryption of communication with the IdP. If defined, this certificate is used to decrypt messages from IdP. |
IdP entity ID | active_directory_id | The IdP entity identifier (Asserting Party Entity Id). |
Graphlytic entity ID | graphlytic_idp_id | The local application (Graphlytic) ID for IdP communication. Has to be created in the IdP configuration. |
SSO Redirect URL | https://idp_url_for_login.com/sso | Login redirect URL. The user will be redirected to this location during the login workflow. |
Assertion Consumer URL | https://your.domain.com/login/saml2/sso/idpid | Assertion URL where the successfully logged-in user is redirected back from the IdP. If not defined a default value is used (this value is sent in the IdP request and some IdPs are automatically reading and using this value). |
Manage groups in IdP | If turned on then Graphlytic updates user groups based on IdP Assertion claim on every log-in. | |
Group claim | claims/role | The claim URI in the returned IdP Assertion with the user groups listing. |
Fallback group | read-only-group-name | Used only when "Manage groups in IdP" is turned on. Name of a Graphlytic user group that will be used if no mapping was successful. If the Fallback group is not configured or the group doesn't exist in Graphlytic then such user (with no valid user groups) is not created in Graphlytic (to minimize license consumption). |
Default group | read-only-group-name | Used only when "Manage groups in IdP" is turned off. It’s the name of a Graphlytic user group that will be assigned to every user created based on successful SSO log-in. |
First Name claim | claims/firstName | The claim URI in the returned IdP Assertion with the user’s first name. |
Last Name claim | claims/lastName | The claim URI in the returned IdP Assertion with the last name. |
Email claim | claims/email | The claim URI in the returned IdP Assertion with the user’s email address. |
2.2. Import integration metadata
When your IdP provides an XML federation file you can import the file into Graphlytic using the “Import metadata” button. Graphlytic then extracts as much information as possible and uses it to configure the SSO form. There’s still a possibility that this file does not include all the information and manual editing of the form values will be needed.
2.3. Export integration metadata
Graphlytic allows the export of a SAML2 federation metadata file that can be used to import metadata into your IdP. Click on the “Export metadata” button to export the file. Please note that the SSO configuration has to be turned on to export the file. If it’s turned off then please turn it on, save the change, and then you should be able to export the metadata file.
2.4. User groups mapping
Mapping of LDAP groups stored in the Identity Provider to Graphlytic groups is done in the User Groups management. Every Graphlytic user group can have assigned multiple LDAP groups that will be used to map them to the Graphlytic groups during the user's login process.
2.5. Default Configuration
The default configuration can be overridden in the graphlytic.conf file (application needs to be restarted after any change in this conf file).
More information can be found on the Configuration page.
3. Example configuration of Microsoft Entra ID (former Azure Active Directory)
Azure Entra ID can be used as an SSO provider with Graphlytic.
We assume the tenant, app registration, user, and group are successfully created using Microsoft manual.
Steps to configure Azure Entra ID connection
Find the Federation metadata document URL in Azure
Enter the Federation metadata URL into Graphlytic and click “Import”
Find the Graphlytic entity ID in Azure and enter it into Graphlytic
Check the Assertion Consumer URL
it should be a public URL pointing to your Graphlytic instance
it should be defined in Azure Entra ID app registration Redirect URIs
Configure claim mappings
Save the configuration in Graphlytic
See the table below for more information.
Form element | Example Value | Description |
|---|---|---|
Federation Metadata URL | https://login.microsoftonline.com/87654321-4321-4321-4321-3d7hh723f7/federationmetadata/2007-06/federationmetadata.xml | Publicly available XML document that contains most of the information needed to connect Graphlytic to Azure Entra ID. See chapter “3.1. Federation Metadata document URL” below for more information. |
Verifying Certificate | -----BEGIN CERTIFICATE----- MIIDBTCCAe2gAwIBAgIQH4FlYAM+UJlF0G3vy9ZrhTANBgkq………. | Depending on your infrastructure, there could be a need to set the certificate needed to verify the SAML assertion. The certificate is automatically loaded when the Federation metadata document is imported. The Federation metadata URL is also automatically used to reload the certificate when an auto-renewal of key happens on Azure’s side. |
Decryption certificate | Not needed for Azure Entra ID (if not specifically configured), leave empty. | |
IdP entity ID | https://sts.windows.net/87654321-4321-4321-4321-3d7hh723f7/ | Should be in the form of "https://sts.windows.net/{TENANT_ID}/" In our example {TENANT_ID} is 87654321-4321-4321-4321-3d7hh723f7 Please do not forget the slash “/” and the end of the IdP entity ID string This value is automatically loaded when the Federation metadata document is imported. |
Graphlytic entity ID | spn:12345678-1234-1234-1234-971777321736 | Should be in the form of "spn:{Application_ID}", in our example {Application_ID} = 12345678-1234-1234-1234-971777321736 See chapter "3.2. Graphlytic Application ID" for more information |
SSO Redirect URL | https://login.microsoftonline.com/87654321-4321-4321-4321-3d59c8323023/saml2 | SAML-P sign-on endpoint This value is automatically loaded when the Federation metadata document is imported. |
Assertion Consumer URL | https://my-domain.com/login/saml2/sso/idpid | The url must end with /login/saml2/sso/idpid This value is set in Azure Entra ID → App Registration → Redirect URIs |
Group Claim | http://schemas.microsoft.com/ws/2008/06/identity/claims/groups | For Azure Entra ID it’s usually one of these:
List of available claims is automatically loaded when the Federation metadata document is imported. |
First Name claim | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | The claim name in the returned XML where the user’s first name is returned. For Azure Entra ID it’s usually http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname List of available claims is automatically loaded when the Federation metadata document is imported. |
Last Name claim | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | The claim name in the returned XML where the user’s last name is returned. For Azure Entra ID it’s usually http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname List of available claims is automatically loaded when the Federation metadata document is imported. |
3.1. Federation Metadata document URL
The “Federation metadata document URL” is located in the Endpoints panel (see picture below). To locate the link go to App registrations → Endpoints and look for the “Federation metadata document“ link:
3.2. Graphlytic Application ID
3.3. Redirect URIs
