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:

• Auth0
• Okta
• Amazon Cognito - see example setup
• Azure Active Directory
• Cloud IAM
• Keycloak
• PingOne

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>
   • Flows:
     • Authorization Code
   • Scopes:
     • openid
     • profile
     • (optional) offline_access
   • Claims:
     • sub
     • name
     • nonce
   • Endpoints:
     • /.well-known/openid-configuration
     • authorization_endpoint
     • jwks_uri
     • token_endpoint
     • userinfo_endpoint

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. We recommend that you configure your OIDC IdP to issue a refresh token. This will prevent users from having to manually reauthenticate frequently.

   If you are using a refresh token, ensure that it is set to be reusable for at least 10 times. The GoodData backend may generate multiple API calls at the same time, which may require the same refresh token to be used several times.

4. 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 make an API request to update the OIDC settings for your 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",
      "oauthSubjectIdClaim": "sub",
      "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

When it comes to mapping users to an organization, you can choose from the following two methods:

• API-based user provisioning is robust, offering precise control over user management processes. Organizations can automate the creation, update, and deletion of user accounts, making it ideal for complex user management scenarios.

• Just-In-Time (JIT) user provisioning is very flexible. It allows users to be created and updated dynamically at the time of login, based on the information provided by an identity provider. This method provides an effortless and immediate way to onboard users, making it ideal for enhancing user experience and reducing overhead.

For mapping, GoodData uses the sub claim. The value of a user’s sub claim is provided by your OIDC IdP.

API-Based Provisioning

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.

Just-In-Time (JIT) User Provisioning

JIT provisioning automates the creation and updating of user accounts at the very moment a user attempts to log in. Here is an example of how it works:

1. First Login Attempt: A new user wants to access GoodData for project analytics. They open GoodData and are redirected to log in via their company’s OIDC provider.
2. Authentication: The user logs in using their company credentials. The OIDC provider sends the user’s attributes (claims) back to GoodData as a part of the OAuth authentication token. GoodData recognizes the access of a new user, as their authentication ID (sub-claim) does not exist in our database, and initiates JIT provisioning.
3. Seamless Account Creation: The user is immediately taken to their GoodData dashboard. Meanwhile, their account has just been created in the background.
4. Regular Updates: Each time the user logs in after that, any changes in their details are automatically updated in GoodData.

Setting Up JIT User Provisioning

Follow these simple steps to set up JIT user provisioning:

1. Configure Your Authentication Provider: Make sure your authentication provider supports the following scopes:

   • openId
   • profile
   • email
   • urn.gooddata.scope/user_groups (GoodData-specific scope for user group memberships)

   These scopes will allow us to obtain the following claims for user provisioning:

   • sub (Subject, the user’s identifier)
   • given_name, family_name
   • email
   • urn.gooddata.user_groups (GoodData-specific claim for user group memberships. To remove a user from groups, include this claim with an empty list. If omitted, group memberships won’t change. Even though this claim is not mandatory, the corresponding scope is still requested in each authentication request and, therefore, has to be correctly configured.)

2. Enable JIT Provisioning: After updating your provider configuration, enable JIT provisioning at the organization level using the organization API. Set the jitEnabled attribute to true.

JIT ID Token Example

When set up correctly, the ID token payload will look like this:

{
  "sub": "<Subject - Identifier for the end-user at the issuer>",
  "name": "User Name",
  "given_name": "User",
  "family_name": "Name",
  "email": "user.name@gooddata.com",
  "ver": 1,
  "iss": "https://issuer/oauth2/default",
  "aud": "<aud>",
  "iat": 1234567890,
  "exp": 1234567890,
  "jti": "ID.example",
  "amr": ["pwd"],
  "idp": "<idp>",
  "nonce": "nonce",
  "preferred_username": "user.name@gooddata.com",
  "auth_time": 1000,
  "at_hash": "preview_at_hash",
  "urn.gooddata.user_groups": [
    "userGroupA",
    "userGroupB",
    "adminUserGroup"
  ]
}

If your provider does not support lists as token attribute values, the urn.gooddata.user_groups attribute can also be specified as a comma-separated string:

urn.gooddata.user_groups: "userGroupA,userGroupB,adminUserGroup"

Logout

To handle logouts in GoodData, invoke the API endpoint https://<your_subdomain>.cloud.gooddata.com/logout.

The specific setting for enabling the logout call may vary depending on the OIDC provider you are using. Look for an option to set the logout endpoint.

Failing to call this endpoint may result in incomplete or inconsistent logout states.

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.

There is a known issue where users the Auth0 logout procedure does not work if you are using Auth0 and GoodData with a custom domain. We are working on delivering a fix for this issue.

Google

Google IdP does not support custom scopes, so Just-In-Time provisioning cannot be used with Google.

Additionally, a known issue with Google IdP may prevent successful logout.

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.

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