Federated Identity Management

This type of authorization extends our regular Auth Service, enabling you to:

Use multiple OIDC providers
Use SAML authentication
Combine both MOIDC and SAML authentication simultaneously

User federation is managed through Amazon Cognito, which connects users from their identity providers. The organization’s Amazon Cognito user pool is configured as an OIDC provider in GoodData.

When a user pool is created, it is located in the same data center as the organization. For example, a customer in Region X will have their user pool in Region X as well. This is important for compliance and data residency requirements.

Multiple OIDCs (MOIDC)

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.

After setting up this feature, you will have access to APIs for managing OIDC providers (see more details below).

Authentication Logic

Enabling multiple identity providers requires a slight change in the authentication process. Here is how it works once everything is set up:

When an unauthenticated user tries to access your organization, they are redirected to a simple login page and asked for their email address. Based on the email suffix (e.g., for example@gooddata.com, the email suffix is gooddata.com), we determine which provider is responsible for the user’s authentication and redirect them there. Once authenticated, they can access the GD platform.

Users can be mapped from each provider using Just-In-Time (JIT) User Provisioning or the API process as described in the Create a User section.

JIT Provisioning Enabled

If a user does not exist in your organization (usually the first time they try to access it), their account is created automatically during authentication. User details are automatically updated on each login if any changes are detected.

JIT Provisioning Disabled

If you create a user with the correct authenticationId from the provider, they will be mapped correctly once they log in. If a user does not exist or has an incorrect authenticationId, their account will not be created automatically, and they will receive a 401 Unauthorized error.

Setting Up Multiple OIDCs

To set up multiple OIDC providers, follow these steps:

Contact Support: Reach out to our support team to enable this feature and inform them whether you want to use JIT provisioning. The support team will assist with the initial setup.
You will need to provide us with the following details of your current identity provider (IDP):
- Client secret
- Unique identifier(s) valid for login via identity provider
  The identifier is a domain name used to direct users to the correct provider for authentication. For example, an organization is configured for MOIDC with two providers: Okta and Auth0. Okta’s identifier is gooddata.com and Auth0’s is example.com. If User A enters UserA@example.com on the login page, then, based on their email, the authentication request is sent to Auth0.
  At least one identifier must be specified for each identity provider, but no more than 50. Each identifier must have a minimum length of 1 and a maximum length of 40. Additionally, each identifier must adhere to the following pattern: [\w\s+=.@-]+.
Encrypt Client Secrets
We strongly recommend encrypting the Client Secrets to prevent unauthorized access. You can use the GoodData PGP key or another encryption method. For guidelines on encrypting a document using PGP, see the GNU Privacy Handbook.
Configure Authentication:
- Our support team will give you a new sign-in redirect URI.
- Register this URI in your current OIDC provider and use it in any providers you add to your authentication flow in the future.
- Regardless of whether you are using JIT provisioning or not, add the GoodData custom scope (urn.gooddata.scope/user_groups) to your current provider and any providers you add to your authentication flow in the future.
- If using JIT provisioning, modify the ID token sent by your OIDC provider to contain the urn.gooddata.user_groups claim (a GoodData-specific claim used for user group membership definition). This claim will now be requested by the urn.gooddata.scope/user_group scope during the new authentication flow. See JIT provisioning for more details.
- Each OIDC provider should be configured to use Client Secret (sometimes referred to as Client Secret Post) as the authentication method.

After the initial setup, your organization will have one federated provider (the one you have been using).

Enabling MOIDC impacts the organization APIs. Once enabled, OAuth-related fields in these APIs become locked and non-editable, as they store the necessary configuration for redirecting authentication to the federation tool (Cognito). Instead, you gain access to APIs for managing OIDC providers.

Manage Customers' OIDCs Directly

We will soon add tools for configuring which OIDC providers a user should use. Until then, we assign the provider automatically to newly provisioned user entities. This also means that the user’s user groups are assigned automatically based on the claims present in the authentication token.

If your tenants manage their own OIDCs, they can define claims and scopes, including the urn.gooddata.user_groups claim, which can grant additional rights outside of a tenant’s scope (as the access rights are derived from users’ user groups). Thus, we recommend managing customers’ OIDCs directly to prevent this possible security issue.

Configuration

