General preparation

• If it does not already exist, manually create the heavy.conf and servers.json file in $HEAVYAI_BASE (typically /var/lib/heavyai).
• Have admin access to Auth0 dashboard.
• HEAVY Immerse must be enabled for HTTPS, for callback from Auth0.  
• Add this optional config item to your heavy.conf file to allow logins from the /bin/heavysql command line tool as a local (admin) user as well as any medium other than Immerse (such as heavyai python package).  This step is not required to facilitate SAML authentication via Immerse, but it can be handy to allow you to monitor the server while SAML is being configured and tested.  Optionally remove after completion of SAML integration, if authentication can be done exclusively through Immerse (no need for heavysql, heavyai python package, direct thrift connections, etc.)

allow-local-auth-fallback= true

• Have at least one role already created in the HeavyDB to facilitate privileges for new SAML users that arrive in HEAVY.AI.  It will need to have at least database ACCESS permissions.  For this exercise we'll call the role: "DBaccess_only_role".  This can be done either in Immerse or the heavysql command line tool.  It will provide the minimal privilege needed to log into Immerse.

-----------------------------------------------------------------

heavysql> create role DBaccess_only_role;

heavysql> show roles;

ROLES

DBaccess_only_role

heavysql> grant access on database heavyai to DBaccess_only_role;

heavysql>

-----------------------------------------------------------------

 

 

Configuring SAML for Your HEAVY.AI Application

 

This exercise uses a bare metal install, whose $HEAVYAI_BASE path will be: /var/lib/heavyai

For illustration, we will use a url that points to a host whose ip was 13.56.159.185

Immerse url:    https://13.56.159.185:6273     This host is not actually in service, it is only an example.

 

1)  With a local HEAVY.AI userid, verify a successful HTTPS login to Immerse as a sanity checkpoint.

Our SAML endpoint used for the callback URL will then be: https://13.56.159.185:6273/saml-post

At the time of writing, HEAVY.AI requires our endpoint to be "saml-post" and is not customizable.

 

 

2)  Login to the Auth0 dashboard and declare your new application to be used for HEAVY.AI SAML authentication.

 

 

 

3)  Here we named our application "My new OmniSci app".  Make it a regular web application.

 

 

 

 

 

 

4)  Go to the settings tab of your new application to see its properties.

 

 

 

 

 

5)  Scroll down and enter the endpoint url of the HEAVy.AI service that Auth0 will direct the authenticated users towards.

 

 

 

6)  In the Addons tab, go to the SAML2 WEB APP to gather more config info.

 

 

 

7)  Here, you will gather the Identity Provider Login URL and the Identity Provider Metadata.

Copy the URL and download a copy of the metadata xml file.

 

 

 

8)  Upload the metadata xml file to your server's $HEAVYAI_BASE directory. 

For simplicity in this exercise, we'll rename that file to be "idp_metadata.xml".

 

 

9)  In the Settings, add your HEAVY.AI endpoint (callback) URL.

 

 

 

10)  First click the Enable button.

 

 

 

11)  Then save it afterwards.

 

 

 

 

 

 

 

Configuring the HEAVy.AI server

12)   Here we will add these items to the heavy.conf file in the [Web] section.

Config item	Description
saml-metadata-file	path to the metadata file obtained from the IdP.
saml-sp-target-url	the HEAVY.AI SAML endpoint.
saml-signed-assertion	Boolean value that determines whether Auth0 signs the assertion.
saml-signed-response	Boolean value that determines whether Auth0 signs the response.
servers-json	path to your servers.json file.

 

 

 

13)  If you do not yet have a servers.json file present, you will need to manually create one and enter the SAMLurl, which is the Identity Provider Login URL that you obtained from step 7.  This will cause new Immerse login attempts to redirect the user to Auth0 first for authentication.

For this exercise : https://dev-qi9v6hmf.us.auth0.com/samlp/F6dxMtBBZ2vCgVEO05Kjk66txTpqEjgd

[
  {
     "port": "6273",
    "SAMLurl":"https://dev-qi9v6hmf.us.auth0.com/samlp/F6dxMtBBZ2vCgVEO05Kjk66txTpqEjgd"
  }
]

 

 

 

14)  Final result of the heavy.conf file.  For now, we'll not yet require SAML signing, for simplicity.  This can be added later after basic SAML is first achieved.

port = 6274
http-port = 6278
calcite-port = 6279
data = "/var/lib/heavyai/data"
null-div-by-zero = true

allow-local-auth-fallback= true
saml-metadata-file = "/var/lib/heavyai/idp_metadata.xml"
saml-sp-target-url = "https://13.56.159.185:6273/saml-post"
saml-sync-roles = true
saml-signed-assertion = true
# Note that Auth0 does not sign the response by default 
saml-signed-response = false


[web]
port = 6273
frontend = "/opt/heavyai/frontend"
enable-https = "true"
cert = "/var/lib/heavyai/cert.pem"
key = "/var/lib/heavyai/key.pem"
servers-json = "/var/lib/heavyai/servers.json"

 

 

Create a user

15)  For this exercise, we created an HEAVY.AI end user in the Auth0 dashboard named "csmheavy37@gmail.com".

 

 

 

16)  Create the same "DBaccess_only_role" from HEAVY.AI  in Auth0.

 

 

 

17)  Assign the role to the user

 

 

 

