Single Sign-On
Single sign-on (SSO) enables you to use your organization’s identity provider (IDP) to authenticate users to access TigerGraph GraphStudio and Admin Portal UI.
We have verified the following IDPs that support SAML 2.0 protocol:
For supporting additional IDPs, please contact sales@tigergraph.com and submit a feature request.
To set up single sign-on, you need to perform three steps :
-
Configure your identity provider to create a TigerGraph application.
-
Provide information from your identity provider to enable TigerGraph single sign-on.
-
Create user groups with proxy rules to authorize single sign-on users.
Before you begin
-
Ensure that you can access GraphStudio UI through a web browser using the URL: http://tigergraph-machine-honestname:14240
-
If you enabled SSL connection, change
http
tohttps
. If you changed the Nginx port of the TigerGraph system, replace 14240 with the port you have set.
-
-
Ensure that you have enabled GSQL authentication by changing the password of the default user. If you don’t enable GSQL authentication, SSO configuration will not work and any user will be logged in automatically.
During the SSO authentication process, TigerGraph sends a response with a large header to confirm the result of the authentication request. If you use any middleware such as an Nginx load balancer between TigerGraph and your IDP, make sure that your middleware is able to handle the size of the responses. For example, if using Nginx, make sure proxy buffering is turned on. |
1. Configure Identity Provider
Below are detailed instructions for identity providers that we have verified. Please consult your IT or security department for how to configure the identity provider for your organization if it is not listed here.
After you finish configuring your identity provider, you will get the following:
-
An Identity Provider single sign-on URL
-
An Identity Provider Entity ID
-
an X.509 certificate file
idp.cert
. You need these 3 things to configure TigerGraph next.
Okta
Create an Application Integration in Okta for your TigerGraph application. Below are the Assertion Consumer Service URL / Single sign on URL , and SP Entity ID required for this process:
-
Assertion Consumer Service URL/Single sign on URL:
http://<tigergraph-machine-hostname>:14240/api/auth/saml/acs
-
SP Entity ID URL:
http://<tigergraph-machine-hostname>:14240/gsqlserver/gsql/saml/meta
Auth0
-
Register TigerGraph as a Single-Page web application in Auth0.
-
Configure Auth0 as SAML Identity provider. You will need to enter the following information when following Auth0’s guide:
-
Application Callback URL: http://<tigergraph-machine-hostname>:14240/api/auth/saml/acs`
-
When downloading the certificate from Auth0, choose
.cer
format instead of.pem
format.
-
Azure AD
-
Log in to Azure Active Directory Admin Center as an Admin user. In the left menu, select .
-
In the top left corner, click Create your own application.
In the form that appears on the right side of the page, fill in the name of your application and choose Integrate any other application you don’t find in the gallery (Non-gallery). This creates the application and takes you to the application page.
-
Click Users and groups on the left pane, add the users or groups you want to give access to TigerGraph, choose the appropriate role, and click Assign.
-
After adding users and groups, click Single sign-on and choose SAML.
This takes you to a page titled "Set up single sign-on with SAML".
-
Fill in Identifier (Entity ID) and Reply URL with the information below. Replace
<tigergraph-machine-hostname>
with the host name of your TigerGraph instance:-
Identifier (Entity ID):
https://<tigergraph-machine-hostname>:14240/gsqlserver/gsql/saml/meta
-
Reply URL:
https://<tigergraph-machine-hostname>:14240/api/auth/saml/acs
-
-
After filling in the Entity ID and Reply URL, click Edit for SAML Signing Certificate, and choose Sign SAML Assertion and Response. Click Save and download certificate (base64).
-
We recommend signing both assertion and response for maximum security. However, you may choose to only sign one of them, but you need to match this with your SSO settings in TigerGraph.
-
-
Under "Set up <Application name>", Azure AD provides a login URL, an Azure AD identifier, and a logout URL. These items are used in the next steps to configure single sign-on in TigerGraph.
PingFederate
Prerequisites
-
You have a running PingFederate server with the required ports available.
-
You have created users within PingFederate for those who are using PingFederate to sign on to TigerGraph.
-
You have created and exported a certificate from on PingFederate.
-
The certificate’s common name must be the IP of your PingFederate server.
-
-
You have created a Password Credential Validator (PCV) instance.
-
You have created an HTML Form IdP Adaptor instance and configured the adaptor instance to use your PCV.
Procedure
Go to the APPLICATIONS page in PingFederate, open SP Connection Management.
, then click Create Connection to add a Service Provider (SP) connection to TigerGraph. Follow the instructions in the product and enter the additional information as required. There are many configuration options available in PingFederate. This guide provides an example setup. To learn about each of the available options, see-
In this guide, we do not use a connection template for this SP connection.
-
Choose the Browser SSO Profiles connection type on the Connection Type page.
-
Check the Browser SSO option on the Connection Options page and choose the SAML 2.0 protocol.
-
Skip the Import Metadata step.
-
For General Info, choose a name to name your connection. Refer to the following for Partner’s Entity ID and Base URL:
-
Partner’s Entity ID (Connection ID):
http://<tigergraph-machine-hostname>:14240/gsqlserver/gsql/saml/meta
-
Base URL:
http://<tigergraph-machine-hostname>:14240
-
-
Click Configure Browser SSO on the Browser SSO page to configure browser SSO.
-
Check IdP-Initiated SSO and SP-Initiated SSO on the SAML Profiles page.
-
Choose Standard Identity Mapping option for configuring assertion creation.
-
Change the Subject Name Format for the SAML_SUBJECT field to
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
orurn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
-
In Authentication Source Mapping, click Map New Adaptor Instance and choose an adaptor instance. Follow the in-product instructions to finish configuring the adaptor instance.
-
-
Configure Protocol Settings.
-
For
, set Binding to "POST". For Endpoint URL, fill inhttp://<tigergraph-machine-hostname>:14240/api/auth/saml/acs
. -
For Allowable SAML Bindings, check
POST
andREDIRECT
. -
Configure signature policy and encryption policy tp suit your needs.
-
-
-
Configure credentials. On the Credentials page, click Configure Credentials, and choose a certificate to be the signing certificate. This must be the same certificate that you upload to TigerGraph later.
-
Verify the details of your SP connection and click Save.
After setting up the SP connection, return to the SP Connections page, find the connection and click
. The exported XML file provides the information you need to configure single sign-on in TigerGraph.-
IDP’s SSO URL:
Location attribute
of the md:SingleSignOnService` element in the XML file. -
Entity ID:
entityID
attribute of themd:EntityDescriptor
element field in the XML file. -
Identity Provider’s X509 certificate:
ds:X509Certificate
element in the XML file. You can also export the certificate directly in PingFederate. -
Authentication context:
md:NameIDFormat
element in the XML file.
Active Directory Federation Services (AD FS)
Prerequisites
-
A Windows Server which has AD FS Server configured. If this is not set up, follow these instructions to configure it: Deploying a federation server farm
A configured AD FS server should belong to an AD DS (Domain Service) and have an available certificate service. |
-
Ensure that you have domain administrator permissions or have domain administrator credentials available before you perform this procedure.
Configure AD FS
-
Create a relying party trust in AD FS.
-
Under "Relying party identifiers", use this format, where
host
is replaced by your TigerGraph Server public IP address:
https://host:14240/gsqlserver/gsql/saml/meta`
-
In the Endpoints tab, your URL appears under SAML Assertion Consumer Endpoints. The Trusted URL is in this format:
https://host:14240/api/auth/saml/acs
-
Export the public certificate of the AD FS server for TigerGraph use. Open the AD FS Management dialog and export the Token-signing certificate
-
Right-click the certificate → View certificate
-
Details → Copy to file
-
Base64 encoded X.509
-
-
Run the following command to make the AD FS server sign SAML responses. In this example, <display name> takes the place of your actual Display Name in the Relying Party Trusts list.
Set-AdfsRelyingPartyTrust -TargetName <display name> -SamlResponseSignature "MessageAndAssertion"
-
TigerGraph needs a required Claim Name ID to know which user is logging in successfully. Following these instructions, create a transform claim rule: Create a rule to transform an incoming claim
Configure TigerGraph
After configuring AD FS as described previously, you must now configure TigerGraph to accept the connection. This is handled in Admin Portal on the SSO page. Single Sign-on (SSO)
-
In the field Identity Provider’s X509 certificate, use the certificate exported in Step #4 above.
-
For the Identity Provider’s entity ID, use a value in this format: (adfs.company.com means the URL of the AD FS server)
http://adfs.company.com/adfs/services/trust
-
For the Identity Provider’s SSO URL, use the AD FS SSO URL. In general, it uses a value in this format:
https://adfs.company.com/adfs/ls/
-
For IDP SignonBinding, check Redirect.
The final configuration should appear similar to this screenshot:
2. Enable single sign-on in TigerGraph
Having configured the identity provider and obtained the identity provider’s SSO URL, entity ID and certificate, the next step is to provide the information to TigerGraph to enable single sign-on.
2.1. Navigate to SSO page
From GraphStudio home page, click Admin Portal in the upper right corner. In the left pane, click
. At the top of the SSO page, click the toggle to Enable SAML-based SSO.2.2. Update service provider URL
The service provider (in this case - TigerGraph) URL is the same URL that you use to access GraphStudio.
2.3. Prepare service provider certificate and private key
Under SAML, the service provider can optionally sign the SAML requests made to the identity provider. This step configures the certificate and private key used for the signature.
According to the SAML standard trust model, a self-signed certificate is acceptable. This is different from configuring an SSL connection, where a CA-authorized certificate is considered mandatory if the system goes to production.
You can generate a self-signed private key and x-509 certificate from GraphStudio. Click the button next to the Service Provider’s private key field:
, and fill in your information to generate a self-signed private key and x-509 certificate.2.4. Provide IDP certificate, entity ID, and URLs
Upload the certificate you downloaded from the identity provider in the previous step, and provide the identity provider’s entity ID and single sign-on URL in the corresponding fields.
2.5. Configure security options
At the bottom of the SSO page are a list of security options you can configure for SSO:
-
Sign authentication requests before sending to Identity Provider
-
Require Identity Provider to sign responses
-
Require Identity Provider to sign assertions
-
Require Identity Provider to sign metadata
-
-
An attribute that defines how a user must log in. This is an optional configuration. You can leave it blank if you do not want to restrict how users must log in or if you are not sure what value to provide for this field.
-
Example value:
urn:oasis:names:tc:SAML:2.0:ac:classes:Password
-
Known issue: Authentication context is a required field in Admin Portal. To set this configuration to blank, log in to the server as the TigerGraph Linux user and run the following command:
|
It is recommended that you enable as many of the options as possible for maximum security. However, some identity providers do not support enabling certain options at the same time. Refer to your identity provider’s documentation to determine which options to use.
2.6. Command-line options
Besides providing the SSO information in the UI, you also have the option of providing the information using gadmin config
through the command-line.
Below is the list of parameters you need to configure.
You can run gadmin config set
to configure their value non-interactively, or run gadmin config entry Security.SSO.SAML
to configure their values interactively in the terminal.
Name | Description | Example |
---|---|---|
Security.SSO.SAML.AssertionSigned |
Require Identity Provider to sign assertions: default true |
|
Security.SSO.SAML.AuthnRequestSigned |
Sign AuthnRequests before sending to Identity Provider: default true |
|
Security.SSO.SAML.BuiltinUser |
The builtin user for SAML |
|
Security.SSO.SAML.Enable |
Enable SAML2-based SSO: default false |
|
Security.SSO.SAML.IDP.EntityId |
Identity Provider Entity ID: default http://idp.example.com |
|
Security.SSO.SAML.IDP.SSOUrl |
single sign-on URL: default http://idp.example.com/sso/saml |
|
Security.SSO.SAML.IDP.X509Cert |
Identity Provider’s x509 Certificate filepath: default empty. You can use @/cert/file/path to pass the certificate from a file. |
|
Security.SSO.SAML.MetadataSigned |
Sign Metadata: default true |
|
Security.SSO.SAML.RequestedAuthnContext |
Authentication context (comma separate multiple values) |
|
Security.SSO.SAML.ResponseSigned |
Require Identity Provider to sign SAML responses: default true |
|
Security.SSO.SAML.SP.Hostname |
TigerGraph Service Provider URL: default http://127.0.0.1:14240 |
|
Security.SSO.SAML.SP.PrivateKey |
Content of the host machine’s private key. Require PKCS#8 format (start with “BEGIN PRIVATE KEY”). You can use @/privatekey/file/path to pass the certificate from a file. |
|
Security.SSO.SAML.SP.X509Cert |
Content of the x509 Certificate: default empty. You can use @/cert/file/path to pass the certificate from a file. |
|
Security.SSO.SAML.SignatureAlgorithm |
Signature algorithm [rsa-sha1/rsa-sha256/rsa-sha384/rsa-sha512]: default rsa-sha256 |
|
3. Create user groups with proxy rules to authorize single sign-on users
In order to authorize single sign-on users, you need create user groups with proxy rules and grant roles on graphs for the user groups. Proxy rules assign users who log in through SSO into proxy groups based on the attributes of the user from the identity provider’s response.
3.1. Required privilege
-
WRITE_PROXYGROUP
for creating proxy groups. -
WRITE_ROLE
for granting roles to users
3.1.1. Create proxy groups in Admin Portal
You can create proxy groups in Admin Portal:
-
From Admin Portal, navigate to
. -
Click Add Group, and give the group a name.
-
Provide the attribute equation for the proxy group. If a user’s specified attribute matches the value in the equation, they will be assigned to this proxy group.
After creating the proxy group, you can start granting roles to the proxy group. All users matching the proxy rule will be granted all the privileges of that role. To learn how to grant roles, see Role Management.
3.1.2. Create proxy groups in GSQL shell
You can create proxy groups with GSQL commands.
Single User Proxy
For example, if you want to create a user group SuperUserGroup
that contains the user with nameid admin@your.company.com
only, and grant superuser
role to that user, you can do so with the following command:
GSQL > CREATE GROUP SuperUserGroup PROXY "nameid=admin@your.company.com"
GSQL > GRANT ROLE superuser TO SuperUserGroup
Role "superuser" is successfully granted to user(s): SuperUserGroup
User Group Proxy
Suppose you want to create a user group HrDepartment
which corresponds to the identity provider single sign-on users having the group attribute value hr-department
, and want to grant the queryreader role to that group on the graph HrGraph:
GSQL > CREATE GROUP HrDepartment PROXY "group=hr-department"
GSQL > GRANT ROLE queryreader ON GRAPH HrGraph TO HrDepartment
Role "queryreader" is successfully granted to user(s): HrDepartment
4. Test single sign-on
To test if single sign-on is working, visit the GraphStudio UI in your browser. You should see a Login with SSO button:
Click the button to navigate to your identity provider’s login portal:
-
If you are already logged in with your identity provider, you will be redirected back to GraphStudio immediately. After about 10 seconds, the verification should finish, and you are authorized to use GraphStudio.
-
If you aren’t logged in at your identity provider, you will need to log in.
After logging in successfully, you will see your single sign-on username when you click the User icon at the upper right of the GraphStudio UI.
Common errors
Below are a few common SSO errors and how to resolve them.
User has no access to any graph
-
If you return to the login page and see the error message saying you do not have access to any graph, check your user group proxy rules, and roles you have granted to the groups.
"Login failed. Please contact system admin."
-
If your single sign-on fails with the above error message, it usually means the configuration are inconsistent between TigerGraph and your identity provider.
You can check your GSQL log to investigate. First, find your GSQL log file with the following:
$ gadmin log gsql
GSQL : /home/tigergraph/tigergraph/log/gsql/log.INFO
Then, grep the SAML authentication-related logs:
cat /home/tigergraph/tigergraph/log/gsql/log.INFO | grep SAMLAuth
Focus on the latest errors. Usually the text is self-descriptive. Follow the error message and try to fix TigerGraph or your identity provider’s configuration.
If the problem persists or if you encounter any errors that are not clear, please open a support ticket.