SAML Authentication

Owned by Juliane Wetzel
Last updated: Nov 13, 2020

INFO

Security Assertion Markup Language (SAML) allows users exchange authorization data between different parties, in particular, between an identity provider and a service provider.

The Datameer X SAML Authenticator is designed to allow Datameer X to act as a Service Provider with a SAML SSO (Single Sign On) environment. This means that authentication and identity management happen externally to the Datameer X instance. These services are provided by an Identity Provider which authenticates end users and issue assertions containing subject and session information along with arbitrary attributes about the user.

The SAML Authenticator plug-in exposes some extension points to allow customers to provide the appropriate Datameer X user details (group memberships, roles, username, email) based on the incoming assertion.

Requirements

Having an Authentication Repository

INFO

The SAML authenticator requires an authentication repository that resolves the available users to your Datameer X instance.

The SAML authentication repository should have a signed assertion signature, and the clocks between the authentication side and the Datameer X side need to be in sync. The authentication side sends an expiration time to their response token. If the clocks are not in sync, the token can be expired or invalid.

Having the SDK Extension Implemented

INFO

Note that you need to implement SAML SSO SDK Extensions to configure SAML authentication.

Configuring a SAML Authentication

To configure a SAML authentication:

  1. Click on the "Admin" tab and select "Authentication". The page 'Authentication' opens.
     
  2. Click "Edit". The authentication configuration page opens.
     
  3. Select "Remote Authentication System" and select "SAML Authenticator" from the drop-down.
     
  4. Click "Next". 
     
  5. Select from where to load the metadata. 
    INFO: The documentation describes the case 'Load Metadata from File on the Datameer Server File System'.
    INFO: You can upload a file, load the metadata from the Datameer X Server File System or load it from a HTTP URL. 
     
  6. Enter the fully qualified URI of the Datameer server. 
    INFO: If needed, activate the checkbox "Load Balancer Mode" to enable SAML, if Datameer X is running behind a load balancer that terminates SSL/ TLS. If you are using a third-party single sign-on application, add '/saml/SSO' to the end of the URI. 
     
  7. If using a KeyManager, enter the 'KeyStore Path', 'KeyStore Password', 'Service Provider Key Alias' and the 'Service Provider Key Passphrase'.
    INFO: A KeyManager is needed when signing messages is enabled. 
     
  8. Select the "Saml Ldap Authenticator Repository" as the directory service. 
    INFO: You can set up this directory service through the SAML SSO SDK Extensions.
     
  9. Enter the server URL and enter the username and password. 
    INFO: If needed, select "Use default user" instead to use the default user to connect to the server. 
     
  10. Enter the search base query and the user definition query. 
    INFO: If needed, enter the filter query for the groups. 
     
  11. If needed, define the pagination control.
     
  12. Enter the username attribute that defines a username and must be unique across all users. 
     
  13. Enter the email attribute.
     
  14. If needed, enter the attributes for impersonation and/ or salt.
     
  15. Enter the attribute for group names.
     
  16. If needed, enter further group related attributes as well as group related fields, e.g. 'Virtual Group'.
    INFO: The checkbox 'Mixed mode' is enabled by default and enables both internal user management as well as SAML. Having this disabled, the internal user management is disabled. 
     
  17. View that the SAML attribute user provider is enabled.  
  18. If needed, enable the checkbox "Use roles from Directory". 
    INFO: The roles for a user can be defined in the saml assertion or in the user directory. By default the roles comming with the saml assertion are used. In case these roles are not defined in saml, we can read these rules from the directory configured above.
     
  19. If needed, enter properties for the saml username, email, roles and groups assertion. 
    INFO: The default 'SAML Attribute User Provider' uses the following SAML attributes: 'datameer.user.name' as username, 'datameer.user.email' as email, 'datameer.user.groups' as list of groups and 'datameer.user.roles' as list of datameer roles. 
     
  20. If needed, change the advanced SSO options to your needs. 
    INFO: They provide access control options for the authentication. 
  21. Confirm with "Save". The configuration is finished. 

Enabling SAML Debugging

To enable debugging of SAML edit the 'log4j-production.properties' file and add the following:

log4j.category.com.<package_name>=ERROR
#openSAML
log4j.category.org.opensaml=ERROR
log4j.category.org.springframework.security.saml=ERROR
log4j.category.org.springframework.security.web.authentication=ERROR