OAuth

ODAS 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 will be able to accept an OAuth code token and exchange 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 (e.g. Google, Ping, etc.), enabling the user to login from the external OAuth service.

Configuration Settings

The following configuration settings are used to configure OAuth support:

  • OKERA_OAUTH_SECRETS
  • OKERA_OAUTH_SCOPES

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

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

Note

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

Note

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, ODAS 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 ODAS configuration file:

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

You can then update your cluster by running okctl update.

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