OAuth 2.0 identity providers#

Starburst Enterprise platform (SEP) includes support for OAuth 2.0 authentication. The following sections provide information about configuring and using the supported identity providers.

All OAuth 2.0 implementations require oauth2 to be included in the values set for the http-server.authentication.type configuration property in the config.properties file on the coordinator in addition to other configuration properties described in this document.

OpenID Connect metadata#

OpenID Connect servers publish their metadata at a well-known URL, typically https://authorization-server.com/.well-known/openid-configuration. The data returned by this endpoint is used to configure OAuth 2.0 authentication.

Warning

If the authorization server is issuing JSON Web Tokens (JWTs) and the metadata document contains userinfo_endpoint, SEP uses this endpoint to check the validity of OAuth2 access tokens. Since JWTs can be inspected locally, using them against userinfo_endpoint may result in authentication failure. In this case, set the http-server.authentication.oauth2.oidc.use-userinfo-endpoint configuration property to false (http-server.authentication.oauth2.oidc.use-userinfo-endpoint=false). This instructs SEP to ignore userinfo_endpoint and inspect tokens locally.

For more information on OpenID, refer to OpenID Connect.

Supported identity providers#

The following sections detail the necessary configuration steps in each of the supported identity provider’s user interface and in the config.properties file on the SEP coordinator. The following identity providers are supported:

Okta#

This section provides specific information for setting up OAuth 2.0 for SEP in Okta. There are two tasks to complete:

  • Create an Okta app

  • Configure the client

The following sections describe the steps to complete these tasks.

Create an Okta app#

If you are using an existing app integration you can skip this step, referring to it only as a guideline on where to obtain the required information.

  1. In the Okta Admin Console, create an Okta app integration.

  2. Enter the OAuth 2.0 authentication callback URL https://<sep-coordinator-domain-name>/oauth2/callback for Redirect URI.

Configure the client#

  1. In the General tab of the Okta Admin Console, click the Client Credentials section and copy the Client ID.

  2. Set the http-server.authentication.oauth2.client-id property in the config.properties file on the coordinator to the Client ID displayed in the Client Credentials section:

http-server.authentication.oauth2.client-id=<Client ID displayed in Okta Admin Console>

  1. In the General tab of the Okta Admin Console, click the Client Credentials section and copy the Client secret.

  2. Set the http-server.authentication.oauth2.client-secret property in the config.properties file on the coordinator to the Client Secret displayed in the Client Credentials section:

http-server.authentication.oauth2.client-secret=<Client Secret displayed in Okta Admin Console>

  1. In the Okta Admin Console, go to Security > API > Authorization Servers. Choose the authorization server for your application under Name, and copy the Issuer URL.

  2. Set the http-server.authentication.oauth2.issuer property in the config.properties file on the coordinator to the Issuer URL value:

http-server.authentication.oauth2.issuer=https://example-account.okta.com/oauth2/default

  1. In the Okta Admin UI, copy the Audience and use it to set the http-server.authentication.oauth2.additional-audiences property in the config.properties file on the coordinator:

http-server.authentication.oauth2.additional-audiences=<Audience displayed in Okta Admin Console>

Configuration properties values summary#

The following table describes all configuration properties available to configure SEP with OAuth 2.0 through Okta, and their values or source of the values:

Okta configuration properties#

Property

Value

http-server.authentication.oauth2.additional-audiences

As copied from Audience displayed in the Okta Admin Console

http-server.authentication.oauth2.client-id

As copied from Client ID displayed in the Okta Admin Console

http-server.authentication.oauth2.client-secret

As copied from Client Server displayed in the Okta Admin Console

http-server.authentication.oauth2.issuer

As copied from Issuer displayed in the Okta Admin Console

http-server.authentication.oauth2.principal-field

sub

Azure Active Directory#

This section provides specific information for setting up OAuth 2.0 for SEP in Azure. There are several tasks to complete:

  • Create an Azure AD app integration

  • Expose the API

  • Configure the client

  • Configure passthrough authentication settings (optional)

  • Configure endpoint properties

