Skip to content

Authenticate Using Open Authorization (OAuth)

Okera supports enabling OAuth for authenticating to the Web UI. 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 Web UI with basic OAuth integration, the REST API accepts an OAuth code token and exchanges it for an OAuth access token automatically. This allows the Web UI to redirect an Okera user from the Okera login page to a pre-configured OAuth service provider (for example, Google or Ping), enabling the user to login from the external OAuth service.

Okera recommends that you configure OAuth integration using a JSON Web Key Set (JWKS) endpoint. The endpoint is used to dynamically fetch the appropriate public key needed for OAuth authentication from the JWKS content supplied by OAuth services. See Configuring the JWKS Endpoint.

Configuration Settings

The following configuration settings are used to configure OAuth support:

  • OAUTH_PROVIDER: google (required if you are using Google OAuth, but otherwise, not required).
  • OAUTH_SECRETS
  • OAUTH_SCOPES
  • JWT_JWKS_URL

Configuring OAuth Authentication

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

  1. 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.
  2. 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.
  3. 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.
  4. Token URI - this is the URI that Okera must use to exchange the access code for a identity provider access token.
  5. URL of your OAuth identity provider - this is the URL Okera uses to fetch the appropriate public key needed for OAuth authentication from the JWKS content supplied by OAuth services.
  6. 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 login page, e.g. https://my-okera-host:8083/login.
  7. Origin URIs - this is a list of 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 calls from the Okera Web UI.
  8. Optional: OAuth Scopes - this list of scopes determines which information the OAuth service provider will allow the user to access once the token is obtained. It is specified in the configuration file. For example, OAUTH_SCOPES: openid profile email api://<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx>/okera/okera_auth_scope.
  9. Optional: OAuth Provider -- this must be specified if you are using Google OAuth. It should not be specified if you are not using Google OAuth. Specify OAUTH_PROVIDER: google in the configuration file. If you are using Google OAuth and do not specify this setting, OAuth will fail. The only valid value for this configuration setting (other than no value) is google.

Configuring the Client ID, Client Secret and Token URI

These values are typically provided by your Identity Provider (e.g. Google, Ping, GitHub, Azure AD, etc) when you create an OAuth registration.

Configuring the JWKS Endpoint

Use the JWT_JWKS_URL configuration setting to specify the URL of your OAuth identity provider (for example, Okta, Auth0, AzureAD, etc). Okera uses this JWKS endpoint to dynamically fetch the appropriate public key needed for OAuth authentication from the JWKS content supplied by OAuth services. See Configuration.

Configuring the Redirect and Origin URIs

OAuth requires a known list of URIs that are allowed to initiative OAuth requests and can serve as redirect targets as part of the OAuth flow. These values need to be configured in your OAuth Identity Provider (e.g. Google, Ping, GitHub, Azure AD, etc), and their values are derived from the URIs you access the Okera Web UI.

For example, if you access the Web UI at https://okera.company.com:8083, then the Redirect URI will be https://okera.company.com:8083/login and the Origin URI will be https://okera.company.com:8083.

Notes: While all Identity Providers require the Redirect URI, not all require an Origin URI.

The URIs must match the URI on which you are accessing the Web UI from, and cannot be dynamic. As such, it is recommended you configure a static DNS entry on which to access the Web UI.

Creating and Using the client_secrets.json File

Since the OAuth configuration has many values, Okera accepts the configuration for it as a JSON file that contains all this information.

The format of the file is:

{
  "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"
    ]
  }
}

Put this file in some location (e.g. /etc/okera/client_secrets.json), and then add the following to your Okera configuration file:

OAUTH_SECRETS: file:///etc/okera/client_secrets.json

You can then update your cluster using your Okera Helm chart.

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 Identity Provider, you can still use an internal IP address, internal hostname, or even localhost as a host for the Okera UI, as long as the OAuth app in Azure is configured with that hostname.

Troubleshooting

If you encounter issues, look in the logs of the Okera 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 Okera REST Server cannot read it.
  • Ensure Okera information is properly configured in the OAuth identity 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.