SSO

Kantree supports Single Sign On with OpenID Connect and SAML2. Each one is an extension: load it in extensions and configure your identity providers.

Users log in with their identity provider at /oidc/<provider name>/login or /saml/<provider name>/login. To show an SSO panel next to the password form of the login page, see Authentication.

OpenID Connect

Activate the kantree.extensions.auth.oidc extension and configure the identity providers with the oidc_identity_providers setting. Kantree can support multiple identity providers, each named under this key. For this guide, we will consider only one identity provider, the default one.

First, create a client (or application) for Kantree in your identity provider, with this redirect URI:

https://<yourdomain.com>/oidc/default/callback

Then configure Kantree with the discovery URL of your identity provider and the credentials of the client:

extensions:
    - kantree.extensions.auth.oidc
oidc_identity_providers:
    default:
        discovery_url: "https://idp.example.com/.well-known/openid-configuration"
        client_id: "CLIENT_ID"
        client_secret: "CLIENT_SECRET"

Important: by default, OpenID Connect is the only way to log in: the password login and the signup without OpenID Connect are turned off. Set oidc_only: false to keep them.

Optional options of an identity provider:

Example of a claim mapping:

oidc_identity_providers:
    default:
        # ...
        claim_mapping:
            username: preferred_username

All the options are listed in OpenID Connect authentication.

SAML2

Kantree must be served over HTTPS (server_secured: true): SAML needs the SameSite=None session cookie.

Starting with 11.0, the options of the extension are top-level settings with the saml_ prefix: identity_providers is saml_identity_providers. The options given under the extension entry in extensions still work, but the top-level settings take precedence. The migrate-config command moves them for you.

All the options are listed in SAML authentication.

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

Activate the kantree.extensions.auth.saml extension and configure the identity providers with the saml_identity_providers setting. Kantree can support multiple identity providers, each named under this 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
saml_identity_providers:
    default:
        idp_metadata_url: /path/to/metadata.xml

The filename can be a local file or an URL. A local file must be mounted in the app container and readable by the user 65532.

Manual configuration

You will need to configure an identity provider as follow:

extensions:
    - kantree.extensions.auth.saml
saml_identity_providers:
    default:
        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:

Security settings

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

Example:

extensions:
    - kantree.extensions.auth.saml
saml_identity_providers:
    default:
        ...
        security:
            wantAttributeStatement: false

Enable encryption

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)

The string version of a certificate or private key is the plain text version without the header and footer on a single line.

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

extensions:
    - kantree.extensions.auth.saml
saml_identity_providers:
    default:
        ...
        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
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.

Using Keycloak as Identity Provider

By default, Keycloak will require Service Provider to have a certificate. Prepare a certificate and private key. See “Enable encryption” section.

First, configure Kantree:

extensions:
    - kantree.extensions.auth.saml
saml_identity_providers:
    default:
        idp_metadata_url: "http://yourkeycloak.com/realms/YOUR_REALM/protocol/saml/descriptor"
        use_name_id_as_identifier: false
        email_attr: email
        username_attr: username
        sp_cert: "..."
        sp_private_key: "..."
        security:
            wantAttributeStatement: false
            logoutRequestSigned: true

Once Kantree is restarted with the new settings, download the metadata file from https://yourkantree.com/saml/metadata

Then in Keycloak:

1. Select Clients from the main navigation sidebar
2. Add a new client and upload the details by clicking Import client and upload the metadata file

3. Using a shared client scope or in the client scope for your new client:

   1. Click Configure a new mapper > User Attribute, and enter the details below:

      Mapper Type: User Attribute

      Name: email

      User Attribute: email

      SAML Attribute Name: email

      SAML Attribute NameFormat: Unspecified

      Click Save

   2. Do the same for email

Confirm that everything works !