The following sections describe the steps to complete these tasks.

Create an Azure AD app integration#

Skip this step if you use an existing app registration.

  1. Go to Microsoft Azure Portal > Azure Active Directory > App registrations > New registration.

  2. Enter a name, for example sep-app-01, and choose Accounts in this organizational directory only (Starburst Data only - Single tenant) from Supported account types. This is needed in a later step.

  3. For Redirect URI use Web and the OAuth 2.0 authentication callback URL https://<sep-coordinator-domain-name>/oauth2/callback.

  4. Click Register.

Expose the API#

By default Microsoft only adds the API for Microsoft Graph to an app registration. You must also expose an API for SEP:

  1. Go to Expose an API and click Set next to Application ID URI. The Application ID URI must be unique within your organization and match the URL of your SEP cluster. For example: https://example.com/d858d980d-71d5-4e86-8da8-5ea4cab5a8e1.

  2. Select Add a scope in the Scopes defined by this API section.

  3. Add a Name for the new scope such as SEPUsers.Read.All, as well as a Display name and Description. Name is used to configure the scope on the coordinator.

  4. Choose Admins and users from the Who can consent? selector.

  5. Click Add a client application in the Authorized client applications. Use the client ID and select the new scope.

  6. Configure http-server.authentication.oauth2.scopes in the config.properties file on the coordinator as a comma-separated list including the scope URL and openid:

http-server.authentication.oauth2.scopes=https://example.com/d858d999d-71d5-4e96-8da9-5ea4c999a8e1/SEPUsers.Read.All,openid

Configure the client#

Once the app integration is added and the API is exposed, the client is configured in the Azure Portal:

  1. Go to Certificates & secrets and select New client secret.

  2. Enter description and set an expiration period.

  3. Copy the value of the secret to and set http-server.authentication.oauth2.client-secret in the config.properties file on the coordinator to that value:

http-server.authentication.oauth2.client-secret=<Client Secret displayed in Azure Portal>

  1. Go to API permissions > Add a permission. Do the following, in the order shown:

    • Select My APIs at the top.

    • In the list of app registrations, click on the name you entered for your app registration, sep-app-01 in this example.

    • Check the box for Delegated permissions.

    • Check the box for the scope you created earlier (for example, SEPUsers.Read.All)

    • Click the Add permission button.

  2. Go to Overview > Application (client) ID, and use the content to configure http-server.authentication.oauth2.client-id on the coordinator.

  3. Set the http-server.authentication.oauth2.access-token-issuer property in the config.properties file on the coordinator to https://sts.windows.net/<your-tenant-id>/. The trailing forward slash is a required part of the URL.

http-server.authentication.oauth2.access-token-issuer=https://sts.windows.net/9ac99957-7c90-4d4f-9993-d8a199928c05/

  1. Set the http-server.authentication.oauth2.principal-field property in the config.properties file on the coordinator to upn.

http-server.authentication.oauth2.principal-field=upn

Configure passthrough authentication settings#

Skip this step unless you are implementing passthrough authentication.

  1. To configure Azure AD OAuth2 passthrough authentication, click API permissions > Add a permission again, and do the following, in the order shown:

    • Ensure that Microsoft APIs is selected at the top.

    • Select Azure Storage from the list of applications.

    • Check the box for Delegated permissions.

    • Check the box for user_impersonation.

    • Click the Add permission button.

  2. In the Authentication section, the following options must be checked as appropriate for your environment:

    • Access tokens - Used for implicit flows

    • ID tokens - Used for implicit and hybrid flows

  3. If you are using passthrough authentication, you must set the http-server.authentication.oauth2.additional-audiences property in the config.properties file on the coordinator as a comma separated list with https://storage.azure.com and the URL of your SEP coordinator:

