Authentication

Canopy has a number of different authentication options available. They are explained in this document, along with how to configure them.

Local user database

By default, Canopy uses a local user database for storing user accounts and credentials. This is based on Django’s auth module, and the standard configuration uses PBKDF2 for password storage. The authentication details are managed via the Canopy Users admin interface:

image0

For further details on how Django stores user passwords, see the Django documentation.

LDAP/Active Directory (Premium)

Integration with LDAP/AD is supported in Canopy.

We assume that you have knowledge of LDAP/AD authentication and sufficient permissions/capabilities to set up the LDAP/AD server side requirements. This aspect of the configuration is not considered within the scope of this document.

Installation

Canopy already installs the necessary components for our premium users to make use of LDAP/AD authentication.

Configuration

Configuration of AD/LDAP is done via the inclusion of the following configuration:

[settings]
# Example settings for Windows AD auth
AUTH_LDAP_ENABLE=true
AUTH_LDAP_SERVER_URI=ldap://windows.ad.local
AUTH_LDAP_BIND_DN=CN=Administrator,CN=Users,DC=example,DC=com
AUTH_LDAP_BIND_PASSWORD=password
AUTH_LDAP_USER_SEARCH_DN=CN=Users,DC=example,DC=com
AUTH_LDAP_USER_SEARCH_FILTER=(&(objectClass=user)(userPrincipalName=%%(user)s))

Single sign-on (Premium)

Single sign-on (SSO) is available in Canopy as of version 3.0.1. Our implementation is based on top of SAML2, which means that any SAML2 based SSO solution should be readily supported.

We assume that you have background knowledge of SAML2 and the SSO system you are integrating with. If you have any specific questions, please open a ticket or email us at support@checksec.com.

Installation

Canopy already installs the necessary components for our premium users to make use of SAML2. Configuration of external SAML2 systems is not covered in this document.

Configuration

The Canopy SAML configuration files are located under /etc/canopy/saml. The following configuration files are present:

canopy.ini

SAML ini file for enable/disabling SAML integration

config.py

SAML configuration file

These additional files are included, but are unlikely to be required for typical set ups:

attributemaps/basic.py

Default attribute mapping setup

/etc/canopy/saml/canopy.ini

The canopy.ini file is used to configure the basic settings for SAML integration and to enable/disable use of SAML.

[settings]
SAML_ENABLE=true
#SAML_CONFIG_FILE=/etc/canopy/saml/config.py
SAML_ATTRIBUTE_MAPPING=email=email

The above configuration is pretty straightforward. The most important aspect (apart from enabling/disabling) is which SAML_ATTRIBUTE_MAPPING should be used for the unique identifier. Canopy requires the email address at the moment, although the UUID could also be used if supported in the SAML provider.

/etc/canopy/saml/config.py

The following sample configuration is provided for integration with a SAML Service Provider.

import saml2
import saml2.saml

SAML_CONFIG = {
    # full path to the xmlsec1 binary program
    'xmlsec_binary': '/usr/bin/xmlsec1',

    # your entity id, usually your subdomain plus the url to the metadata view
    'entityid': 'http://172.17.0.1:8000/saml2/metadata/',

    # directory with attribute mapping
    'attribute_map_dir': '/etc/canopy/saml/attributemaps',

    # this block states what services we provide
    'service': {
        # we are just a lonely SP
        'sp': {
            'name': 'Federated Django sample SP',
            'name_id_format': saml2.saml.NAMEID_FORMAT_PERSISTENT,
            'allow_unsolicited': True,
            'endpoints': {
                # url and binding to the assetion consumer service view
                # do not change the binding or service name
                'assertion_consumer_service': [
                    ('http://172.17.0.1:8000/saml2/acs/',
                     saml2.BINDING_HTTP_POST),
                ],
                # url and binding to the single logout service view
                # do not change the binding or service name
                'single_logout_service': [
                    ('http://172.17.0.1:8000/saml2/ls/',
                     saml2.BINDING_HTTP_REDIRECT),
                    ('http://172.17.0.1:8000/saml2/ls/post',
                     saml2.BINDING_HTTP_POST),
                ],
            },

            # attributes that this project need to identify a user
            'required_attributes': ['uid', 'email'],

            # attributes that may be useful to have but not required
            'optional_attributes': ['eduPersonAffiliation'],

            # in this section the list of IdPs we talk to are defined
            'idp': {
                # we do not need a WAYF service since there is
                # only an IdP defined here. This IdP should be
                # present in our metadata

                # the keys of this dictionary are entity ids
                'http://172.17.0.2:8080/simplesaml/saml2/idp/metadata.php': {
                    'single_sign_on_service': {
                        saml2.BINDING_HTTP_REDIRECT: 'https://172.17.0.2:8080/simplesaml/saml2/idp/SSOService.php',
                    },
                    'single_logout_service': {
                        saml2.BINDING_HTTP_REDIRECT: 'https://172.17.0.2:8080/simplesaml/saml2/idp/SingleLogoutService.php',
                    },
                },
            },
        },
    },

    # where the remote metadata is stored
    'metadata': {
        'local': ['/etc/canopy/saml/metadata.xml'],
    },

    # set to 1 to output debugging information
    'debug': 1,

    # Signing
    'key_file': '/etc/canopy/saml/mycert.key',  # private part
    'cert_file': '/etc/canopy/saml/mycert.pem',  # public part

    # own metadata settings
    'contact_person': [
        {'given_name': 'Luke',
         'sur_name': 'Skywalker',
         'company': 'Jedi Knights LLP',
         'email_address': 'luke@jedi.knights',
         'contact_type': 'technical'},
        {'given_name': 'Leia',
         'sur_name': 'Skywalker',
         'company': 'Jedi Knights LLP',
         'email_address': 'leia@jedi.knights',
         'contact_type': 'administrative'},
    ],
    # you can set multilanguage information here
    'organization': {
        'name': [('CheckSec', 'en'), ('El CheckSec', 'es')],
        'display_name': [('CheckSec', 'en'), ('CheckSec', 'es')],
        'url': [('http://checksec.com', 'en'), ('http://checksec.com', 'es')],
    },
    'valid_for': 24,  # how long is our metadata valid
}

Multi-factor authentication (Coming soon - all users)

Multi-factor authentication will be added to Canopy in an upcoming release. We intend to support the following solutions initially:

  • Google Authenticator

  • Yubikey

  • RSA