About Domino
Domino Data LabKnowledge BaseData Science BlogTraining

Connect to Okera

This topic describes how to connect to the Okera Active Data Access Platform from Domino. You must have network connectivity between Okera and your Domino deployment.

Warning
 Domino does not officially support this method. We provide this information as a courtesy.

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

If you allow users to create their own accounts, Domino recommends that you use another authentication method.

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.

See the Okera docs for detailed instructions on Okera configuration.

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 credentials 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.

See 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

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)

After 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))

See Pyokera to learn more about using.

Next steps