SAML 2.0 Authentication

Owned by Gert Burger
Last updated: Apr 23, 2018
2 min read

Overview

Canopy can act as a SAML 2.0 Service Provider(SP) and authenticate against any SAML 2.0 compatible Identity provider(IdP) as a SSO solution with just in time user creation. Additionally it can populate user fields and role assignments directly from SAML attributes.

SAML authentication related settings are configured in /etc/canopy/canopy.ini, /etc/canopy/saml/config.py and a few other related files as specified in /etc/canopy/saml/config.py. Any change to them requires Canopy to be restarted.

Important Information

  • Login can be SP initiated or IdP initiated.
  • Canopy's SAML URLs:
  • The IdP's metadata should be stored under /etc/canopy/saml/metadata.xml and IdP's metadata URL must be configured in /etc/canopy/saml/config.py
  • Canopy requires that the email field is mapped to a SAML attribute that contains the users email address and the name field is mapped to the user's name/surname attribute.
  • SAML request/response signing/transport certificate/key(X509) must be configured in /etc/canopy/saml/config.py
  • If a SAML Attribute map is required then /etc/canopy/saml/attributemaps/basic.py should be updated accordingly. Specifically the attribute nameformat should match what the IdP is emitting.
  • Example config files are located under /opt/checksec/canopy/configs/saml/


Configuration

Example config files may be used as a starting point via the following steps:

  • $ mkdir /etc/canopy/saml
  • $ cp /opt/checksec/canopy/configs/saml/config.py /etc/canopy/saml/
  • $ cp -a /opt/checksec/canopy/configs/saml/attributemaps /etc/canopy/saml/


The following config options(With defaults) are valid inside /etc/canopy/canopy.ini

SAML_ENABLE=true
SAML_ATTRIBUTE_MAPPING=email=email  # This is the minimum required. Format is: user_field1=saml_attribute1,user_field2=saml_attribute2
SAML_SSO_NAME=Single Sign On  # Name of SSO service to display on login page


Additionally a SAML specific config file is also required at /etc/canopy/saml/config.py

Many of the fields will need updating, specifically URLs and file locations.

Attribute Mapping

If allow_unknown_attributes is not set to True in config.py under the SAML_CONFIG dictionary then all attributes used must be configured under required_attributes or optional_attributes and in the attribute maps (/etc/canopy/saml/samlattributemaps/basic.py)

At the very least the email and name fields MUST be mapped to SAML attributes.

Role assignment

Assigning roles based on SAML attributes is optional and not all flags need to be mapped. Unmapped flags can be managed via the Canopy Admin interface. The attribute value should any string value to signify membership. To unset/remove a role the SAML attribute should be have an value of '' (an empty string). Any other value will indicate the role is present. If the attribute is missing then no adjustment will occur.

Role fields currently supported:

is_admin

is_technical_managers
is_senior_analysts
is_analysts
is_schedulers
is_sales_managers
is_account_managers
is_custom_pr_reviewers
is_custom_qa_reviewers

Role mappings form part of the SAML_ATTRIBUTE_MAPPING setting, e.g.

SAML_ATTRIBUTE_MAP=email=email,name=name,is_admin=saml_admin_attribute

Microsoft ADFS 

ADFS requires some additional configuration:

  • A NameID claim with the correct name format is required. Most IdPs send these but ADFS doesn't by default. See https://blogs.msdn.microsoft.com/card/2010/02/17/name-identifiers-in-saml-assertions/
  • When set to send a group membership claims, ADFS will not submit the claim when the user is NOT in the given group. Canopy will be unable to remove a role from a user. To correct this one requires an additional custom claim rule to submit the lack of membership to a group:
    • NOT EXISTS([Type == "GROUPCLAIMTYPE"]) => issue(Type = "GROUPCLAIMTYPE", Value = "");