Authenticate Using Open Authorization (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.
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.
The following configuration settings are used to configure OAuth support:
OAUTH_PROVIDER: google(required if you are using Google OAuth, but otherwise, not required).
Configuring OAuth Authentication¶
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.
- 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.
- 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.
- Token URI - this is the URI that Okera must use to exchange the
access codefor a identity provider
- 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.
- 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.
- Origin URIs - this is a list of URIs are the same as the Redirect URIs, without the
/loginpart. 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.
- 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.
- 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: googlein 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
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¶
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 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
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
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:
For example, if Google OAuth were to be used, after setting up a new Google OAuth project, we might have the following file:
Put this file in some location (e.g.
/etc/okera/client_secrets.json), and then add the following to your Okera configuration file:
You can then update your cluster by running
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.
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