SAML Authentication

The SAML authentication logic is nearly identical to MOIDC authentication.

Authentication and access in GoodData using a federated SAML provider. The user accesses GoodData, which redirects to a login page that automatically selects the provider based on the user's email. The user is then redirected to a federated SAML provider for authentication, which returns a list of attributes. If JIT provisioning is disabled and the user does not exist, access is denied. If JIT provisioning is enabled and the user does not exist, the user is provisioned. If the user exists and claims have changed, the user is updated. In all valid cases, access is granted.

To set it up, follow the MOIDC setup guide and change the details described below.

SAML Configuration

SAML configuration uses the same API endpoint as MOIDC but with a slightly different payload. Instead of OAuth-related parameters, it uses the samlMetadata parameter, which should be defined by a Base64-encoded XML document containing the SAML metadata.

Example: Registering a SAML Provider

To register a new SAML 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"
      ],
      "samlMetadata": "string"
    },
    "id": "id1",
    "type": "identityProvider"
  }
}

Custom Claim Mapping

When configuring an Identity Provider (IdP) — whether OIDC or SAML — in Amazon Cognito, it is necessary to specify which user attributes the IdP supports and returns in its authentication response.

For example:

  • If the token comes from IdP A, it might include attributes like name, familyName, givenName, email, etc.
  • If it comes from IdP B, the token might use attribute names like family_name, given_name, email, and so on.

To handle this variation, Cognito uses attribute mapping, which defines how IdP-provided attributes map to Cognito’s internal user profile attributes. In the Cognito UI, this mapping is visualized in an Attribute Mapping table with Cognito attributes on the left, and Token (IdP) attributes on the right.

For OIDC providers, this is typically straightforward because they usually follow standard naming conventions (sub, email, family_name, given_name, name), allowing the default mapping to work out of the box.

However, SAML providers often use custom or non-standard attribute names. Therefore, custom claim mapping is essential. You must define explicitly how the SAML token attributes should map to Cognito attributes when setting up a SAML IdP.

Example of a required customClaimMapping for a SAML IdP:

"customClaimMapping": {
  "sub": "NameId",
  "email": "Email",
  "given_name": "Fname",
  "family_name": "Lname",
  "name": "Name"
}

Without this mapping, Cognito won’t be able to correctly interpret the incoming attributes from the SAML token.

Federated Identity Management