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 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.
The following configuration settings are used to configure OAuth support:
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
- 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.
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
While all Identity Providers will require the Redirect URI, not all will 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 ODAS 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