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. The following sections lay out in order what will be required. Note that successful SAML setup involves configuration on both SD Elements (the Service Provider) and your Identity Provider (IdP).

Configure SAML for Single Sign-on

The following sections will help you configure SAML for Single Sign-on.

Prerequisites:

  • The application user is a Super User.

  • Domain settings for SD Elements are correctly configured, as they will produce the ACS URLs. These will be used to create the SD Elements entity ID and assertion consumer service (ACS) URLs.

  • PEM-format certificate and private key pair for signing, and optionally another pair for encryption, of SAML assertions from SD Elements.

  • Identity Provider (IdP) metadata file.

SAML certificate and private key

SD Elements supports the use of separate certificates and private keys for signing and encrypting SAML assertions. By default, SD Elements auto-generates SAML certificates and private keys for signing and encrypting SAML assertions.

Users may still upload certificates and private keys if they wish, following the guide below.

How to generate SAML certificate and private key (Optional)

Steps:

  1. Download the script using wget.

  2. Verify the hash of the self-signed SAML certificate using the following hash:

$ sha256sum samlcert.sh
d8cedbd336e89c2d6d9328c4ee80dc2ad7d46332d635cdf30e555a1375b81994 samlcert.sh

  1. Edit line 6 of the script to update the output file location to one on your system.

  2. Run the script to create the certificate and private key files:

bash samlcert.sh

  1. Use the resulting certificate and private key files (server.crt and server.key respectively) in the SD Elements UI to obtain SD Elements Service Provider metadata.

Obtain the SD Elements Service Provider metadata file

Steps:

  1. Select Authentication from the SD Elements settings menu.

  2. Select SAML as the SSO type.

  3. Click Choose File under Upload Identity Provider Metadata File and select the IdP metadata file.

  4. Click Choose File under SAML X509 cert and select the SAML certificate file you generated.

  5. Click Choose File under SAML private key and select the SAML private key file you generated.

  6. (Optional) Click Choose File under Separate SAML private key for encryption and select the encryption file corresponding to your private key file.

  7. (Optional) Click Choose File under Separate SAML X509 cert for encryption and select the encryption file corresponding to your certificate file.

  8. Click Save.

  9. Download sde_metadata.xml by using the SD Elements metadata file link. This file doesn’t contain proprietary or sensitive information, and can be shared with your Identity Provider administration team as needed.

If you don’t intend to configure SAML yet and only wanted to obtain its Service Provider metadata file, select SSO Type: None and click Save, otherwise SAML authentication will be enabled. To access SD Elements with a local account (such as superuser) if this occurs, add /accounts/login/ to the SD Elements URL in order to log in and deactivate SAML.

Complete the SAML configuration

You should still be on the Authentication settings page with SAML selected as the SSO type.
Steps:

  1. Upload the Identity Provider metadata file by clicking Choose File within the Upload Identity Provider Metadata File section and choosing the appropriate file.

  2. Select an option for Authentication Type.

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

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

    • (Optional) Require Signed Responses (indicates if the Service Provider is expecting signed responses from the Identity Provider).

    • (Optional) Sign Authentication Requests (only applicable for SP-initiated authentication to indicate if the Authentication Requests sent by this Service Provider should be signed).

    • (Optional) Sign Logout Requests (only applicable for SP-initiated authentication to indicate if the Logout Requests sent by this Service Provider should be signed).

  3. Click Save.

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. These can be found in the application logs. 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.

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.

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.

results matching ""

    No results matching ""