How to set up SAML Single Sign-On (SSO)

About

SAML Single Sign-On and SCIM can be used together in Insightly although implementation of SCIM is codependent on SAML. SAML and SCIM are only available on the Enterprise level plan.

For information regarding SAML & SCIM related to Azure, the Enterprise Application Setup for SAML & SCIM Testing in Azure help article can be reviewed.

What are SAML & SCIM?

SAML

NOTE: This feature is not supported on the Insightly mobile application.

Security Assertion Markup Language (SAML) is the Single Sign-On (SSO) standard for enterprise cloud applications. Using SAML, administrators can manage user access from a single place, and users can access different applications with a single login through an identity provider (IdP) like OneLogin, Okta, G Suite, Microsoft Outlook, or another IdP. This provides an organization with higher security and greater convenience.

Insightly supports SAML 2.0 and can be configured to be a SAML 2.0 Service Provider. The verification certificate file must be an X.509-formatted certificate with an embedded public key, and Insightly supports certificates generated with the DSA or RSA algorithms only.

SCIM

NOTE: This feature is not supported on the Insightly mobile application.

To enable SCIM, users will first have to enable SAML as the implementation of SCIM within Insightly is dependent on SAML integration.

System for Cross Domain Identity Management (SCIM) is a standard protocol used for automating the management of user identities across multiple domains or IT systemsSystem for Cross Domain Identity Management (SCIM) is used for automating the transfer of user identity information between identity domains or IT systems. SCIM is a standard protocol used for automating the management of user identities across multiple domains. SCIM allows administrators to centrally provision and manage Insightly users through an Identity Provider (IdP) such as Okta or Azure Active Directory. SCIM aims to reduce the cost and complexity of user management in companies utilizing a multitude of cloud applications and services. When used with SAML, SCIM provides administrators an end-to-end, standards-based solution for access management. Insightly supports the Users and Schemas endpoints of SCIM 2.0.

SAML Integration Setup

SAML Integration setup occurs via System Settings and is therefore established by a System Admin. Once setup, users can go log into the identity provider, access their application panel, and log directly into Insightly.

Users will need to have an account with an identity provider (IdP) such as OneLogin, Okta, Ping Identity, G Suite, or another IdP.
Add users to Insightly and have them complete their registration. The email address used to add a users to Insightly will need to match the user's email address in the identity provider that is being connected. If SCIM will be utilized, this step can be skipped.

To enable SAML integration, navigate to System Settings > Security > SAML and SCIM and check the Enable SAML Sign-on checkbox.
Copy the URL located in the Sign-on Page URL field. Via the IdP’s settings, setup a SAML app for Insightly and paste the Insightly sign-in page URL into the applicable field of the IdP's SAML app setup.
NOTE: Insightly only supports IDP-initiate SAML 2.0. SP-initiated SAML is not supported.
1. Enter the System Admin email address used for the Insightly account and then download the IdP’s public key/certificate file.
2. Within Insightly, via System Settings > Security > SAML & SCIM, upload the certificate or XML metadata file (if both are available, only one needs to be uploaded into Insightly).
  NOTE:If the XML metadata file is uploaded instead of the certificate, ensure that the metadata has the correct certificate included to avoid an error.
3. To enforce users to use SAML SSO, check the Enforce SAML Login checkbox and click Save.
  1. If SAML SSO is integrated/enabled but not enforced via this checkbox, users can continue to login without using their SAML SSO login.

SCIM Integration Setup

Insightly’s implementation of SCIM supports the /Users and /Schemas endpoints. Batch operations are not supported.

Note: Product licenses are not assigned when provisioning users via SCIM. An administrator has to manually assign licenses to each user from within the Insightly app after provisioning.

To enable SAML integration, navigate to System Settings > Security > SAML and SCIM. Ensure that SAML integration is enabled - SCIM integration cannot be setup without SAML integration being enabled and setup.
To enable SCIM integration, check the Enable SCIM Provisioning checkbox and click Save to generate a SCIM Token and reveal the SCIM URL.
1. Once the page is saved and reloads, the SCIM Token and SCIM URL fields will be populated. Copy the SCIM token and SCIM URL by clicking the copy to clipboard buttons to the right of each field.
  1. To regenerate the SCIM token, the Regenerate button can be clicked. This will invalidate any previously generated tokens. Once regenerated, Save does not have to be clicked as the new token will be instantly saved.
After users have been provisioned via SCIM, a System Admin will need to manually assign licenses to each user by navigating to System Settings > Users > User List.
1. Via the three dot menu for a user, select the Edit User Settings action.
2. Via the Product User Licenses section, enable the checkboxes for each license that should be added to the user and click Save User Details to implement the assignment of licenses.

SCIM Supported Operations

Operation	Description	Notes
GET /Users	Gets a list of users	Returns both active and inactive users. Paging per SCIM spec.
GET /Users/{id}	Gets a single user	Returns a user whether active or inactive
GET /Users?filter=userName eq "user@example.com"	Get users by query	Returns both active and inactive users that match the filter. Insightly only supports the “userName eq” filter.
POST /Users	Creates a user
PUT /Users/{id}	Updates a user
PATCH /Users/{id}	Updates fields included in the request only.	Insightly only supports the “replace” operation.
DELETE /Users/{id}	Deactivates a user	Insightly does not support hard deleting users. This operation is equivalent to setting active=false.
GET /Schemas	Returns attributes supported by Insightly.

SCIM User Attributes & Field Mappings

SCIM Attribute	Insightly Field	Notes
id (readonly)	User.USER_ID	Insightly generated unique identifier of a User.
userName	User.EMAIL_ADDRESS
meta.resourceType (readonly)	“User”
meta.created (readonly)	User.DATE_CREATED_UTC	Insightly generated.
meta.lastModified (readonly)	User.DATE_UPDATED_UTC	Insightly generated.
active	User.ACTIVE	Editable, but set to “true” when creating a new User.
name.givenName	User.FIRST_NAME
name.familyName	User.LAST_NAME
emails (readonly)	User.EMAIL_ADDRESS	Contains a single email address with type=work

Additional Resources

Enterprise Application Setup for SAML & SCIM Testing in Azure

Was this article helpful?