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 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 authentication flow to establish a login session and the tokens are in JSON Web format (JWT). In GoodData Cloud we use authorization code flow and the following tokens are used:
- Access Token - provides authorized access to a resource on behalf of the user and it is usually short-lived.
- Refresh Token (if enabled in your Identity provider) - is used to renew the access token if the access token expires and it 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:
- User is not logged in.
- The client (browser) calls the backend resource and gets 401 (no existing session).
- The client calls a login to the application backend (/appLogin).
- The backend requests authorization code from an Identity provider.
- The identity provider authenticates the user and provides the authorization code to the application backend.
- The application backend uses authorization code to issue ID, Access and Refresh tokens from identity provider.
- The application backend tries to find a user based on ID token
- The tokens are encrypted and saved as cookies in a browser creating a login session.
- 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 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 field as it will be used later to update OIDC setting 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 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 identifier of your GoodData Cloud organization and you will obtain it in the welcome e-mail 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 trailing slash “/” in the configuration, make sure you include it at the end of 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 is for the user is user_ID in User Management section in Auth0.
Now you should be able to login 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 to invite other users through application UI or via API but it is limited to 100 users in total and every user is initially created with an 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 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.
Future plans
JSON Web Token (JWT) authentication
- Sometimes customers need to proactively create a session for the GoodData Cloud organization.
- JWT is an open standard according to the RFC-7519 that defines secure transmission of information between parties.
- We are planning to implement passing JWT as an authentication method to authenticate users.
Multiple OIDC providers per GoodData cloud organization
- Currently it is possible to have only one OIDC provider per one GoodData Cloud organization.
- In the future we plan to implement support for multiple OIDC providers per GoodData Cloud organization.