Connecting Using SAML

Security Assertion Markup Language (SAML) is used for exchanging authentication and authorization data between security domains. SAML uses security tokens containing assertions (statements that service providers use to make decisions about access control) to pass information about a principal (usually an end user) between a SAML authority, named an Identity Provider (IdP), and a SAML consumer, named a Service Provider (SP). SAML enables web-based, cross-domain, single sign-on (SSO), which helps reduce the administrative overhead of sending multiple authentication tokens to the user.

If you use SAML for authentication to HEAVY.AI, and SAML login fails, HEAVY.AI automatically falls back to log in using LDAP if it is configured.

If both SAML and LDAP authentication fail, you are authenticated against a locally stored password, but only if the allow-local-auth-fallback flag is set.

These instructions use Okta as the IdP and HEAVY.AI as the SP in an SP-initiated workflow, similar to the following:

1. A user uses a login page to connect to HEAVY.AI.

2. The HEAVY.AI login page redirects the user to the Okta login page.

3. The user signs in using an Okta account. (This step is skipped if the user is already logged in to Okta.)

4. Okta returns a base64-encoded SAML Response to the user, which contains a SAML Assertion that the user is allowed to use HEAVY.AI. If configured, it also returns a list of SAML Groups assigned to the user.

5. Okta redirects the user to the HEAVY.AI login page together with the SAML response (a token).

6. HEAVY.AI verifies the token, and retrieves the user name and groups. Authentication and authorization is complete.

In addition to Okta, the following SAML providers are also supported:

• auth0

• Ping Identity

• Keycloak

• Oracle Access Management

Registering Your SAML Application in Okta

Begin by adding your SAML application in Okta. If you do not have an Okta account, you can sign up on the Okta web page.

1) Log into your Okta account and click the Admin button.

2) From the Applications menu, select Applications.

3) Click the Add Application button.

4) On the Add Application screen, click Create New App.

5) On the Create a New Application Integration page, set the following details:

• Platform: Web

• Sign on Method: SAML 2.0

  And then, click Create.

6) On the Create SAML Integration page, in the App name field, type Heavyai and click Next.

7) In the SAML Settings page, enter the following information:

• Single sign on URL: Your Heavy Immerse web URL with the suffix saml-post; for example, https://tonysingle.com:6273/saml-post. Select the Use this for Recipient URL and Destination URL checkbox.

• Audience URI (SP Entity ID): Your Heavy Immerse web URL with the suffix saml-post.

• Default RelayState: Forward slash (/).

• Application username: HEAVY.AI recommends using the email address you used to log in to Okta.

Leave other settings at their default values, or change as required for your specific installation.

After making your selections, click Next.

8) In the Help Okta Support... page, click I'm an Okta customer adding an internal app. All other questions on this page are optional.

After making your selections, click Finish.

Your application is now registered and displayed, and the Sign On tab is selected.

Configuring SAML for Your HEAVY.AI Application

Before configuring SAML, make sure that HTTPS is enabled on your web server.

On the Sign On tab, configure SAML settings for your application:

1) On the Settings page, click View Setup Instructions.

2) On the How to Configure SAML 2.0 for HEAVY.AI Application page, scroll to the bottom, copy the XML fragment in the Provide the following IDP metadata to your SP provider box, and save it as a raw text file called idp.xml.

3) Upload idp.xml to your HEAVY.AI server in $HEAVYAI_STORAGE.

4) Edit heavy.conf and add the following configuration parameters:

• saml-metadata-file: Path to the idp.xml file you created.

• saml-sp-target-url: Web URL to your Heavy Immerse saml-post endpoint.

• saml-signed-assertion: Boolean value that determines whether Okta signs the assertion; true by default.

• saml-signed-response: Boolean value that determines whether Okta signs the response; true by default.

  For example:

  saml-metadata-file = "/heavyai-storage/idp.xml"
  saml-sp-target-url = "https://tonysingle.com:6273/saml-post"
  saml-signed-assertion = true
  saml-signed-response = true

• In the web section, add the full physical path to the servers.json file; for example:

  [web]
  enable-https = true
  cert = "/heavyai-storage/ssl/server.crt"
  key = "/heavyai-storage/ssl/server.key"
  servers-json = "/heavyai-storage/servers.json"

5) On the How to Configure SAML 2.0 for HEAVY.AI Application page, copy the Identity Provider Single Sign-On URL, which looks similar to this:

https://heavyai-tony.okta.com/app/heavyaiorg969324_heavyai_2/exk1p0m4blWiBsFiU357/sso/saml

6) If the servers.json file you identified in the [web] section of heavy.conf does not exist, create it. In servers.json, include the SAMLurl property, using the same value you copied in Identify Provider Single Sign-On URL. For example:

 [
  {
    "enableJupyter": true,
     "url": "tonysingle.com",
     "port": "6273",
    "SAMLurl":"https://heavyai-tony.okta.com/app/heavyaiorg969324_heavyai_2/exk1p0m4blWiBsFiU357/sso/saml"
  }
]

7) Restart the heavyai_server and heavyai_web_server services.

Auto-Creating Users with SAML

Users can be automatically created in HEAVY.AI based on group membership:

1) Go to the Application Configuration page for the HEAVY.AI application in Okta.

2) On the General tab, scroll to the SAML Settings section and click the Edit button.

3) Click the Next button, and then in the Group Attribute Statements section, set the following:

• Name: Groups

• Filter: Set to the desired filter type to determine the set of groups delivered to HEAVY.AI through the SAML response. In the text box next to the Filter type drop-down box, enter the text that defines the filter.

• Click Next, and then click Finish.

Any group that requires access to HEAVY.AI must be created in HEAVY.AI before users can log in.

1. Modify your heavyai.conf file by adding the following parameter:

   saml-sync-roles = true

   The heavyai.conf entries now look like this:

   saml-metadata-file = "/heavyai-storage/idp.xml"
   saml-sp-target-url = "https://tonysingle.com:6273/saml-post"
   saml-sync-roles = true

2. Restart the heavyai_server and heavyai_web_server processes.

Users whose group membership in Okta contains a group name that exists in HeavyDB can log in and have the privileges assigned to their groups.

Creating Users Manually

1) On the Okta website, on the Assignments tab, click Assign > Assign to People.

2) On the Assign HEAVY.AI to People panel, click the Assign button next to users that you want to provide access to HEAVY.AI.

3) Click Save and Go Back to assign HEAVY.AI to the user.

) Repeat steps 2 and 3 for all users to whom you want to grant access. Click Done when you are finished.

User accounts assigned to the HEAVY.AI application in Okta must exist in HEAVY.AI before a user can log in. To have users created automatically based on their group membership, see Auto-Creating Users with SAML.

Verifying SAML Configuration

Verify that the SAML is configured correctly by opening your Heavy Immerse login page. You should be automatically redirected to the Okta login page, and then back to Immerse, without entering credentials.

When you log out of Immerse, you see the following screen:

Logging out of Immerse does not log you out of Okta. If you log back in to Immerse and are still logged in to Okta, you do not need to reathenticate.

If authentication fails, you see this error message when you attempt to log in through Okta:

To resolve the authentication error:

1. Add the license information by either:

   • Adding heavyai.license to your HEAVY.AI data directory.

   • Logging in to HeavyDB and run the following command:

     heavysql> \set_license

2. Reattempt login through Okta.

The Information about authentication errors can be found in the log files.