SSO with SAML2

Kantree supports Single Sign On authentification using SAML2.

Requirements

Install needed requirements using:

./platform install_extensions_reqs saml

About certificates

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

Configuring the identity provider

Kantree can support multiple identity providers, each named under the identity_providers key. For this guide, we will consider only one identity provider, the default one.

From a metadata file

The easiest way to configure your identity provider is using the xml metadata file.

extensions:
    - kantree.extensions.saml:
        identity_providers:
            default:
                idp_metadata_url: /path/to/metadata.xml

The filename can be a local file or an URL.

Using settings

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

Using Microsoft ADFS as Identity Provider

Creating the Relying Party Trust

Add Kantree as a Relying Party Trust:

  1. On the ADFS Server, access the ADFS Management Console.
  2. Navigate to Trust Relationships > Relying Party Trusts > Add Relying Party Trust.
  3. Select Start on the Add Relying Party Trust Wizard page.
  4. Select Import Data about the relying party published online or on a local network.
  5. Enter the following URL: https://<yourdomain.com>/saml/default/metadata
  6. Enter a Display name such as “Kantree” and select Next.
  7. Select “I do not want to configure multi-factor authentification” and select Next
  8. Select Permit All Users to Access this Relying Party and select Next.
  9. Select Next on the Ready to Add Trust step and then select Close on the Finish step.

You can also find these steps on the Microsoft ADFS documentation: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust#to-create-a-claims-aware-relying-party-trust-using-federation-metadata

Add claim rules for relying party trust

Adding claim rules for the Relying Party Trust sends LDAP attributes as claims from the ADFS server to Kantree.

First, create a rule to transform an incoming claim to handle the Name ID. Follow the steps described here: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-transform-an-incoming-claim.
In the “Configure Rule” step, select “E-Mail Address” in “Incoming claim type” and “Name ID” as “Outgoing claim type”.

(Note: by default, Kantree uses the “emailAddress” Name ID format. If you are using another format, you will need to adjust the “Incoming claim type” accordingly)

We then need to map LDAP attributes to Outgoing claim types for Kantree to automatically create users when they are missing. Follow the steps described here: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims.
Provide mappings for the following outgoing claim types: E-Mail Address, UserPrincipalName (UPN), Name

Configure Kantree to use the mapped attributes:

extensions:
    - kantree.extensions.saml:
        identity_providers:
            default:
                # ...
                email_attr: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
                username_attr: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
                display_name_attr: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"

Note: you can actually use any Outgoing claim types as long as you configure them properly in the Kantree config.