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.

Troubleshooting

Common Issues

The table below provides troubleshooting guidance for issues arising from SAML integration.

Symptom Reason Verification Next steps

IdP is posting to the wrong SP URL.

The SP URL has the wrong domain.

Check the SP URL on the SAML configuration page

Update the domain on the Domain Settings page. Re-enable SAML.

The user is not redirected to the correct Login URL

The login URL is heavily cached or not specified.

Confirm the Login URL if IdP initiated is configured. Restart the web application:

sde apache restart

Technical issues error page

IdP is configured for endpoint /sso/saml2/acs

Check the IdP configuration for the SP URL.

Ensure the IdP configuration posts to URL with a trailing slash. For example, /sso/saml2/acs/

The IdP has specified an unexpected entity ID.

Check the SAML logs for a "Not for me" error

Make sure the IdP has configured the SP for entity ID https://<your-sd-elements-domain>/sso/saml2/metadata/

An entity ID mismatch between the SAML assertion and the IdP metadata.

Check the SAML logs for a "Missing key" error

Ensure the entity ID in the IdP metadata is correct.

System time may be out of sync with the time on the SAML token.

Check the SAML logs for a "Can’t use it yet" error

Ensure NTP settings are correct and working.

The certificate inside the SAML request may be invalid. Verify that it is in unix format and does not contain DOS line endings.

Check the SAML logs for a "Strange beginning of PEM File" error

You can also validate it using the following command:

openssl x509 -in filename.crt -text -noout

Unexpected attribute mapping. Verify the value of SAML_ATTRIBUTE_MAPPING in the /docs/sde/local_settings file.

Check SAML logs for "The user is none" or "Could not find saml_user_value" error

Update the SAML_ATTRIBUTE_MAPPING for expected input.

Decryption of the encrypted assertion has failed. The IdP metadata is missing or the IdP used an incorrect public encryption key for the SP.

Check the SAML logs for " 'NoneType' object has no attribute 'authn_statement' " error

  • Regenerate the SP metadata and re-import into the IdP.

  • Reinstall the IdP metadata.

Enabling verbose logging

SAML logs are outputted to /docs/sde/log/saml.log.

 If it appears that no logs are being written to the file, then try deleting the existing file and let it auto-regenerate.
Prerequisites:

  • SSH credentials for sde_admin or sudo access.

Steps:

  1. Open /docs/sde/live/code/sigma/osd_settings.py and update the following entry,

    LOGGING = {
    ...
    'handlers': {
        ...
        'saml': {
            'level': 'DEBUG',   # Change this value to DEBUG
            'class': 'logging.handlers.TimedRotatingFileHandler',
            'filename': os.path.join(ROOT_SDE_PATH, 'log/saml.log'),
            'when': 'W0',
            'formatter': 'file',
        },
    },
    'loggers': {
        ...
        'djangosaml2': {
          'handlers': ['saml'],
          'level': 'DEBUG',   # Change this value to DEBUG
          'propagate': False,
        },
        'pysaml2': {
            'handlers': ['saml'],
            'level': 'DEBUG',   # Change this value to DEBUG
            'propagate': False
        },
        'saml2': {
            'handlers': ['saml'],
            'level': 'DEBUG',   # Change this value to DEBUG
            'propagate': False
        },
        ...
    }
}

  2. Restart Apache

    sde apache restart
 The logs may contain sensitive information. Remember to disable verbose logging when it is no longer needed.

results matching ""

    No results matching ""