Connecting to Okera from Domino


Overview

This article describes how to connect to the Okera Active Data Access Platform from Domino.

The Okera Active Data Access Platform unifies and manages access for data consumers by providing an Automated Schema Registry, Policy Engine and Audit Engine.

Domino and Okera make it easy to access securely and simply data governed by Okera for analysis in Domino.


Credential Setup

Option A - JWT Token

The simplest method for authentication with Okera from Domino is to use the JWT token provided by Domino.

Domino automatically populates all Workspaces and Batch Jobs with a user specific, securely signed token that can be used for authentication. When used in conjunction with Single Sign On (SSO), you can achieve a chain of identity from you identity provider through Domino to Okera. No additional set up in Domino is required.

Warning

We do not recommend using this authentication method if are not using a Single Sign On (SSO) and allow end users to create their own accounts.

Since all Domino issued tokens are securely signed by Domino, Okera needs to be configured to validate the JWT signature using Domino’s public key.

For me detailed instructions on Okera configuration see the Okera docs here.

Required metadata from Domino:

  • JWT_PUBLIC_KEY for your Domino deployment can be found at <your domino url>/auth/realms/DominoRealm
  • JWT_ALGORITHM will be RS256 by default
  • JWT_USER_CLAIM_KEY allows you to bind users identity in Domino to their identity in Okera so a user can only authenticate at themselves. Typically, you will want to use the preferred_username from the Domino token if you’ve used the same username pattern in Domino and Okera. Alternatively, you can create a custom claims in your Domino token by mapping in additional SAML attributes or deriving a value from the user’s email address, for example.

Option B - Username & Password

Alternatively, Okera also allows for authentication via a username and password. This requires an extra set up step on the part of each end user. Similar to storing credential for other data sources, users can add their credentials as Domino user environment variables. These variables are then populated to that user’s workspace and batch jobs.

Read Environment Variables for Secure Credential Storage to learn more about Domino environment variables.

Environment Libraries Setup

Installation

Okera’s Pyokera package is available from pip. The Dockerfile instruction below is what you’ll need to install Pyokera.

RUN pip install pyokera

For a basic introduction to modifying Domino environments, watch this tutorial video.

Alternative Installation

A more secure method of reading S3 from the OS shell of a Domino executor is the AWS CLI. Making the AWS CLI work from your executor is a two-step process. You need to install it in your environment, and provide it with your credentials.

Usage (Accessing Data in Python)

Once Pyokera is installed in your compute environment, you can access your Okera data using the following code snippet by adding in the URI for you Okera instance:

#Load the Pyokera package
import os
from okera import context

#Load the Domino Auth Token which should always be available and refreshed at $DOMINO_TOKEN_FILE
def get_token():
    return open(os.environ.get('DOMINO_TOKEN_FILE'), 'r').read().strip()

#Connect to Okera using your token and using the environment variable $DOMINO_STARTING_USERNAME which be populated with your Domino username
ctx = context()
ctx.enable_token_auth(token_func=get_token, user=os.environ['DOMINO_STARTING_USERNAME'])

#Query Okera
with ctx.connect(host='<URI for your Okera Instance>', port=12050) as conn:
    display(conn.scan_as_pandas('select * from okera_sample.whoami', strings_as_utf8=True))

Learn more about using Pyokera