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... -----END CERTIFICATE-----	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... -----END CERTIFICATE-----	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
1. it should be a public URL pointing to your Graphlytic instance
2. 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………. -----END CERTIFICATE-----	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 See chapter "3.3. Redirect URIs" for more information
Group Claim	http://schemas.microsoft.com/ws/2008/06/identity/claims/groups	For Azure Entra ID it’s usually one of these: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups http://schemas.microsoft.com/ws/2008/06/identity/claims/role 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: