Connecting to OmniSci 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 Provide_r (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 OmniSci, and SAML login fails, OmniSci 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 OmniSci as the SP in an SP-initiated workflow, similar to the following:

1. A user uses a login page to connect to OmniSci.

2. The OmniSci 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 OmniSci. If configured, it also returns a list of SAML Groups assigned to the user.

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

6. OmniSci 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 OmniSci and click Next.

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

• Single sign on URL: Your OmniSci 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 OmniSci Immerse web URL with the suffix saml-post.

• Default RelayState: Forward slash (/).

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

Leave other setttings 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 OmniSci Application

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 OmniSci 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 OmniSci server in $OMNISCI_STORAGE.

4) Edit omnisci.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 OmniSci 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 = "/omnisci-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 = "/omnisci-storage/ssl/server.crt"
  key = "/omnisci-storage/ssl/server.key"
  jupyter-url = "http://jupyterhub:8000"
  servers-json = "/omnisci-storage/servers.json"

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

https://omnisci-tony.okta.com/app/omnisciorg969324_omnisci_2/exk1p0m4blWiBsFiU357/sso/saml

6) If the servers.json file you identified in the [web] section of omnisci.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://omnisci-tony.okta.com/app/omnisciorg969324_omnisci_2/exk1p0m4blWiBsFiU357/sso/saml"
  }
]

7) Restart the omnisci_server and omnisci_web_server services.

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

9) On the Assign OmniSci to People panel, click the Assign button next to users that you want to provide access to OmniSci. You provide access to groups of users in the same way.

10) Click Save and Go Back to assign OmniSci to the user.

11) Repeat steps 9 and 10 for all users to whom you want to grant access. Click Done when you are finished.

User accounts assigned to the OmniSci application in Okta must exist in OmniSci 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 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 omnisci.license to your OmniSci data directory.

   • Logging in to OmniSciDB and run the following command:

     omnisql> \set_license

2. Reattempt login through Okta.

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

Auto-Creating Users with SAML

Users can be automatically created in OmniSci based on group membership:

1) Go to the Application Configuration page for the OmniSci 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 OmniSci 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 OmniSci must be created in OmniSci before users can log in.

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

   saml-sync-roles = true

   The omnisci.conf entries now look like this:

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

2. Restart the omnisci_server and omnisci_web_server processes.

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