http-server.authentication.oauth2.additional-audiences=https://storage.azure.com,https://sep-app-01.example.com

  1. Set the http-server.authentication.type in the config.properties file on the coordinator as follows:

http-server.authentication.type=delegated-oauth2

  1. Once the authentication type is set to delegated-oauth2, you must change the http-server.authentication.oauth2.scopes configuration property in the config.properties file on the coordinator as follows:

http-server.authentication.oauth2.scopes=https://storage.azure.com/user_impersonation,openid

Note

For delegated-oauth2 you do not set your own scope.

Configure endpoint properties#

  1. Go to Overview > Endpoints.

  2. Navigate to the OpenID Connect metadata document.

  3. Find the issuer field and use its value to set the http-server.authentication.oauth2.issuer configuration property in the config.properties file on the coordinator. For example:

http-server.authentication.oauth2.issuer=https://login.microsoftonline.com/9ac99957-7c90-4d4f-9993-d8a199928c05/v2.0

Warning

Azure AD does not return access_token_issuer in OpenID Connect Metadata document the provider metadata.

Access tokens in JWT format use a different issuer.

Configure the groups field#

The System for Cross-domain Identity Management (SCIM) protocol synchronizes information about users and groups with external providers such as Azure AD. For more information about SCIM, see SCIM user and group synchronization.

Note

The Azure group name is not used. The field is populated with the Object IDs of the groups to which the user belongs.

Configuration properties values summary#

The following table describes all configuration properties available to configure SEP with OAuth 2.0 through Azure, and their values or source of the the values. Identifiers shown are for purposes of example only.

Azure configuration properties#

Property

Value examples

http-server.authentication.oauth2.client-id

As copied from Overview > Application (client) ID in the Azure Portal

http-server.authentication.oauth2.client-secret

As copied from Certificates & secrets in the Azure Portal

http-server.authentication.oauth2.issuer

https://login.microsoftonline.com/9ac99957-7c90-4d4f-9993-d8a199928c05/v2.0

http-server.authentication.oauth2.scopes

https://organization.com/d858d999d-71d5-4e96-8da9-5ea4c999a8e1/<scopename>,openid

http-server.authentication.oauth2.additional-audiences

https://storage.azure.com,https://sep-app-01.example.com

http-server.authentication.oauth2.access-token-issuer

https://sts.windows.net/9ac99957-7c90-4d4f-9993-d8a199928c05/

http-server.authentication.oauth2.principal-field

upn

Active Directory Federation Services#

OAuth 2.0 can be implemented for SEP in organizations using Active Directory Federation services (ADFS). There are two tasks to complete:

  • Create an ADFS application group

  • Configure the client

The following sections describe the steps to complete these tasks.

Create an ADFS Application Group#

If you are using an existing ADFS application group you skip this step, referring to it only as a guideline on where to obtain the required information.

  1. Open the ADFS administrative UI.

  2. Choose Application Groups > Add Application Group.

  3. Specify a name for your application group, for example sep-app-group, and use the Server application template.

  4. Enter the OAuth 2.0 authentication callback URL https://<sep-coordinator-domain-name>/oauth2/callback for Redirect URI.

  5. Set the http-server.authentication.oauth2.client-id property in the config.properties file on the coordinator to the Client ID for the application group displayed in the ADFS Administrative UI:

http-server.authentication.oauth2.client-id=<Client ID displayed in the ADFS administrative UI>

  1. In the ADFS administrative UI, select Configure Application Credentials > Generate a shared secret.

  2. Set the http-server.authentication.oauth2.client-secret property in the config.properties file on the coordinator to the Client Secret displayed in the ADFS administrative UI:

http-server.authentication.oauth2.client-secret=<Client Secret displayed in ADFS administrative UI>

Configure the client#

  1. In the ADFS administrative UI, go to Service > Endpoints.

  2. Click OpenID Connect Discovery. Use the metadata to configure http-server.authentication.oauth2.issuer in the config.properties file on the coordinator.

  3. Set the http-server.authentication.oauth2.scopes property in the config.properties file on the coordinator to the following:

