Skip to content

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 (authorizations 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 authorizations. 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 authorizations. 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.
    • authorizationPrefix (string): Prefix value used to pick up Immuta authorizations from SAML attributes. Attributes with this prefix will be recognized by Immuta as authorizations. For example, a SAML attribute named immutaAuth.locations will be recognized in Immuta as an authorization called locations.
    • 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'
      authorizationPrefix: 'immutaAuth.'
      arrayDelimeter: ','
    supportedActions: ['syncGroups', 'syncAuthorizations']
    permissions:
      immuta-admin:
      - 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.
    • Note that for authorizations, values not configured in the schema can still be picked up as authorizations in Immuta if they include the configured authorizationPrefix. This prefix defaults to immutaAuth..
    • 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'
      authorizationPrefix: 'immutaAuth.'
      arrayDelimeter: ','
    defaultPermissions:
    - 'CREATE_DATA_SOURCE'
    - 'CREATE_PROJECT'

Azure Active Directory

Integrating with Azure Active Directory requires you to create an Enterprise Application to be used with Immuta. You must create a Non-gallery application, which at this time is only available to organizations with a Premium Azure Active Directory license.

For more detailed instructions on creating custom Enterprise Applications, see Active Directory Custom SASS Apps.

  1. From the Azure Active Directory blade, select Enterprise Applications, then click New Application.

  2. Select Non-gallery Application, then name the Application.

  3. Select Single sign-on, then in the Single sign-on blade, select SAML-based Sign-on.

  4. Configure SAML-based sign-on. Configure SAML-based sign-on

    • The Identifier may be any value of your choosing, it will need to be set as the issuer field in the Immuta configuration as well.
    • The Reply URL field will follow the format of

      &lt;your immuta base url&gt;/bim/iam/&lt;your iam id&gt;/user/authenticate/callback
      
    • You do not have to set any Advanced URL Settings such as Sign on URL or Relay State

    • Select the User Identifier field based on what is appropriate for your organization. Common values for this field are user.mail or user.userprincipalname.
    • Check View and edit all other user attributes and configure attributes that will be shared with Immuta.
      • Common attributes to use are email, name, and position.
  5. Enter a notification email address.

  6. Select Configure <your application name>

  7. Download the certificate from the Configure blade by clicking the SAML Signing Certificate - Raw link.

    • This certificate will be DER encoded, so you must convert to PEM encoding before using it with Immuta. You can use OpenSSL to convert the certificate encoding. Use the command below:
      openssl x509 -inform der -in &lt;your cert&gt;.cer -out &lt;your new cert&gt;.pem
      
  8. Use the information on the Configure Sign-on blade to configure the SAML IAM in Immuta

    • The displayName parameter is the name that will be displayed to users on the Immuta login and admin pages.
    • The Identifier that was selected in Step 4 will be used as the issuer option.
    • The SAML Single Sign-On Service URL will be set as the entryPoint option.
    • The converted certificate will be used as the certPath option.
    • Set the protocol option to https:// if your Immuta instance is using TLS.
    • Set the host option to the hostname of your Immuta instance.
  9. Configure the SAML Token Attribute mapping:

    • Common attributes to be mapped are email, name, and position.
    • If the attributes have a namespace set in Azure, then the attribute mapping will be
      &lt;namespace&gt;/&lt;attribute&gt;
      

Azure Active Directory Sample Configuration

plugins:
  azdsIAM:
    id: azds
    type: saml
    plugin: saml
    displayName: Azure AD
    saml: true
    supportedActions: ['syncGroups', 'syncAuthorizations']
    clientOptions:
      issuer: https://demo.immuta.com
      entryPoint: https://login.microsoftonline.com/7d0bfsdafs4-b543-4a3b-8sfd14-dafe785d77/saml2
      certPath: /etc/immuta/azure-saml.pem
      protocol: 'https://'
      host: demo.immuta.com
    schema:
      profile:
        name: name
        email: email
        position: position
      permissions: groups
    permissions:
      immuta-admin:
      - ADMIN
      - AUDIT
      immuta-auditor:
      - AUDIT
      immuta-governor:
      - GOVERNANCE
    defaultPermissions:
    - 'CREATE_DATA_SOURCE'
    - 'CREATE_PROJECT'