SAML2

SAML2.0 (Security Assertion Markup Language 2.0) is a cross-domain authentication and authorisation system based on security tokens. Next we will see how to configure SSO against the identity provider in Athento.

IP Requirements

The Identity Provider (IP) must provide the XML descriptor to be hosted in the Athento configuration. If it provides an accessible path to the descriptor, Athento can link directly to the IP URL, otherwise it would be enough to place the XML file in the Athento server itself to establish the configuration. To do so, we associate the URL or the file in the Athento configuration attributes: METADATA_AUTO_CONF_URL or METADATA_LOCAL_FILE_PATH.

Attribute Mapping

To set the Athento user configuration with the information coming from the IP, it is necessary to link the IP UserProfileMetadata to the Athento user properties. To do this we use the ATTRIBUTES_MAP attribute.

SAML2_AUTH = {
    'METADATA_AUTO_CONF_URL': 'https://saml2.athento.com/site_media/athento-metadata2.xml',
    'METADATA_LOCAL_FILE_PATH': '/etc/saml2/athento/athento-metadata2.xml',
    'ASSERTION_URL': 'https://saml2.athento.com',
    'CREATE_USER': 'TRUE',
    'NEW_USER_PROFILE': {
        'USER_GROUPS': []
    },
    'ENTITY_ID': 'https://saml2.athento.com/saml2sso/acs/',
    'NAME_ID_FORMAT': None,
    'FRONTEND_URL': 'https://saml2.athento.com',
    'ATTRIBUTES_MAP': {
        'email': 'mail',
        'username': 'mail',
        'first_name': 'givenName',
        'last_name': 'sn',
    }
}

What information does Athento use for SAML2 configuration?

The usual parameters to generate the metadata file are:

Entity ID: Usually a URL of the type https://SUBDOMINIO.athento.com/saml2sso/acs/

Assertion URL: https://SUBDOMINIO.athento.com

User attributes: The minimum recommended attributes are those shown in the following mapping structure, taking into account that the names email, username, first_name and last_name are those used by Athento and the names mail, givenName and sn are those used by the SAML identity provider (adjust as needed).

'ATTRIBUTES_MAP': {
'email': 'mail',
'username': 'username',
'first_name': 'givenName',
'last_name': 'sn',
}

Make a request to soporte@athento.com to know the exact subdomain of your instance.

What should I send to Athento to perform the SAML2 configuration?

To request your SAML2 configuration you must send an email to soporte@athento.com with:

• The metadata XML file
• The equivalent attributes for email, username, first_name and last_name.

Configuration options

Authentication with SAML2 allows some additional configurations, for example:

DEFAULT_TEAM_NAME (string): allows to indicate the internal team name in which users will be created by default.

CHECK_USER_HAS_INTERNAL_GROUPS (bool): Allows to indicate if the user is required to have some group assigned in Athento to be allowed access. IMPORTANT: The user will have to be created by hand in Athento prior to its first authentication.

CHECK_USER_IN_GROUPS (string list): Allows to indicate the name of the groups that the user must have assigned in the user directory to be allowed access to Athento.