http-server.authentication.oauth2.scopes=openid

  1. Set the http-server.authentication.oauth2.additional-audiences property in the config.properties file on the coordinator to the following:

http-server.authentication.oauth2.additional-audiences=urn:microsoft:userinfo

Configuration properties values summary#

The following table describes all configuration properties available to configure SEP with OAuth 2.0 through ADFS, and their values or source of the values:

ADFS configuration properties#

Property

Value

http-server.authentication.oauth2.additional-audiences

urn:microsoft:userinfo

http-server.authentication.oauth2.client-id

As copied from Client ID displayed in the ADFS Administrative Console

http-server.authentication.oauth2.client-secret

As copied from Client Secret displayed in the ADFS Administrative Console

http-server.authentication.oauth2.issuer

As copied from the OpenID metadata endpoint

http-server.authentication.oauth2.scopes

openid

Keycloak#

This section provides specific information for setting up OAuth 2.0 for SEP using Keycloak.

There are two tasks to complete:

  • Create application

  • Configure the client

The following sections describe the steps to complete these tasks.

Create application#

Use your existing realm, for example myrealm where your Keycloak instance is configured to run on https://example.com. The base Keycloak URL to use with the configuration properties in the this section becomes https://example.com/auth/realms/myrealm.

  1. In the Keycloak administrative UI, select your realm, and click Configure > Clients > Create.

  2. Provide a meaningful name for the SEP application in the Client ID field, such as starburst-sep.

  3. Set the Access Type field to confidential.

  4. Set the Client Protocol field to openid-connect.

  5. Click Save, then click Save again.

  6. Open the Credentials tab to view the values for Client ID and Secret needed to configure the client.

  7. In the Redirect URIs field, enter the OAuth 2.0 authentication SEP callback URL, https://<sep-coordinator-domain-name>/oauth2/callback.

Configure the client#

  1. Set the http-server.authentication.oauth2.client-id property in the config.properties file on the coordinator to the Client ID displayed in Keycloak:

http-server.authentication.oauth2.client-id=<Client ID displayed in Keycloak UI>

  1. Set the http-server.authentication.oauth2.client-secret property in the config.properties file on the coordinator to the Client Secret displayed in the Keycloak Credentials tab:

http-server.authentication.oauth2.client-secret=<Client Secret displayed in Keycloak UI>

  1. Set the http-server.authentication.oauth2.issuer property in the config.properties file on the coordinator to your realm’s base Keycloak URL:

http-server.authentication.oauth2.issuer=<base Keycloak URL for your realm>

  1. Set the http-server.authentication.oauth2.scopes property in the config.properties file on the coordinator to the following:

http-server.authentication.oauth2.scopes=openid

Configuration properties values summary#

The following table describes all configuration properties available to configure SEP with OAuth 2.0 through Keycloak:

Keycloak configuration properties#

Property

Value

http-server.authentication.oauth2.client-id

Client ID from Keycloak

http-server.authentication.oauth2.client-secret

Client secret from Keycloak. Note: Only clients with access type set to Confidential and at least one Valid Redirect URIs set has secrets.

http-server.authentication.oauth2.issuer

{baseURL}

http-server.authentication.oauth2.scopes

openid

Google Cloud Platform#

This section provides specific information for setting up OAuth 2.0 for SEP in Google cloud Platform (GCP).

There are two tasks to complete:

  • Create application

  • Configure the client

The following sections describe the steps to complete these tasks.

Create application#

  1. In Google Cloud Platform open APIs & Services > Credentials.

  2. Click + CREATE CREDENTIALS and OAuth client ID > Web application.

  3. Provide a meaningful name for the SEP application.

  4. In the Authorized redirect URIs, enter the OAuth 2.0 authentication SEP callback URL, https://<sep-coordinator-domain-name>/oauth2/callback.

