Authentication in GoodData Cloud

In this article, I will summarize the authentication methods in GoodData Cloud and what are the future plans. Also, I will show a simple example of how to set up Auth0 as an OpenID Connect (OIDC) provider with GoodData Cloud.

When your GoodData Cloud environment is provisioned, by default it is created with one user in our Auth0 Identity provider. For proper user management, we assume that you will be using your own OIDC provider. Setting up authentication and supported Identity providers can be found on the following help page.

GoodData Cloud uses OAuth 2.0 and OIDC protocol standard to handle authentication. OAuth 2.0 is an authorization framework that enables websites or applications access to resources hosted on another web application on behalf of a user. OIDC protocol is an identity layer built on top of OAuth 2.0 and handles authentication (to identify who the user is).

Tokens are used during the authentication flow to establish a login session and the tokens are in JSON Web format (JWT). In GoodData Cloud, we use the authorization code flow, and the following tokens are used:

• Access Token: Provides authorized access to a resource on behalf of the user and is usually short-lived.
• Refresh Token (if enabled in your Identity provider): Used to renew the access token if the access token expires and is usually long-lived.
• ID Token: Provides information about a user (e-mail, first name, last name, etc.)

The authentication flow is done through a series of HTTP redirects and requested tokens are encrypted and stored in a browser as cookies. Here is the simplified authentication flow:

1. The user is not logged in.
2. The client (browser) calls the backend resource and gets 401 (no existing session).
3. The client calls a login to the application backend (/appLogin).
4. The backend requests authorization code from an Identity provider.
5. The identity provider authenticates the user and provides the authorization code to the application backend.
6. The application backend uses authorization code to issue ID, Access, and Refresh tokens from the identity provider.
7. The application backend tries to find a user based on the ID token.
8. The tokens are encrypted and saved as cookies in a browser, creating a login session.
9. The client calls a backend resource and gets the authenticated result.

For additional details, visit the following help page.

Example of setting up Auth0 as OIDC provider with GoodData Cloud

Generally, the below steps need to be followed when setting up authentication with your OIDC provider.

• Make sure your Identity provider supports OIDC authentication.
• Create an OIDC application in your Identity provider.
• Generate and save API authentication token in your GoodData Cloud environment.
• Update the OIDC setting in your GoodData Cloud environment.
• Map users to the new OIDC provider.

Step 1: Create a new application in Auth0.

Create the application as a “Regular Web Application”

Note the Domain, Client ID, and Client Secret fields, as they will be used later to update the OIDC settings in GoodData.

Fill in Allowed Callback URLs according to the following format:

https://<organization-hostname>/login/oauth2/code/<organization-hostname>

and Allowed Logout URLs with your organization hostname.

Step 2: Generate and save API token for your GoodData Cloud

Review the following help page on how to create an API token.

Step 3: Update the OIDC setting of the organization via API.

Use the following API call to update the OIDC setting of your organization.

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

Where id is the identifier of your GoodData Cloud organization, and you will obtain it in the welcome email or if you call GET current organization info API. Values for oauthIssuerLocation, oauthClientId, and oauthClientSecret can be found in Auth0 Application settings as mentioned previously.

Note:

Auth0 has a trailing slash “/” in the configuration, make sure you include it at the end of the oauthIssuerLocation URL, e.g., https://test.us.auth0.com/. Not including the trailing slash at the end of the URL will result in an error, and you’ll be unable to log in.

Step 4: Map existing users to the Auth0 provider

Use the following API call to map existing users to the new OIDC provider.

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

Value for authenticationId for the user is user_ID in the User Management section in Auth0.

Now you should be able to log in with Auth0 as an OIDC provider. When you visit your GoodData Cloud environment and you have no existing login session, you will be redirected to the Auth0 login page. After providing valid credentials, you’ll be redirected back and logged in to your GoodData Cloud.

For additional details about authentication, visit the following help page.

Using GoodData default Identity provider (Auth0)

If you are not planning to use your own OIDC Identity provider, you can use our own default Identity provider (Auth0) with MANAGED_OIDC entitlement.

This feature will enable you to invite other users through the application UI or via API but it is limited to 100 users in total. Every user is initially created with admin permission (the permission can be updated afterwards), and you won’t be able to switch to your OIDC Identity provider as long as the entitlement is active. To enable or disable the MANAGED_OIDC feature, please reach out to our support.

Authentication using an injected API token

If you are embedding GoodData Cloud analytics into your application, there is an option to use injected API tokens as an authentication method.

Important note:

Using token authentication in a production environment can lead to some security issues, such as unintentionally exposing your token to someone else. We strongly recommend using context deferred authentication for UI applications.

API token authentication is supported in iFrame embedding and GoodData.UI SDK. For additional details consult the following help pages for Iframe and GoodData.UI.

JSON Web Token (JWT) authentication

You can use a JSON Web Token (JWT) to authenticate with GoodData as an alternative to OpenID Connect. JWTs provide a more modern alternative to simple API access tokens by enabling security features such as expiration time and tamper-proofing. JWT is an open standard according to the RFC-7519 that defines the secure transmission of information between parties.

See the Set Up Authentication Using JSON Web Tokens section of our documentation for further details.

Multiple OIDC providers

You can set up specific OIDC providers to be supported in your organization. Whether your company uses different providers or your tenants want to use their own, the Multiple OIDC (MOIDC) feature makes it possible. It allows users to access GoodData using their external identity provider credentials (also known as identity federation), eliminating the need for separate credentials.

See the Multiple OIDCs section of our documentation for further details.