Secure Assertion Markup Language (SAML)

SD Elements can be configured for SAML authentication. It supports version 2.0 of the protocol including IdP and SP-initiated requests. Users are automatically provisioned in the application upon login, unless otherwise configured.

Configure SAML for Single Sign-on

Follow the steps below to configure SAML for Single Sign-on.

Prerequisites:

  • The application user is a Super User.

  • SSH credentials for sde_admin or sudo access.

  • Domain settings for SD Elements is correctly configured.

  • IdP metadata file.

  • SAML Type: IdP Initiated or SP Initiated.

    • If IdP Initiated is chosen determine values for Login URL and Logout URL.

      • Login URL: The URL where unauthenticated users are redirected.

      • Logout URL: The URL where users are redirected after logging out from SD Elements.

  • Setup Certificate for SAML SSO.

  • Verify the IdP sends the Expected user attributes, else Customize the SAML attribute mapping.

Steps

  1. Login to the SD Elements web application.

  2. From the gear icon settings menu, select Authentication.

  3. Select option "SAML" for SSO Type.

  4. In Upload IDP Metadata File: click Choose File.

  5. Select the IdP metadata file.

  6. Select an option for Authentication Type:

    • If SP Initiated (recommended) is selected, decide on a value for Sign Authentication Requests.

    • If IdP Initiated is selected, optionally provide values for Login URL and Logout URL.

  7. Click Save.

The server is now setup to authenticate users using SAML.

 Problems with SAML setup are normally due to invalid domain settings or wrong/missing SAML user attribute mappings.

Service Provider Metadata file

SD Element’s metadata file can be obtained before it is configured for SAML SSO. This can then be used to configure help the IdP.

Prerequisites:

  • The application user is Super User.

Steps

  1. Login to the SD Elements web application.

  2. From the gear icon settings menu, select Authentication.

  3. Select option "SAML" for SSO Type.

  4. The SD Elements metadata file link appears.

  5. Download the SD Elements metadata file from the server:

    `https://<your-sd-elements-domain>/sso/saml2/metadata/`.

Expected user attributes

The IdP is responsible for providing the following user attributes. These values will be used for creating the user in SD Elements.

Attributes:

  • Email: The user email attribute is named: email

  • First Name: The first name attribute is named firstname.

    • Optional. Upon log in, the application will prompt the user if not present.

  • Last name: The last name attribute is named lastname

    • Optional. Upon log in, the application will prompt the user if not present.

 Attribute names are case sensitive.

Customize the SAML attribute mapping

Follow the steps below to support SAML environments that do not provide the expected attribute mapping above.

Prerequisites:

  • SSH credentials for sde_admin or sudo access.

Steps:

  1. Open /docs/sde/local_settings and add the following,

    SAML_ATTRIBUTE_MAPPING = {
    'email': ('username', 'email'),
    'firstname': ('first_name'),
    'lastname' ('last_name')
}

  2. Update SAML_ATTRIBUTE_MAPPING to reflect the IdP user attribute values.

    • For example, to map the SDE user’s email to an IdP user attribute corporate_email set SAML_ATTRIBUTE_MAPPING as follows:

      SAML_ATTRIBUTE_MAPPING = {
    'corporate_email': ('username', 'email'),
    'firstname': ('first_name'),
    'lastname' ('last_name')
}

  3. Save the file.

  4. Restart Apache

    sde apache restart

The system is updated to use the customized SAML attribute mapping.

 If the IdP does not send the email attribute but an email address is sent in the <NameID> element, add SAML_USE_NAME_ID_AS_USERNAME = True to /docs/sde/local_settings.

Setup Certificate for SAML SSO

You can use your own or follow the steps below to generate a self-signed certificate and key.
If you are using your own certificate, ensure it satisfies the following:

  • The certificate is a PEM-encoded X509 certificate

  • The certificate is stored in /docs/sde/saml2/server.crt

  • The key is stored in /docs/sde/saml2/server.key

  • The certification and key have the permission bits 664

  • The certification and key are owned by the sde_admin user and the sde group

Generating a Self-Signed Certificate

Prerequisites:

  • Outbound network access to this documentation

    • If external network access is unavailable you can download the file locally and scp it onto the server

  • SSH credentials for sde_admin or sudo access.

Steps:

  1. Access the SD Elements server SSH console as sde_admin.

  2. Download the following script using wget: samlcert.sh

  3. Run the script to generate the files:

    bash samlcert.sh

The files server.crt and server.key will be generated in /docs/sde/saml2/

Disable auto user provisioning (SAML)

By default, users who authenticate using SAML are automatically provisioned a user account in SD Elements when they attempt to login. Follow the steps below to restrict access only to users who are manually provisioned.

Prerequisites:

  • SSH credentials for sde_admin

Steps:

  1. Access the SD Elements server SSH console as sde_admin.

  2. Update file /docs/sde/local_settings set:

    SAML_CREATE_UNKNOWN_USER = False

  3. Save the file and run:

    sde apache restart

Users who authenticate using SAML will be unable to login to SD Elements unless they already have a user account.

results matching ""

    No results matching ""