Single Sign-On

Document Updated:


14 Mar 2018

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. If your IDP supports SAML 2.0 protocol, you should be able to integrate your

identity provider

with TigerGraph

Single Sign-On

.

Currently we have verified following identity providers:

• 
  Okta
  
• 
  Auth0
  

In order to use

Single Sign-On

, you need perform
four 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.
   
4. 
   Change the password of the
   
   tigergraph
   
   user to be other than the default, if you haven’t
   done
   so already.
   

We assume you already have TigerGraph
up and running
, and you can access GraphStudio UI through a web browser using the URL:

If you enabled SSL connection, change http to https. If you changed the nginx port of the TigerGraph system, replace 14240 with the port you have set.

1 Configure I

dentity Provider

Here we provide 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 an

Identity Provider Single Sign-On URL

,

Identity Provider Entity Id

, and an X.509 certificate file

idp.cert

. You need these 3 things to configure TigerGraph next.

Okta

After logging into Okta as the admin user, click

Admin

button at the top-right corner.

Click

Add Applications

in the right menu.

Click

Create New App

button in the left toolbar.

In the pop up window, choose

SAML 2.0

and click

Create

.

Input TigerGraph (or whatever application name you want to use) in

App Name

, and click

Next

. Upload a logo if you like.

Enter the

Assertion Consumer Service URL

/

Single sign on URL

, and

SP Entity ID

.

Both are URLs in our case. You need to know the hostname of the TigerGraph machine. If you can visit GraphStudio UI through a browser, the URL contains the hostname. It can be either an IP or a domain name.

The




Assertion Consumer Service URL

, or Single sign on URL, is

The

SP entity id

URL is:

Scroll to the bottom for Group Attribute Statements. Usually you want to grant roles to users based on their user group. You can give a name to your attribute statement; here we use

group

. For filter, we want to return all group attribute values of all users, so we use

Regex .*

as the filter. Click

Next

after you set up everything.

In the final step, choose whether you want to integrate your app with Okta or not. Then click

Finish

.

Now your Okta identity provider settings are finished. Click

View Setup Instructions

button to gather information you will need to setup TigerGraph Single Sign-On.

Here you want to save

Identity Provider Single Sign-On URL

and

Identity Provider Issuer

(usually known as

Identity Provider Entity Id

). Download the certificate file as okta.cert, rename it as

idp.cert

, and put it somewhere on the TigerGraph machine. Let’s assume you put it under your home folder: /home/tigergraph/idp.cert. If you installed TigerGraph in a cluster, you should put it on the machine where the GSQL server is installed (usually it’s the machine whose alias is m1).

Finally, return to previous page, go to the

Assignments

tab, click the

Assign

button, and assign people or groups in your organization to access this appllication.

end of Okta configuration instructions. Jump to Step 2:

Enable Single Sign-On for TigerGraph

Auth0

After logging into Auth0, click

Clients

in the left navigation bar, and then click

CREATE CLIENT

button.

In the pop-up window, enter


TigerGraph (or whatever application name you want to use) in the Name input box. Choose

Single Page Web Application

, and then click the

CREATE

button.

Click

Clients

again. In the Shown Clients list, click the

settings

icon of your newly created TigerGraph client.

Scroll down to the bottom of the settings section, and click

Show Advanced Settings

.

Click the

Certificates

tab and then click

DOWNLOAD CERTIFICATE. I

n the chooser list, choose

CER

. Rename the downloaded file as

idp.cert

,

and put it somewhere on the TigerGraph machine. Let’s assume you put it under your home folder: /home/tigergraph/idp.cert. If you installed TigerGraph in a cluster, you should put it on the machine where the GSQL server is installed (

usually it’s the machine whose alias is m1

).

Click the

Endpoints

tab, and copy the text in the

SAML Protocol URL

text box.  This is the


Identity Provider Single Sign-On URL



that will be used to configure TigerGraph in an upcoming step.

Scroll up to the top of the page, click the

Addons

tab, and switch on the toggle at the right side of the

SAML2

card.

In the pop-up window, enter the







Assertion Consumer Service URL

in the Application Callback URL input box:

Scroll down to the end of the settings JSON code, click the

DEBUG

button, and log in as any existing user in your organization in the pop-up login page.

If login in successfully, the SAML response will be shown in decoded XML format. Scroll down to the attributes section. Here you will see some attribute names, which you will use to set proxy rules when creating groups in an upcoming configuration step.

Return to the previous pop-up window and click the

Usage

tab. Copy the

Issuer

value. This is the


Identity Provider Entity Id

that will be used to configure TigerGraph in an upcoming step.

Click the

Settings

tab, scroll to the bottom of the pop-up window, and click the

SAVE

button. Close the pop-up window.

end of Auth0 configuration instructions. Jump to Step 2:

Enable Single Sign-On for TigerGraph

2 Enable Single Sign-On in TigerGraph

Prepare certificate and private key on TigerGraph machine

According to the SAML standard trust model, a self-signed certificate is considered fine. This is different from configuring a SSL connection, where a CA-authorized certificate is considered mandatory if the system goes to production.

There are multiple ways to create a self-signed certificate.  One example is shown below.

First, use the following command to generate a private key in PKCS#1 format and a X.509 certificate file.

In the example below, the Common Name value should be your server hostname (IP or domain name).

Second, convert your private key from PKCS#1 format to PKCS#8 format:

Finally, change the certificate and private key file to have permission 600 or less. (The tigergraph user can read or write the file; no other user has any permission.)

Enable and configure Single Sign-On Using Gadmin

From a TigerGraph machine, run the following command: gadmin –configure sso.saml

Answering the questions is straightforward; an example is shown below.

The reason we change

security.sso.saml.advanced.responses.signed

to false is because some identity providers (e.g., Auth0) don’t support signed assertion and response at the same time. If your identity provider supports signing both, we strongly suggest you leave it as true.

After making the configuration settings, apply the config changes, and restart gsql.

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 in GSQL with proxy rules and grant roles on graphs for the user groups.

In TigerGraph Single Sign-On, we support two types of proxy rules. The first type is nameid equations; the second type is attribute equations. Attribute equations are more commonly used because usually user group information is transferred as attributes to your identiity provider SAML assertions. In the Okta identity provider configuration example, it is transferred by the attribute statement named

group

. By granting roles to a user group, all users matching the proxy rule will be granted all the privileges of that role.  In some cases if you want to grant one specific Single Sign-On user some privilege, you can use a nameid equation to do so.

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:

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:

4 Change Password Of Default User

Don’t forget to enable User Authorization in TigerGraph by changing the password of the default superuser

tigergraph

to other than its default value. If you do not change the password, then every time you visit the GraphStudio UI, you will automatically log in as the superuser tigergraph.

Testing Single Sign-On

Now you have finished all configurations for Single Sign-On. Let’s test it.

Visit the GraphStudio UI in your browser. You should see a

Login with SSO

button appear on top of the login panel:

Clicking the button will navigate to your identity provider’s login portal. If you have already logged in there, 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 haven’t login at your identity provider yet, you will need to log in there. 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.

If after redirecting back to GraphStudio, you return to the login page with the error message shown below, that means the Single Sign-On user doesn’t have access to any graph. Please double check your user group proxy rules, and roles you have granted to the groups.

If your Single Sign-On fails with error message show below, that means either some configuration is inconsistent between TigerGraph and your identity provider, or something unexpected happened.

You can check your GSQL log to investigate. First, find your GSQL log file with the following:

Then, grep the SAML authentication-related logs:

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 you encounter any errors that are not clear, please contact

support@tigergraph.com

.