Set Up Authentication Using OpenID Connect Identity Provider

GoodData uses OAuth 2.0 and OpenID Connect (OIDC) to handle authentication. It allows users to log in using their existing credentials from a variety of identity providers (IdPs), such as Okta or Auth0. GoodData integrates with the IdP to securely manage user authentication.

By default GoodData Cloud uses an Auth0 OIDC IdP. If you want to change the provider that your organization is using, follow these instructions:

  1. Ensure the OIDC IdP of your choice is supported.
  2. Set up your OAuth2 client.
  3. Update the OIDC settings of the organization.
  4. Map existing users to the organization, if there are any.

See Known limitations and Troubleshooting if you encounter any problems.

If you are using Amazon Cognito, or you just want to follow a worked example to help you set up your own OIDC IdP, see Use Amazon Cognito as Identity Provider.

Supported OIDC IdPs

Gooddata should support all OIDC IdPs that expose the OpenID configuration document.

To find out whether your preferred OIDC IdP exposes the OpenID configuration document, check whether you are able to reach the following URL:

https://<your_issuer_url>/.well-known/openid-configuration

Tested Providers

We have tested the following OIDC IdPs and confirmed they can be successfuly integrated with GoodData:

If the provider of your choice is not on this list, but it does expose the OpenID configuration document, you should still be able to successfuly integrate the provider with GoodData. If you are having difficulties, please contact us on our support or community portals.

Set up an OAuth2 Client

The exact procedure depends on the OAuth2 client that you are using. The generic steps are as follows.

Steps:

  1. Create an OAuth2 client with the following configuration:

    • Callback URL: https://<organization-hostname>/login/oauth2/code/<organization-hostname>
    • Grant types:
      • Implicit
      • Authorization code
      • Refresh token
    • Claims:
      • name
      • openid
      • profile
      • offline_access

  2. Ensure your OIDC IdP advertises end_session_endpoint at the https://<your-issuer-url>/.well-known/openid-configuration endpoint.

    This is required to support the logout action in GoodData. If your OIDC IdP supports CORS configuration, add the URL of the Organization’s endpoint URL to the configuration.

  3. When the OAuth2 client is created, continue on to the Update the OIDC Settings of the Organization guide to copy and store the following parameters:

    • The client ID
    • The client secret

Update the OIDC Settings of the Organization

Use the following template to create an API request for updating the OIDC settings of the Organization:

curl --request PUT \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/vnd.gooddata.api+json' \
  --data '{
  "data": {
    "id": "alpha",
    "type": "organization",
    "attributes": {
      "name": "Alpha Corp.",
      "hostname": "analytics.alpha.example.com",
      "oauthIssuerLocation": "https://<your-issuer-url>",
      "oauthClientId": "<your-client-id>",
      "oauthClientSecret": "<your-client-secret>"
    }
  }
}'  $HOST_URL/api/v1/entities/admin/organizations/alpha

Once you have updated the OIDC settings, map the users stored in the IdP to your organization.

Map Users to the Organization

For mapping, GoodData uses the sub claim. The value of the user sub claim supplied to you by the IdP you are using.

To map a user, submit a POST request to /api/v1/entities/users and provide the value of the sub claim in the authenticationId attribute in the API request body:

curl --request POST \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/vnd.gooddata.api+json' \
  --data '{
      "data": {
        "id": "john.doe",
        "type": "user",
        "attributes": {
          "authenticationId": "<user-sub-claim>"
        },
        "relationships": {
          "userGroups": {
            "data": [ {
              "id": "adminGroup",
              "type": "userGroup"
            } ]
          }
        }
      }
}' $HOST_URL/api/v1/entities/users

For further details on user and user-groups see Manage Users.

Known limitations

If you are using one of the following OIDC IdPs, make note of their limitations when used together with GoodData.

Auth0

Auth0 Issuer has a trailing slash in its configuration. When configuring the external OIDC provider for your organization, make sure that the oauthIssuerLocation value ends with a trailing slash, like https://mycompany.eu.auth0.com/. Otherwise, the authentication will not work.

Google

There is a known issue with the Google IdP that may prevent you from logging out.

Azure Active Directory

GoodData is not currently part of the Active Directory Marketplace, you will need to register it manually. To register GoodData with Azure Active Directory, we recommend you follow this guide.

Amazon Cognito

RP Initiated Logout does not work at the moment. We plan to implement the functionality in a future release.

Troubleshooting

Here are some common issues you may run into when using an OIDC, and how to address them.

Issues With Silent Login

If you block 3rd party cookies in your browser and the domain of GoodData is different from the domain of your application - most probably, a silent login will not work. You can fix that by putting GoodData on the same domain as your application (GoodData should be on a subdomain, for example, analytics.<your-domain>.com).

Also, if your application is running in a different domain than Identity Server, you can also have a problem with a silent login. It is possible to fix that by using Okta custom URL domain or Auth0 custom URL domain.

SalesForce

If you are using SalesForce as your OIDC provider, ensure that you have checked the Include Standard Claims option. Without this option, the provider will not provide the name claim in the ID token and the authentication will fail.

Include standard claims

Content Is blocked

When your user session times out, a session timeout overlay is displayed. When you click the Log in button some GoodData.CN users may get the following error message:

This content is blocked. Contact the site owner to fix the issue.

There is no easy fix available to Auth0 users at the moment. We have temporarily extended the inactivity timeout to 3 days and the required re-login to 7 days, for Auth0, to minimize the chances of this issue occuring.

If you are using a different OIDC, such as Okta or Cloud IAM, you can fix this issue by creating CSP directives to allow the blocked content from your OIDC IdP. Ensure you have the following CSP directives configured:

curl -X POST -H "Authorization: Bearer <token>" \
    -H "Content-type: application/vnd.gooddata.api+json" $HOST_URL/api/v1/entities/cspDirectives \
    -d @data.json

where data.json contains the CSP directive allowing frame-src content from your OIDC IdP:

{
    "data": {
        "id": "frame-src",
        "type": "cspDirective",
        "attributes": {
            "sources": [
                "<oidc-provider-hostname>",
                "'self'"
            ]
        }
    }
}

Replace the <oidc-provider-hostname> with an appropriate URL. For example:

  • *.okta.com for Okta
  • accounts.google.com for Google
Example: Using Amazon Cognito