Skip to content

You are viewing documentation for Immuta version 2.8.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

SAML 2.0

Audience: Application Admins

Content Summary: Immuta is compatible with enterprise SAML 2.0 identity providers. Immuta can leverage your SAML provider for authentication and authorizations or use SAML 2.0 only for authentication while maintaining all user attributes and groups within Immuta's built-in identity manager.

This page outlines configuration options and examples for SAML identity managers, including Okta and Azure Active Directory. Implementation will vary based on your SAML configuration. For detailed assistance, please contact your Immuta support professional.

Configuration

SAML IAMs are configured in the Identity and Access Management section of the Application Settings page, but if you have contacted the Immuta Support team and they have instructed you to add advanced configuration options, those options can be managed in the Advanced Configuration section of the Application Settings page:

  • id (string): The id of the IAM. This value will reference the IAM in the callback URL with the format: <base url>/bim/iam/<id>/user/authenticate/callback.
  • displayName (string): The name of the IAM that will show in the Immuta UI.
  • type (string): The IAM type that is being configured. This value must be saml for SAML IAMs.
  • clientOptions (object): Options for the SAML client:
    • issuer (string): Your identity provider issuer; this should match the configured certificate.
    • entryPoint (string): SSO location for redirecting from the Immuta login page.
    • certPath(string): Identity provider public certificate location.
    • protocol (string): Set this to https:// if external TLS is enabled for Immuta or http:// if not.
    • host (string): Set this to the external hostname for Immuta.
    • decryptionPvkPath (string): Private key location for decrypting attribute assertions (optional).
  • supportedActions (array): See Supported Actions for details.
  • schema (object): The mapping schema for profile information and attributes. The yaml keys are the values that you wish to map to, and the yaml values are the keys of the SAML attributes that you wish to derive the values from.
    • profile (object): The mapping schema for profile information. The yaml keys are the values that you wish to map to, and the yaml values are the SAML attributes that you wish to derive the value from.
    • permissions (string): The SAML attribute that contains a list of roles or groups to derive Immuta permissions from.
    • authorizations (object): The mapping schema for attributes. The yaml keys are the values that you wish to map to, and the yaml values are the SAML attributes that you wish to derive the value from.
    • arrayDelimiter (string): Used to split multi-value attributes. For example, a SAML attribute named immutaAuth.locations with the value 'MD, OH' will contain the array value ['MD', 'OH'] in Immuta.
  • permissions (object): The mapping schema for permissions. The yaml keys are the values from the SAML attribute assigned in the schema.permissions configuration and the yaml values are a list of Immuta Permissions to be assigned. If a user has multiple roles or groups assigned, permissions will be merged.
  • defaultPermissions (array(string)): Default permissions to be given to users when they first log in. See Permissions for more information.

Groups

The SAML identity provider will derive groups using a SAML attribute named groups.

Example Configuration

plugins:
  samlIAM:
    id: saml
    displayName: SAML 2.0
    type: saml
    plugin: saml
    saml: true
    clientOptions:
      issuer: 'http://www.exampleprovider.fake/rdsf03ur2hd'
      entryPoint: 'https://example.okta.com/app/documentation_example/rdsf03ur2hd/sso/saml'
      certPath: /etc/immuta/security/saml.crt
      decryptionPvkPath: /etc/immuta/security/decrypt-key.pem
    schema:
      profile:
        name: 'name'
        email: 'email'
        hdfsUser: 'hdfsUser'
      permissions: 'groups'
      authorizations:
        exampleAuth: 'example'
      arrayDelimeter: ','
    supportedActions: ['syncGroups', 'syncAuthorizations']
    permissions:
      immuta-admin:
      - USER_ADMIN
      - AUDIT
      immuta-auditor:
      - AUDIT
      immuta-governor:
      - GOVERNANCE
    defaultPermissions:
    - 'CREATE_DATA_SOURCE'
    - 'CREATE_PROJECT'

Identity Provider Guides

Okta

Integrating with your organization's Okta directory requires creating a custom application mapping in the Okta administrator dashboard.

  1. In the Okta administrator dashboard, navigate to Applications.
  2. Select Add Application.
  3. Select Create New App.
    • For Platform, select Web.
    • For Sign on method, select SAML 2.0.
    • Click Create.
  4. Complete general settings.
    • Fill out a custom app name, or just save it as Immuta.
  5. Complete general SAML configuration settings.
    • For Single sign on URL, enter <your immuta base url>/bim/iam/<your iam id>/user/authenticate/callback. You can check the box that says Use this for Recipient URL and Destination URL.
    • For Enter Audience URI, enter a unique audience name that does not yet exist in your organization's Okta.
    • Default RelayState can be left blank.
    • For Name ID format, select EmailAddress.
    • For Application username, select the profile attribute that denotes the Okta user's email address. Typically, this is simply email.

  6. Complete SAML Attribute Statements. Okta attribute mapping

    • Be sure to build these in accordance with how you build your schema in the Immuta configuration.
    • Multi-value attributes can be mapped in as arrays (with the Okta preview feature), or delimited strings. The default arrayDelimiter is a comma.
    • Groups can only be mapped in as an array of group names, aptly-named groups. The mapping in the screenshot above sends all of an Okta users' groups to Immuta.

  7. Save the Application, and add desired users / groups using the Assignments tab.

Okta Sample Configuration

plugins:
  oktaIAM:
    id: okta
    displayName: Okta
    type: saml
    plugin: saml
    saml: true
    supportedActions: ['syncGroups', 'syncAuthorizations']
    clientOptions:
      issuer: 'http://www.okta.com/e5643t3534534'
      entryPoint: 'https://example.okta.com/app/documentation_example/e5643t3534534/sso/saml'
      certPath: /etc/immuta/security/okta.crt
      decryptionPvkPath: /etc/immuta/security/okta-decrypt.pem
    schema:
      profile:
        name: 'name'
        email: 'email'
        hdfsUser: 'hdfsUser'
      authorizations:
        authColor: 'authColor'
      arrayDelimeter: ','
    defaultPermissions:
    - 'CREATE_DATA_SOURCE'
    - 'CREATE_PROJECT'

Azure Active Directory

Immuta can integrate with Azure Active Directory as an IAM over SAML 2.0. You can find out more in the Azure Active Directory integration guide.