Single sign-on (SSO)

Here we describe how to set-up single sign-on with LeanIX

Overview

LeanIX implements single sign-on (SSO) using the SAML protocol. LeanIX can be configured to work with three kinds of Identity Providers (IDPs). Workspaces for customers that want to use a SSO setup other than the default internal IDP have to be on a dedicated instance that is configured to use a dedicated IDP.

  • internal IDP: the one you see when log in to app.leanix.net
  • internal LDAP-based IDP: we can provide an IDP based on Shibboleth that runs in a docker container and accesses your LDAP directory
  • external IDP: Companies provide an own IDP

Basic Authentication Flow

When the user tries to access the LeanIX application in the browser, the Service Provider (SP) checks if the user if already authenticated. If not, then the user is redirected to the Identify Provider, which initiates the authentication (e.g. via username and password). After successful authentication, the user is redirected back to the Service Provider which grants access to the LeanIX application. The IDP provides attributes, e.g. email address, to the Service Provider which are used to properly identify the user within LeanIX.

SSO Authentication Flow

SSO Authentication Flow

Supported IDPs

LeanIX is tested and works with IDPs which support the SAML 2.0 protocol, e.g.

Hint

For ADFS, we have prepared a site with typical claims here: https://dev.leanix.net/v4.0/docs/sso-with-adfs

Checklist external IDP

Prerequisites:

  • IDP must support SAML 2.0
  • client browser needs network access to IDP

Required decision:
Is the role of a user maintained in LeanIX or IDP? (most customers choose LeanIX here)

  • Managed by LeanIX: Roles can be set during invite of a new user and can later be changed in the user administration. A default role (e.g. VIEWER) can be configured to be assigned to new users automatically on first access of a workspace. In short authentication is done by the IDP and LeanIX handles authorization.
  • Externally managed: The IDP determines the role of a user and transfers it to LeanIX during the login process. Most customers map the membership in a Active Directory Security Group to one of the LeanIX roles. In short authentication and authorization is managed by the IDP.

Setup steps

  1. Customer provides metadata-idp.xml (exported from their IDP)

Common Mistakes

Please make sure to send either a link to the metadata, or the XML in a Zip (in order to avoid problems with spam filter.

Please make sure to send the entire metadata, not only the certificate.

  1. LeanIX sets up a domain and configures it to use the customer's IDP. Once setup, the metadata of LeanIX is available at https://<customer>.leanix.net/Shibboleth.sso/Metadata
  2. Customer imports the LeanIX metadata and configures SAML attributes that LeanIX SP requires (see below).

Common Mistakes

Please ensure that the name of every SAML 2.0 attribute exactly matches the name LeanIX SP expects.

  1. Customer tests the access to https://<customer>.leanix.net/<workspace>

Troubleshooting

Make sure to test access only via https://<customer>.leanix.net/<workspace>, not e.g. via https://app.leanix.net/<workspace> or https://us.leanix.net/<workspace> . We support login via SSO and username / password in parallel for the implementation stage. This will be deactivated in step 5.

We provide you a link with information on the current SAML session here: https://<customer>.leanix.net/Shibboleth.sso/Session . Please send us the result of this page in case something does not work.

Access via Internet Explorer can have problems, if the customer's IDP and LeanIX are in different zones, i.e. the IDP is in the zone "Intranet" while LeanIX is in the zone "Internet". It is then required to put the URL to your LeanIX instance, e.g. https://app.leanix.net into the list of trusted addresses in your Internet Explorer. In enterprises this is often controlled centrally, so please approach the team who define and manage the client configurations.

  1. If successful, LeanIX deactivates the access via username / password.

Attribute Mapping

Please ensure that the name of every SAML 2.0 attribute exactly matches the name LeanIX SP expects.

Name
Format
Example
Comment

firstname

urn:oasis:names:tc:SAML:2.0:attrname-format:uri

Peter

lastname

urn:oasis:names:tc:SAML:2.0:attrname-format:uri

Schmidt

uid

urn:oasis:names:tc:SAML:2.0:attrname-format:uri

peter.schmidt@customer.com

Unique ID of user, stays stable even if Name is changed. Must be in e-mail format

mail

urn:oasis:names:tc:SAML:2.0:attrname-format:uri

peter.schmidt@customer.com

role

urn:oasis:names:tc:SAML:2.0:attrname-format:uri

MEMBER

One of ADMIN, MEMBER, VIEWER. In case multiple roles are submitted comma-separated, then the highest role is taken. This attribute can be omitted if the role of a user is mananged by leanIX.

Hint

The uid needs to be unique within the LeanIX user base. Typically, it is possible that the IDP sends a uid that contains a customer suffix, e.g. uid=123456@customer.xyz. If this is not possible, we can also set this to "Managed By LeanIX". In this case, uids like uid=123456 are ok as well. Please inform us during configuration.

Hint

For Microsoft ADFS we provide a sample custom rule mappings, see https://dev.leanix.net/v4.0/docs/sso-with-adfs.

Example SAML Message

<saml2:AttributeStatement>
   <saml2:Attribute FriendlyName="firstname" Name="firstname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
      Peter
      </saml2:AttributeValue>
   </saml2:Attribute>
   <saml2:Attribute FriendlyName="lastname" Name="lastname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
      Schmidt
      </saml2:AttributeValue>
   </saml2:Attribute>
   <saml2:Attribute FriendlyName="uid" Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
      55201001@customer.com
      </saml2:AttributeValue>
   </saml2:Attribute>
   <saml2:Attribute FriendlyName="mail" Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
      peter.schmidt@customer.com
      </saml2:AttributeValue>
   </saml2:Attribute>
   <saml2:Attribute FriendlyName="role" Name="role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
      MEMBER
      </saml2:AttributeValue>
   </saml2:Attribute>
</saml2:AttributeStatement>

Single sign-on (SSO)


Here we describe how to set-up single sign-on with LeanIX

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.