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:

• Certificates: https://www.samltool.com/format_x509cert.php
• Private keys: https://www.samltool.com/format_privatekey.php

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.auth.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.auth.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:

Optional options:

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

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

(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.auth.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.

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

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:

Auto joining orgs

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

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 (feel free to only give access to groups)
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.auth.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.