Single Sign-On

The Single Sign-On (SSO) feature in TigerGraph 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 identity providers that support SAML 2.0 protocol:

For supporting additional IDPs, please inquire sales@tigergraph.com and submit a feature request.

In order to use Single Sign-On , you need to perform three steps :

  1. Configure your identity provider to create a TigerGraph application.

  2. Provide information from your identity provider to enable TigerGraph Single Sign-On.

  3. Create user groups with proxy rules to authorize Single Sign-On users.

Before you begin

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

Follow Okta’s documentation to create an Application Integration 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

  1. Follow the Auth0 documentation to register TigerGraph as a Single-Page web application.

  2. Follow the Auth0 documentation to 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.

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. Update service provider URL

The service provider (in this case - TigerGraph) URL is the same URL that you use to access GraphStudio.

2.2. 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.3. Prepare certificate and private key on TigerGraph machine

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: Upload file  Self Signed, and fill in your information to generate a self-signed private key and x-509 certificate.

2.4. 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

  • Signature algorithm

  • Authentication context

    • An attribute that defines how a user should log in.

    • Example value: urn:oasis:names:tc:SAML:2.0:ac:classes:Password

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:

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

You can create proxy groups in Admin Portal:

  1. From Admin Portal, navigate to Management  Users  Proxy Group.

  2. Click Add Group, and give the group a name.

  3. 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.

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:

11.25

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 11.1 (1) 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 contact support@tigergraph.com.