SSO with SAML2

Kantree supports Single Sign On authentification using SAML2.

About certificates

Certificates and private keys must be converted to their string representation using the following tools:

Configuring the identity provider

You will need to configure an identity provider as follow:

extensions:
    - kantree.extensions.saml:
        identity_providers:
            default:
                email_attr: 'User.email'
                display_name_attr: '{User.FirstName}{User.LastName}'
                idp_entity_id: "https://example.com/..."
                idp_sso_url: "https://example.com/..."
                idp_slo_url: "https://example.com/..."
                idp_cert: "XXXXXX..."

The following options are required:

Key Default Description
idp_entity_id   Entity ID URL
idp_sso_url   SSO URL
idp_slo_url   SLO URL
idp_cert   Certificate as string

Optional options:

Key Default Description
idp_sso_binding urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect SSO Binding
idp_slo_binding urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect SLO Binding
preferred_url_scheme same as kantree The URL scheme to use if different than the one for kantree

Additionnaly, the following security parameters can be defined under the security key:

Key Default
nameIdEncrypted False
authnRequestsSigned False
logoutRequestSigned False
logoutResponseSigned False
signMetadata False
wantMessagesSigned False
wantAssertionsSigned False
wantNameId True
wantNameIdEncrypted False
wantAttributeStatement True
wantAssertionsEncrypted False
signatureAlgorithm http://www.w3.org/2000/09/xmldsig#rsa-sha1
digestAlgorithm http://www.w3.org/2000/09/xmldsig#sha1

If you wish to enable encryption, you can create a certificate for the Service Provider and use the following options:

Key Description
sp_cert Certificate as string
sp_private_key Private key as string

(Note: you can generate them using https://www.samltool.com/self_signed_certs.php)

When uing a certificate for the Service Provider, set the wantAttributeStatement security parameter to false:

extensions:
    - kantree.extensions.saml:
        identity_providers:
            default:
                email_attr: 'User.email'
                display_name_attr: '{User.FirstName}{User.LastName}'
                idp_entity_id: "https://example.com/..."
                idp_sso_url: "https://example.com/..."
                idp_slo_url: "https://example.com/..."
                idp_cert: "XXXXXX..."
                sp_cert: "AAAAAA..."
                sp_private_key: "BBBBB..."
                security:
                    wantAttributeStatement: false

Mapping attributes

By default, Kantree will use the Name ID as identifier and it will be considered an email if the format is set to emailAddress or a username in every other case.

Key Default Description
use_name_id_as_identifier true Whether to use the Name ID as identifier
name_id_format emailAddress Last part of the Name ID format specification
email_as_identifier true When you are not using the Name ID as identifier, whether to use email as identifier, otherwise username

You can control mapping of SAML attributes to Kantree values with the following options:

Key Default Description
email_attr email  
username_attr    
strip_username_domain true If the username is instead an email, whether to remove the domain from the value
display_name_attr    
avatar_attr   Attributes containing the avatar information
avatar_format url One of: url, base64, binary. In case of the last 2, use the next options
avatar_image_ext jpg Format of the avatar image
avatar_image_mimetype image/jpeg Mimetype of the avatar image

The value for display_name_attr and username_attr can contains format string referencing other attributes. Example: display_name_attr: "{FirstName}{LastName}"

Mapping user role

You can set the role of a user using an attribute containing role names:

Key Description
roles_attr Name of the attribute containing the role name
admin_role Name of the role representing the “admin” role in kantree
observer_role Name of the role representing the “observer” role in kantree
disabled_role Name of the role representing the “disabled” status in kantree

Auto joining orgs

You can use an attribute to specify a list of names of orgs/teams to join on login/signup:

Key
orgs_attr