Configure the client#

  1. Set the http-server.authentication.oauth2.client-id property in the config.properties file on the coordinator to the Client ID displayed in GCP:

http-server.authentication.oauth2.client-id=<Client ID displayed in GCP UI>

  1. Set the http-server.authentication.oauth2.client-secret property in the config.properties file on the coordinator to the Client Secret displayed in GCP:

http-server.authentication.oauth2.client-secret=<Client Secret displayed in GCP UI>

  1. Set the properties on the coordinator in the config.properties file:

http-server.authentication.oauth2.issuer=https://accounts.google.com
http-server.authentication.oauth2.principal-field=email
http-server.authentication.oauth2.scopes=openid,https://www.googleapis.com/auth/userinfo.email
http-server.authentication.oauth2.userinfo-url=https://openidconnect.googleapis.com/v1/userinfo

Configuration properties values summary#

The following table describes all configuration properties available to configure SEP with OAuth 2.0 on GCP, and their values or source of the values:

Google configuration properties#

Property

Value

http-server.authentication.oauth2.authentication-type

oauth2

http-server.authentication.oauth2.client-id

As copied from Client ID displayed in the GCP UI

http-server.authentication.oauth2.client-secret

As copied from Client Server displayed in the GCP UI

http-server.authentication.oauth2.issuer

https://accounts.google.com

http-server.authentication.oauth2.principal-field

email

http-server.authentication.oauth2.scopes

openid,https://www.googleapis.com/auth/userinfo.email

http-server.authentication.oauth2.userinfo-url

https://openidconnect.googleapis.com/v1/userinfo

http-server.authentication.oauth2.auth-url

https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&  prompt=consent. Only required for refresh tokens.

For more information on Google APIs and OAuth 2.0, refer to Using OAuth 2.0 to Access Google APIs.

PingIdentity#

This section provides specific information for setting up OAuth 2.0 for SEP in PingIdentity (PingID). There are two tasks to complete:

  • Create an OIDC application

  • Configure the client

The following sections describe the steps to complete these tasks.

Create an OIDC application#

In PingIdentity, follow these steps:

  1. In the Applications menu, create a new application using the OpenID Connect protocol.

  2. Configure the following on the Configuration tab of the new application:

    • Grant type: Authorization Code

    • Redirect URI: https://<sep-coordinator-domain-name>/oauth2/callback

  3. Collect the Issuer, Client ID, and Client Secret values to be used later in configuration.

  4. In the Attributes tab, create a custom attribute that maps the sub attribute to the PingOne Username mapping with the openid scope.

Configure the client#

  1. Set the http-server.authentication.oauth2.client-id property in the config.properties file on the coordinator to the Client ID displayed in PingIdentity:

http-server.authentication.oauth2.client-id=<client ID>

  1. Set the http-server.authentication.oauth2.client-secret property in the config.properties file on the coordinator to the Client Secret displayed in PingIdentity:

http-server.authentication.oauth2.client-secret=<client secret>

  1. Set the http-server.authentication.oauth2.issuer property in the config.properties file on the coordinator to the Issuer URL displayed in PingIdentity:

http-server.authentication.oauth2.issuer=<issuer URL>

Configuration properties values summary#

The following table describes all configuration properties available to configure SEP with OAuth 2.0 through PingIdentity:

PingIdentity configuration properties#

Property

Value

http-server.authentication.oauth2.client-id

Client ID from PingIdentity

http-server.authentication.oauth2.client-secret

Client secret from PingIdentity

http-server.authentication.oauth2.issuer

Issuer URL from PingIdentity

Enable OAuth for Power BI clients#

In order for users to authenticate with OAuth SEP using Microsoft Power BI, you must do the following:

  1. Add the http-server.authentication.oauth2.public-client-id property to your SEP coordinator node’s config.properties file, and set its value to the the PKCE client ID as registered in your OAuth provider.

  2. Set your OAuth provider’s redirect_uri to https://oauth.powerbi.com/views/oauthredirect.html.