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.

For more details on how SP-Initiated and IdP-Initiated authentication differ, see SP-Initiated SSO and IdP-Initiated SSO.

Set up Certificate for SAML SSO

Use your own certificate, or generate a self-signed certificate and key by following the steps below.

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 certificate and key have the permission bits 664

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

  • For SELinux users, ensure files have the correct context

Generate 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.

  • The certificate and key have the permission bits 664

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

  4. Make sure the files have the correct owners:

    sudo chown sde_admin:sde /docs/sde/saml2/server.*

  5. For SELinux users, make sure files have the correct context:

    sudo chcon unconfined_u:object_r:httpd_sys_content_t:s0 /docs/sde/saml2/server.*

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

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.

  • 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.

  • Verify the IdP sends the expected SAML attributes. Otherwise, Customize the SAML attribute mapping.

Steps:

  1. From the gear icon menu in SD Elements, select Authentication.

  2. For SSO Type, select SAML.

  3. Under Upload Identity Provider Metadata File: click on Choose File and select the IdP metadata file.

  4. Select an option for Authentication Type:

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

    2. (Optional) If IdP Initiated is selected, provide values for Login URL and Logout URL.

  5. Click Save.

The server is now set up to authenticate users using SAML.

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

Service Provider Metadata file

Once you have successfully set up a certificate for SAML SSO, the SD Elements metadata file can be obtained before it is configured for SAML SSO. This can then be used to help configure the IdP.

Prerequisites:

  • The application user is Super User.

Steps

  1. Log in to the SD Elements web application.

  2. From the gear icon menu, select Authentication.

  3. For SSO Type, select "SAML".

  4. The SD Elements metadata file link appears.

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

Alternatively, you can access the following link directly:

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

The metadata file contains no sensitive information, so it is safe to make publicly accessible.

Identity Provider Metadata file

Follow the steps below to view the currently uploaded identity provider metadata file.

Prerequisites:

  • The application user is Super User.

Steps

  1. Log in to the SD Elements web application.

  2. From the gear icon menu, select Authentication.

  3. For SSO Type, select "SAML".

  4. Under Upload IDP Metadata File, the currently uploaded metadata will be linked.

  5. Click the link to view the metadata file.

Alternatively, you can access the following link directly:

https://<your-sd-elements-domain>/system/remote_idp_metadata.xml.

The metadata file contains no sensitive information, so it is safe to make publicly accessible.

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.

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 log in. 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 log in 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.

Category Symptom Remediations

Form Failures

Error uploading IdP metadata file

Before saving the uploaded metadata file, it is first validated against the SAML 2.0 metadata schema.

Check the form error for more details. If the error is about unresolved definitions, it is possible that the metadata file contains elements and attributes outside of the SAML 2.0 metadata schema. This is commonly seen when attempting to upload a metadata file that uses the WS-Federeation schema. The metadata file needs to be re-exported under the SAML 2.0 schema or manually modified to remove the unsupported elements and attributes.

Redirection Issues

User is redirected to the wrong URL during login or logout attempts
IdP-Initiated

  • Verify that the login URL and logout URL fields are correctly configured.

SP-Initiated

  • Verify that the login and logout service URLs in the uploaded metadata file are correct.

Also verify that the domain field in Domain Settings is set correctly.

Endless redirect after authentication with identity provider

Check the URLs that the user is getting bounced between - this can be found in the Apache log files. It is possible that the identity provider is misconfigured and is not redirecting the user to the correct Assertion Consumer Service URL (/sso/saml2/acs/). If the redirected URL is correct, verify that the authenticating user is not disabled.

For detailed information, see the SAML log file after Enabling verbose logging.

Technical Issues Page

Log shows "Missing Key Error"

This issue occurs when the entity ID in the uploaded metadata file does not match the entity ID of the incoming SAML response. Verify the entity ID in the uploaded metadata file with the identity provider and upload a new metadata file if it is incorrect.

Log shows "Signature missing for response"

This issue occurs when the identity provider fails to send a signed SAML response. Ensure that the identity provider is configured to sign SAML responses or uncheck the toggle in SD Elements to require signed responses.

Log shows "Failed to verify signature"

This issue occurs when the identity provider does not correctly sign the SAML response. Ensure that the identity provider is using the correct certificate to sign responses to SD Elements. The correct signing certificate is available in the SD Elements metadata file.

Log shows "ParseError: no element found: line 1, column 0" or "'NoneType' object has no attribute 'authn_statement'"

This issue occurs when SD Elements receives an encrypted SAML assertion and failed to decrypt it. Ensure that the identity provider is using the correct encryption certificate. The correct encryption certificate is available in the SD Elements metadata file.

Log shows "Can’t use it yet"

This issue occurs when there is a timing skew between SD Elements and the identity provider. SD Elements will reject any responses outside of the usable time frame defined by the identity provider. Ensure NTP settings are correct and working on the SD Elements instance.

Log shows "The user is none" or "Could not find saml_user_value"

This issue occurs when the identity provider does not send back the user’s email as part of the SAML response. Ensure that the identity provider is configured to send the email attribute in the response as defined in the SD Elements metadata file. If the identity provider is sending the attribute under a different name and cannot be modified, see Customize the SAML attribute mapping.

Log shows "<URL> not in [u'<SDE_HOST>/sso/saml2/acs/']"

This issue occurs when the recipient field in the SAML response does not match the assertion consumer service URL that the response is being sent to. Ensure the identity provider is updated to use SD Elements' assertion consumer service URL in the recipient field.

Log shows "Not successful operation"

This issue occurs when the authentication or logout request to the identity provider is rejected. The SAML response of the failed request can be found in the logs and will contain a StatusCode element. Refer to this guide for a description of the status codes. If a generic error status is returned in the response, contact the identity provider to get a more detailed error message.

Enabling verbose logging

Saml logs are outputted to a file in /docs/sde/log/. To determine where SAML is currently logging, run the following and look at the time stamp to see which log file is currently being used:

ls -al saml_*
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 ""