Secure Okera REST API Access using OAuth

The Okera REST API supports OAuth integration, primarily to enable easier Web UI access. This document explains how to set up the REST API with OAuth to make the Web UI login easier.

OAuth Basics

In setting up the REST API with basic OAuth integration, the REST API will be able to accept an OAuth code token and exchange it for an Okera token automatically. This allows the Web UI to redirect an Okera user from the Okera Login Page to a preconfigured OAuth service provider (e.g. Google, Ping, etc.), enabling the user to login from the external OAuth service. Once logged in, the Web UI uses the ODAS REST API to exchange the resulting OAuth token for an Okera token to gain access to the Okera Web UI. The user can also then copy his or her token to use it for any Okera integration point.

Prerequisites to enable OAuth

You will need the following pieces of information about your OAuth service provider:

  • Client ID This is the OAuth client ID that the service provider requires for authenticating against Okera. OAuth service providers allow you to create new clients; as part of this, you will obtain a Client ID.
  • Authentication URI This is the URI that the OAuth service requires the user to be redirected to when requesting authentication. Typically, it renders an HTML login page for that service provider. Once the user has successfully interacted with this page, the user is redirect back to Okera with an ephemeral access code.
  • Token URI This is the URI that Okera must use to exchange the access code for a service provider token. This exchange happens in the REST API.
  • Client Secret This value is provided by the OAuth service provider as part of setting up a new client. It is required for Okera to establish trust when attempting the token exchange.
  • Redirect URIs This is a list of URIs that will be recognized as acceptable URIs to navigate to once the Authentication URI flow is over. These need to be configured in the OAuth service provider in the client configuration. Typically, this is just one URI: the location of the Okera Web UI’s login page, e.g. https://my-okera-host:8083/login. Note: the hostname of the URL should be static, either a static IP or static hostname value. The Okera Portal is assumed to have a single, static URL for a given cluster.
  • Origin URIs These URIs are the same as the Redirect URIs, without the /login part. For example https://my-okera-host:8083. These values also need to be configured in the OAuth service provider, so it will allow redirects from the Okera Web UI. Note: the hostname of the URL should be static, either a static IP or static hostname value. The Okera Portal is assumed to have a single, static URL for a given cluster.
  • OAuth Scopes (Optional) The scopes determine which information the OAuth service provider will allow the user to access once the token is obtained. Okera needs only very basic information, namely the subject (sub) in order to generate an Okera token. Typically, the default here (openid profile email). If there are other scopes required by your OAuth service provider to obtain the sub, you will need to set them.
  • Subject Endpoint (Optional) In some deployments, there may be a need to not encode the subject (sub) in the JWT response from the OAuth token exchange. In this case, Okera needs to know the endpoint to call to retrieve the subject, which is the unique user ID that Okera can use to generate the token. This endpoint is expected to return a JSON response with sub being a key on the top-level JSON object, e.g. {"sub": "abc123", ...}.

Setting up OAuth configurations

client_secrets.json

Once you have the above information, you will need to create a JSON file with this information encoded in it. The JSON file has the following form:

{
  "web": {
    "client_id": <Your Client ID>,
    "auth_uri": <Your Authentication URI>,
    "token_uri": <Your Token URI>,
    "client_secret": <Your Client Secret>,
    "redirect_uris": [<Your Redirect URIs>, ...],
    "javascript_origins": [<Your Origin URIs>, ...],
  }
}

For example, if Google OAuth were to be used, after setting up a new Google OAuth project, we might have the following file:

{
  "web": {
    "client_id": "example12345.apps.googleusercontent.com",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token",
    "client_secret": "very-secret",
    "redirect_uris": [
      "https://ec2-1234.compute.amazonaws.com:8083/login"
    ],
    "javascript_origins": [
      "https://ec2-1234.compute.amazonaws.com:8083"
    ]
  }
}

Save this file to /etc/okera/client_secrets.json on the same machine that the deployment manager runs. As part of cluster startup, this file will be copied to the Okera REST Server container.

Note /etc/okera/client_secrets.json must be configured and present before the cluster is started up from the Deployment Manager. If a value in this file needs to be changed, you will need to create a new cluster with the updated client_secrets.json file. If this is not possible, please reach out to Okera Support for guidance.

Environment variables

Okera looks for certain environment variables to be set in order to enable OAuth. In your /etc/okera/env.sh file, set the following environment variables:

  • OKERA_OAUTH_SECRETS, to /etc/okera/client_secrets.json, or wherever the client_secrets.json file is located. Setting this environment variable enables Okera OAuth.
  • OKERA_OAUTH_SCOPES (optional). Space-separated list of scopes required to obtain the sub. This is typically OK to leave unset, in which case the default is "openid profile email".

As an example, the OAuth part of your env.sh might look like this:

export OKERA_OAUTH_SECRETS="/etc/okera/client_secrets.json"
export OKERA_OAUTH_SCOPES="openid profile"

Verify OAuth

Once you’ve deployed Okera with OAuth enabled, verify that it’s working properly.

  • Check the OAuth connection using CURL: The following curl command should return the authentication URI (with client secrets as params) in the oauth_url section:

    $ curl <ODAS REST Server Host:Port>/api/info
    {
      ...,
      "oauth_url": "<your authentication URI plus client secrets params>"
    }
    

    For example:

    {
      "oauth_url": "https://accounts.google.com/o/oauth2/auth?scope=openid+profile+email&redirect_uri=.../login&response_type=code&client_id=abc123.apps.googleusercontent.com&access_type=offline"
    }
    

Use the Web UI

Navigate to the Okera Web UI and there should be a new login option on the login page: “Login with OAuth”. Upon clicking it, the UI should redirect to your OAuth service provider’s login screen. Upon successful login, the UI should redirect back to the Okera Web UI and log you in.

FAQ

Do the redirect_uris and javascript_origins need to be accessible by my OAuth Identity Provider?

No. OAuth Identity Providers do a simple string match against the referrer URI to determine authorization. For example, if Azure is your IdP, you can still use an internal IP address, internal hostname, or even localhost as a host for the Okera Portal, as long as the OAuth app in Azure is configured with that hostname.

Troubleshooting

If you encounter issues, look in the logs of the ODAS REST Server container, which will typically contain information about what went wrong.

  • Verify the JSON validity of client_secrets.json. If it is not well-formed, the ODAS REST Server cannot read it.
  • Ensure Okera information is probably configured in the OAuth service provider, e.g. Okera’s Web UI host:port is configured as a valid redirect URI, the scopes are valid, etc.
  • Be sure that the redirect_uris and javascript_origins are static so the cluster does not first need to be created in order for these values to be known. A static DNS hostname that can be pointed to the cluster IP once it is the recommend approach. Note: localhost works for dev environments.