Cintoo SSO Implementation Guide

TABLE OF CONTENTS

• Overview
• Authentication flow
• User provisioning
• External users
• SSO implementation process
• Identity Provider configuration
  • Option 1 : OpenID Connect
    • Azure AD using a custom application
    • Okta
    • Other providers
      
      
  • Option 2 : SAML

Overview 

Cintoo can be integrated with your corporate Single Sign-On (SSO) solution, in order to fulfill corporate security requirements and simplify user management.

Cintoo supports OpenID Connect (OIDC) and SAML protocols, and is known to work with the following identity providers:

• Azure AD (preferred provider)
• Microsoft ADFS
• Okta / Okta MyID
• Ping Federate

Contact your Cintoo sales representative or sales@cintoo.com to subscribe to the SSO option for your Cintoo account.

Authentication flow

Authentication in Cintoo is done in two steps:

• Enter the login (e-mail address).
• Depending on the domain name (second part of the e-mail after the @ character), redirect to either Cintoo native authentication screen (i.e. with a Cintoo login and password), or to the corporate SSO login screen.

This means that once SSO is activated for the @corp.com domain, any user with a login of the form user@corp.com is redirected to the corresponding identity provider login screen, and there is no way to fall back to the native Cintoo authentication.

Note: customers who subscribed to a custom Cintoo domain (of the form https://corp.cintoo.cloud) can ask to use their own SSO provider for all users, independently of the user’s domain name. See section about External Users below.

User provisioning

SSO is only used for authentication and has no impact on the way users are created in your Cintoo account. Users still have to be invited by an account administrator, or by a project / BIM manager. 

Any user trying to authenticate using SSO without being invited first in the account will get the following error message after the SSO step:

External users

If you invite external users (i.e. with an email in a domain you don’t control) to your projects, by default these users will not authenticate with your SSO, as the SSO is configured per domain name.

Example:

• Your company domain name is corp.com
• You invite user@guest.com to one of your projects
• If guest.com is also a Cintoo customer and subscribed to the SSO option, then user@guest.com will authenticate through guest.com SSO (notcorp.com SSO). Otherwise this user will log in through the native Cintoo authentication.

To increase control over your external users, you may want to:

• Add all external users as guests in your own user directory (e.g. user-guest@corp.com)
• Subscribe to a custom Cintoo domain, i.e. https://corp.cintoo.cloud (contact Cintoo sales for information). This way you will get your own Cintoo tenant, and all your projects will only be accessible through https://corp.cintoo.cloud
• Ask Cintoo IT team to link your custom domain with your SSO provider. This means that any user trying to open a project in https://corp.cintoo.cloud will be redirected to your own SSO, even if they don’t have a @corp.com email address.

SSO implementation process

An SSO implementation always follows these steps:

• Contact Cintoo sales to subscribe to the option
• Configure your identity provider with OIDC or SAML, and communicate the required information to Cintoo IT team via support@cintoo.com (see details below)
• Validate the SSO configuration with a few users, using a temporary login URL
• Agree with Cintoo IT team about a cutover date, after which all users in your domain will be redirected to your SSO login screen

Note that users created in Cintoo prior to the cutover will not be able to connect anymore with their existing Cintoo password.

Identity Provider configuration

Option 1 : OpenID Connect

a) Azure AD using a custom application

If you don’t want to or cannot provision the generic Cintoo application provided in the Azure AD app gallery, you still have the option to create your own application in Azure AD.

In Azure AD, select “App registrations” then “New registration”:

Important: the domain in the redirect URI has to match the domain of your Cintoo instance (e.g. aec.cintoo.com, us.cintoo.cloud, corp.cintoo.cloud).

Once the application is created, edit the Authentication settings and enable the “ID tokens” option:

Note the Application (client) ID and the Directory (tenant) ID of the application and communicate these values to Cintoo IT team:

Important: Cintoo tries to match the user based on its email address. If the upn field of your Azure AD users doesn't contain the email address, you need to configure an optional email claim containing the user's email address (in that case Cintoo will look at the email field in the OAuth reply instead of upn).

Here is how to add this optional claim:

You also need to add an API permission for Microsoft Graph to read the email address:

b) Okta

In Okta administration, create a new app:

Select Web / OpenID Connect:

Add the needed redirect URL:

The redirect URI depends on the domain name of your Cintoo instance. Check with Cintoo IT team what is the correct one.

In the next screen, “General Settings”, click Edit and add the “ID Token with implicit grant” permission:

When it’s done go to “Sign On” tab and note the “Issuer” and “Audience” fields in the “OpenID Connect ID Token” section.

These values will have to be communicated to Cintoo IT team.

c) Other providers

Here is the generic configuration for any other identity provider using OpenID Connect:

• Create a “Cintoo” application
• Configure the redirect URI: https://<domain>/login/oauthcb where domain depends on your Cintoo instance (e.g. us.cintoo.cloud or eu.cintoo.cloud)
• Allow ID token with implicit grant
• Allow the following scopes: openid email profile
• Communicate the following information to Cintoo IT team:
  1. Client ID
  2. OpenID Connect discovery URL (e.g. https://<your_domain>/.well-known/openid-configuration)

Important: Cintoo matches the user name based on the email field in the OAuth reply. If there is no email field, the upn field is used instead.

Option 2 : SAML

Here is the Service Provider Metadata you will need to configure your SAML identity provider:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://<domain>/saml">
    <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<domain>/saml" index="1"/>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

Note that domain has to be replaced by the domain name corresponding to your instance of Cintoo (e.g. eu.cintoo.cloud, us.cintoo.cloud, or your-company.cintoo.cloud).

You will need to communicate your IdP metadata URL of file to Cintoo IT team, or at least the following details:

• IDP entity ID
• Login URL
• Signing certificate(s)

Important: Cintoo matches the user name based on the NameID field (SAML subject) in the SAML response. The NameID has to be same as the Cintoo login, i.e. the user’s email address.