19).  Login to the Immerse url  (would be https://13.56.159.185:6273 in this exercise) and you'll be redirected to the Auth0 site for authentication.

 

 

 

20).  You will first encounter this error as deliberately planned for this exercise.

 

 

 

21)  TROUBLESHOOTING:   

In the heavydb.INFO log, it shows that while there was actually a successful SAML authentication, the user arrived in HEAVY.AI without any privileges to access the heavyai database so they could not see any part of the Immerse page either. 

Notice that the user name for csmheavy37@gmail.com is listed here as "auth0|62095f78d357b2006e12958c".  This is the actual internal user_id property for this user, as managed by Auth0.

2022-02-13T20:15:41.524543 I 2644 0 3 SamlServer.cpp:327  User auth0|62095f78d357b2006e12958c connecting with SAML authentication
2022-02-13T20:15:41.761816 I 2644 0 3 SysCatalog.cpp:3215 User auth0|62095f78d357b2006e12958c has been created by remote identity 
provider with IS_SUPER = 'FALSE'
2022-02-13T20:15:41.761852 I 2644 0 3 SysCatalog.cpp:3257 Roles for user auth0|62095f78d357b2006e12958c are up to date with remote
identity provider
2022-02-13T20:15:41.762188 E 2644 0 3 DBHandler.cpp:837 Unauthorized Access: user auth0|62095f78d357b2006e12958c is not allowed to
access database heavyai.

 

 

 

22)  This heavysql command session also verifies that "auth0|62095f78d357b2006e12958c" did successfully arrive in HEAVY.AI and was automatically created as a new user.  This may not be the  appearance you want for each user in the UI, as it appears visually obfuscated. 

-----------------------------------------------------------------

heavysql> show user details;

NAME|ID|IS_SUPER|DEFAULT_DB|CAN_LOGIN

admin|0|true|(-1)|true

auth0|62095f78d357b2006e12958c|3|false|(-1)|true

heavysql>

-----------------------------------------------------------------

 

 

 

23)  Now we need to make csmheavy37@gmail.com be automatically mapped to the role DBaccess_only_role that we created in HEAVY.AI, so that the user will have the intended privileges to access the heavyai db.  

In order to do this, we need to create a rule in Auth0.  Go to the Auth Pipeline to create a rule.

 

 

 

24)  Use this example rule script for this exercise.  We'll arbitrarily call the new rule "setRolesToUserGroups".  Paste this into the script for the new rule.

function setRolesToUserGroups(user, context, callback) {
const authorization = context.authorization || {};
// Update the user object with the authorization roles
user.Groups = authorization.roles;
context.samlConfiguration.mappings = {"groups": "Groups", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" : "email"};
callback(null, user, context);
}

Supplemental Information: The key value pair we're adding is "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" : "email" -- note that the in the context of a Rule setting context.samlConfiguration.mappings within auth0, the key is the attribute to set and the value is the value to be transmitted. For specific keys

 

 

 

 

25)  Clear your browser cookies to drop the old session.  Re-attempt another login to the Immerse url as in step 19.  After the Auth0 authentication step, you should now land in Immerse with minimal privileges for now, until further privileges are granted to the role or user.

Here in the DATA MANAGER tab, none of the default tables are visible yet because the user has not yet been granted any privilege to SELECT from the db yet.

 

 

 

26)  In addition to seeing a successful login to Immerse, it is also verified in SHOW USER DETAILS.  Notice that the user in HEAVY.AI is now displayed as csmheavy37@gmail.com which is more recognizable, instead of the native Auth0 user_id.  The former user_id is still present and can be dropped from the heavyai db.

-----------------------------------------------------------------

heavysql> show user details;

NAME|ID|IS_SUPER|DEFAULT_DB|CAN_LOGIN

admin|0|true|(-1)|true

csmheavy37@gmail.com|2|false|(-1)|true

auth0|62095f78d357b2006e12958c|3|false|(-1)|true

heavysql>

-----------------------------------------------------------------

 

Also verified in Immerse.

 

Confirmation in heavydb.INFO log file of a successful login and mapping to DBaccess_only_role, allowing the login to Immerse.

2022-02-13T20:50:57.977488 I 2910 0 1 DBHandler.cpp:811 stdlog_begin connect 1 0     
2022-02-13T20:50:57.978316 I 2910 0 1 SamlServer.cpp:327  User csmheavy37@gmail.com connecting with SAML authentication
2022-02-13T20:50:57.978436 I 2910 0 1 SysCatalog.cpp:3257 Roles for user csmheavy37@gmail.com are up to date with remote identity 
provider
2022-02-13T20:50:57.980470 I 2910 0 1 DBHandler.cpp:860 User csmheavy37@gmail.com connected to database heavyai
2022-02-13T20:50:57.980494 I 2910 0 1 DBHandler.cpp:811 stdlog connect 1 3 heavyai csmheavy37@gmail.com 057-XFR1 {"client","roles"
} {"http:localhost:41110","DBaccess_only_role"}

 

Context & Disclaimer

This article is provided for the convenience of users attempting to integrate Auth0 as an Identity Provider (IdP) via HEAVY.AI's available SAML integration. Note that HEAVY.AI's SAML integration is agnostic to which Identity Provider (IdP) is configured.

Article content is believed to be accurate but is provided without warranty. This article shall not be construed to imply that HEAVY.AI will provide support for Auth0 or other third party applications. Auth0 is is a trademark of Auth0, Inc. HEAVY.AI, Inc. is not affiliated with Auth0, Inc.