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:
- Ensure the OIDC IdP of your choice is supported.
- Set up your OAuth2 client.
- Update the OIDC settings of the organization.
- 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.
GoodData Trial Limitation
The trial version of GoodData Cloud is limited to only use the Auth0 OIDC IdP. This is enforced by the ManagedOIDC
entitlement, see View Entitlements.
If you wish to change the OIDC IdP your trial environment is using, contact us on our community portal.
Set up an OAuth2 Client
The exact procedure depends on the OAuth2 client that you are using. The generic steps are as follows.
Steps:
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
- Callback URL:
Ensure your OIDC IdP advertises
end_session_endpoint
at thehttps://<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.
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.
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
Defining the oauthIssuerLocation Parameter
Ensure the oauthIssuerLocation URL Matches Exactly
Pay extra attention to the URL that you provide in the oauthIssuerLocation
parameter. You must specify this URL exactly as it is provided by the OIDC IdP. For example, if the URL provided ends with a trailing slash, keep the slash when passing the URL to the API as a value of the oauthIssuerLocation
parameter.
Microsoft Azure and oauthIssuerLocation
For Microsoft Azure, the oauthIssuerLocation
parameter looks different than for other providers. Normally, you would get the issuer location from https://<your_issuer_url>/.well-known/openid-configuration
, but for Azure B2C, you need to use the direct link, i.e. https://<your_issuer_url>
without /.well-known/openid-configuration
.
Configurable Claim Mapping for AuthenticationId
By default, the user claim is set to sub
. You can change the value of the attribute oauthSubjectIdClaim
to use a different claim, provided it is part of the ID token sent to GoodData.
For example, if you are using Azure Active Directory as your OIDC provider, ensure that you change the value of oauthSubjectIdClaim
to oid
.
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:
Avoid Assigning the Same AuthenticationId to Multiple Users
Although the API will let you map multiple users to the same authenticationId
, only the alphabetically first userId
will be able to log in.
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:
- 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.
- 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.
- Seamless Account Creation: The user is immediately taken to their GoodData dashboard. Meanwhile, their account has just been created in the background.
- 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:
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.)
Enable JIT Provisioning: After updating your provider configuration, enable JIT provisioning at the organization level using the organization API. Set the
jitEnabled
attribute totrue
.
Configuration
Be cautious when configuring the urn.gooddata.user_groups
claim. If it includes user groups that don’t exist in your organization, these groups will be automatically created. As access rights are derived from users’ user groups, creating such groups can be a potential security issue.
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.
Secure Logout
Logging out via the API will not register the logout with the identity provider. This means that the logout will not affect all active sessions.
For a complete logout, you must manually log out directly at the identity provider.
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 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 Oktaaccounts.google.com
for Google