SAML based Single Sign-On

By Ryan Cleary

Learn how to configure generic SAML SSO connections

Create a SAML Connection 

  1. Navigate to the Settings page.
  2. Click the Access tab.
  3. Find the Authentication section. If that section does not currently exist, SSO is not enabled for your instance.
  4. Click the Add button on the bottom left of the authentication table.
  5. In the new blade, click on the Custom SAML connection option.
  6. Click Next.

Configure SAML Connection 

Once you have created the connection, you will see the following configuration options displayed in the blade.

  1. Metadata File
    • This is the URL to the metadata file for the service provider details. Provide this metadata file to your identity provider if it supports metadata files. Note that this link will not be live until you save the connection page (Step 13).
  2. Advanced Details
    • If your identity provider does not support metadata files, click Show Advanced Details. The advanced details section is covered lower in this article and contains the information from within the metadata file.
  3. Name
    • Provide a display name for the connection. This will be shown on the login page. 
  4. Sign-In URL
    • This is the application sign-in URL provided by your identity provider.
  5. Optional Sign-Out URL
    • This is the SLO URL (Single Logout URL) for your identity provider. SLO allows Kandji to automatically sign users out of your identity provider when they sign out of Kandji. Ensure you only fill in this URL if your identity provider supports SLO and it is configured to support SLO specifically with Kandji.
  6. Signing Certificate
    • Paste the contents of the signing certificate, in X.509 PEM format, from your identity provider. This certificate is used to evaluate the validity of an incoming SAML claim. Paste the full contents of the certificate, including the BEGIN CERTIFICATE and END CERTIFICATE header/footer.
  7. User ID Attribute
    • Specify the attribute within the SAML claim that should attempt to match against an existing administrator. Typically this will be the NAME ID URI (example below) as long as your identity provider is configured to send the user's email for the NAME ID value. Otherwise, match against any additional custom attribute that you intend on sending within the claim.
      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
  8. Sign Request
    • Choose if the request from the Service Provider (Kandji) to the Identity Provider, be signed.
  9. Sign Request Algorithm
    • Select the signing algorithm required by your identity provider. 
  10. Sign Request Algorithm Digest
    • Select the signing algorithm digest required by your identity provider. 
  11. Protocol Binding
    • How should the Service Provider (Kandji) direct requests to the identity provider (typically HTTP-Redirect).
  12. Save
    • Saves your SAML configuration.


Required Claim Attributes 

The following attributes are required in your SAML claim. NameID is technically optional within Kandji, so long as another attribute is specified to match the email address against.

If the surname and given name attributes are missing from your claim, the email address will be used for these values.

Attribute URI

Needed ValueReasoning
NameID
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
The email of the user matching the email of a team member in your Kandji instance.Needed to match the user authenticating to Kandji.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
The last name of the user.Needed to update the users last name.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
The first name of the user.Needed to update the users first name.

Encrypted SAML Assertions

Encrypted SAML Assertions are fully supported. While not required, we encourage you to encrypt the assertions from your identity provider whenever possible. Encrypting these assertions helps to prevent software (like browser extensions) from collecting private information from the SAML assertion. 

Encryption AlgorithmAES256_CBCKey
Transport AlgorithmRSA_OAEP
Encryption CertificateThis is the same public key as used for single logout, it can be downloaded in the advanced details section or from here

Single Logout 

The URL used for Single Logout operations is shown below. HTTP-POST or HTTP-REDIRECT bindings are both supported. The SP Issuer ID is the same as the Entity ID. The public key can be downloaded in the advanced details section or from here

SLO URL: https://auth.kandji.io/logout

Enable the SAML Connection

Once you have configured the SAML connection in both Kandji and your identity provider, you can now enable the connection. Please refer to our Single Sign-On support article for step-by-step instructions. 

Advanced Details

If your identity provider does not support configuring a service provider application via a metadata file, you will manually fill in this information.

  1. Service Provider Metadata File: This is the URL to the metadata file for the service provider details. Provide this metadata file to your identity provider if it supports metadata files.
  2. ACS URL: The URL that a SAML assertion should be sent to.
  3. Entity ID: The entity ID of the service provider (this is also the SP Issuer ID used for SLO requests). 
  4. Service Provider Signing Certificate: This is the certificate used to sign requests from the Service Provider to the Identity Provider. This same certificate should also be used if the identity provider is configured to encrypt SAML assertions sent to the service provider.

SessionNotOnOrAfter

The SessionNotOnOrAfter SAML attribute is not currently supported, we plan to support this feature in a future product update.

Enforcing Single Sign-On

Once you have configured at least one Single Sign-On connection, you can disable the Standard Authentication connection. Disabling Kandji standard authentication will disable the ability for Kandji administrators in your instance to authenticate via Email/Password, Google Sign in, or Office 365 Sign in. Please refer to our Single Sign-On support article for step-by-step instructions.