Once you have access to APIs for managing OIDC providers, you can use the /api/v1/entities/identityProviders endpoint to manage both MOIDC and SAML providers.

Register an OIDC Provider

To register a new OIDC provider, send a POST request to the /api/v1/entities/identityProviders API endpoint with the following payload:

{
  "data": {
    "attributes": {
      "customClaimMapping": {
        "property1": "string",
        "property2": "string"
      },
      "identifiers": [
        "gooddata.com"
      ],
      "oauthClientId": "string",
      "oauthClientSecret": "string",
      "oauthIssuerLocation": "string"
    },
    "id": "id1",
    "type": "identityProvider"
  }
}

Configuration Parameters

The identifiers parameter contains the email suffix of the group authorized with the configured OIDC. Users with this suffix will be automatically redirected to the specified OIDC for authentication.

The customClaimMapping parameter allows mapping custom claim overrides, useful when your OIDC does not provide default values. You can define the following parameters: sub, email, name, given_name, family_name, and urn.gooddata.user_groups.

The value for id should be unique, have a minimum length of 1, a maximum length of 32, and adhere to the following pattern: [\p{L}\p{M}\p{S}\p{N}\p{P}\p{Z}]+.

Response:

{
  "data": {
    "attributes": {
      "customClaimMapping": {
        "property1": "string",
        "property2": "string"
      },
      "identifiers": [
        "gooddata.com"
      ],
      "oauthClientId": "string",
      "oauthIssuerLocation": "string"
    },
    "id": "id1",
    "type": "identityProvider"
  },
  "links": {
    "self": "http://example.com"
  }
}

List OIDC Providers

To get a list of all OIDC providers for your organization, send a GET request to the /api/v1/entities/identityProviders API endpoint.

Example Response:

{
  "data": [
    {
      "attributes": {
        "customClaimMapping": {
          "property1": "string",
          "property2": "string"
        },
        "identifiers": [
          "gooddata.com"
        ],
        "oauthClientId": "string",
        "oauthIssuerLocation": "string"
      },
      "id": "id1",
      "type": "identityProvider",
      "links": {
        "self": "http://example.com"
      }
    }
  ],
  "links": {
    "self": "http://example.com",
    "next": "http://example.com"
  },
  "meta": {
    "page": {
      "number": 0,
      "size": 0,
      "totalElements": 0,
      "totalPages": 0
    }
  }
}

Get a Specific OIDC Provider

To see the details of a specific OIDC provider, send a GET request to the /api/v1/entities/identityProviders/{id} API endpoint.

Example Response:

{
  "data": {
    "attributes": {
      "customClaimMapping": {
        "property1": "string",
        "property2": "string"
      },
      "identifiers": [
        "gooddata.com"
      ],
      "oauthClientId": "string",
      "oauthIssuerLocation": "string"
    },
    "id": "id1",
    "type": "identityProvider"
  },
  "links": {
    "self": "http://example.com"
  }
}

Edit an OIDC Provider

To change the settings of a specific OIDC provider, send a PUT request to the /api/v1/entities/identityProviders/{id} API endpoint with the following payload:

{
  "data": {
    "attributes": {
      "customClaimMapping": {
        "property1": "string",
        "property2": "string"
      },
      "identifiers": [
        "gooddata.com"
      ],
      "oauthClientId": "string",
      "oauthClientSecret": "string",
      "oauthIssuerLocation": "string",
      "samlMetadata": "string"
    },
    "id": "id1",
    "type": "identityProvider"
  }
}

Delete an OIDC Provider

To delete a specific OIDC provider, send a DELETE request to the /api/v1/entities/identityProviders/{id} API endpoint. Note that at least one OIDC provider must be defined, so the last OIDC provider cannot be deleted.

Known Limitations

Each user can authenticate with a different OIDC provider, but you can’t link one user to multiple providers.
Users must register using an email with a domain unique to their identity provider. Also, this domain must be registered as an identifier for that provider. This is because we use the email suffix to route users to the correct provider for authentication.
Currently, Azure Entra ID (formerly Azure AD) is not supported with the MOIDC feature.
Embedded visualizations are not yet compatible with Federated Identity Management, which is currently supported only in the standard authentication flow.

OIDC Tokens Security

SAML Authentication