Organization single sign-on

Single sign-on allows you to employ your existing organization's identity provider as the sign in system for members of your organization.

This allows members of your organization to bypass the Civillo registration and sign in and gives you full control over the users account from your organization identity provider.

Members with accounts in your organization's identity provider who have yet to sign up to Civillo with their email address are able to do so via single sign-on. After doing so they will automatically be added to your Civillo organization without having to accept an invitation.

Civillo single sign-on uses "Security Assertion Markup Language (SAML)" to verify sign in authorization sent from your organization identity provider.

TIP

Civillo can only act as a service provider in single sign-on. There is no support for acting as the identity provider. An external identity provider is required.

Initialization

To set up single sign-on in Civillo for your organization, please follow the following steps.

1. Register for a Civillo account manually.

A Civillo account is required so you can at least sign in to Civillo to set up single sign-on.

2. Your organization must have been created in Civillo.

You'll need to contact Civillo support at support@civillo.com to have your organization added to Civillo. This will usually be set up as part of the onboarding process when your first project or trial is set up.

3. You must have the role of organization administrator in Civillo.

Only users with this role have permission to change settings that affect the organization as a whole.

4. Single sign-on made available to your organization.

Please contact Civillo support to have this functionality made available for you as it is not available by default.

5. Verifying your organization's email domains.

Once your organization has access to single sign-on, you will be able to access the Single sign-on settings page by navigating to Administration, opening the Organization item and finally selecting the Single sign-on page.

In order for single sign-on to work, at least one of your organization's email domains must be verified by Civillo. There are three ways this can be done:

1. On the organization single sign-on settings page, click Add new domain and enter your domain in the Domain name box then click Confirm. Next, select "Email" as the Domain verification method and send a verification email to one of the available email addresses. If none of these addresses exist then you must create one. Once you have received this email, click the link within and your domain with then be verified.
2. Similar to above but select "DNS" as the Domain verification method then click Get verification code. Create a DNS TXT record at _civillosso.(YOUR DOMAIN) and set its value to this code. Civillo will check every 5 minutes whether this code has been added; once it is found Civillo will mark your domain as verified.
3. Contact Civillo support at support@civillo.com and request us to verify your domain manually.

Settings

All fields required for setting up single sign-on are available from the Administration -> Organization -> Single sign-on page.

Domain

Email domains are how Civillo determines which users will be eligible (or restricted) to signing in using the organization single sign-on. After registering a domain here you must verify your ownership of it following the steps above.

Note that you cannot change a domain name here after it has been registered; you must instead remove the domain then create a new one (and repeat the verification procedure).

Domain restriction

By default when using single sign-on, Civillo allows users to decide if they wish to sign in with either their Civillo credentials or their organization identity provider credentials via a prompt after entering their email address on the sign in page.

Sign in can be restricted to only use organization identity provider single sign-on by enabling the Restrict domain to single sign-on only setting here. In this case, no prompt will be available to the user and they will be redirected automatically to the organization identity provider sign in page.

Identity provider metadata URL

Your identity provider may or may not host a SAML metadata file, which describes their configuration in a format adhering to the SAML V2.0 Metadata specification (opens new window). If you are able to obtain the link to this file, provide it here and Civillo will take care of the rest of the integration steps.

Otherwise, select the Enter identity provider details manually setting and fill out the following three inputs.

Identity provider sign-in URL (manual only)

The URL of the organization identity provider single sign-on page should be set here. Users will be redirected here for sign in. After the identity provider authorizes the user, it is expected they will be redirected back to Civillo with an appropriate SAMLResponse.

Identity provider sign-out URL (manual only)

The URL of the organization identity provider sign-out page can be set here. If set, after signing out from Civillo, single sign-on users will be redirected to this page to attempt to sign out from the organization identity provider.

Signing certificate (manual only)

A public signing certificate is required from your organization identity provider so that Civillo can verify that any single sign-on SAMLResponse has been made and authorized by the organization identity provider and not an unexpected source.

Identity provider sign-out protocol

The binding protocol that your organization identity provider sign-out page is expecting. This defaults to HTTP-REDIRECT, however if your identity provider expects HTTP-POST, then this value can be changed here.

Enabling single sign-on

After the correct identity provider settings are entered, you can enable single sign-on by the toggle in the top right of the page.

If for any reason single sign-on has a problem, it can be disabled by disabling the toggle in the top right of the page.

Note that you must have at least one verified domain in order to enable single sign-on. If you remove your last verified domain from the list of registered domains then single sign-on will automatically be disabled for your organization.

Identity provider setup

Depending on your organization identity provider setup, you will need to set some settings related to Civillo in the identity provider so it knows where to send sign in responses and how to structure the SAMLResponse.

Audience

The SAML audience is a unique identifier (also known as issuer or identifier) to help your identity provider identify Civillo as a service provider. This value needs to be set to https://app.civillo.com/sp.

Sign-in callback

URL

After a single sign-on request from Civillo has been authorized, the SAMLResponse should be sent to the Civillo SSO callback URL which is https://app.civillo.com/i/user/ssoauthorize. This needs to be set in the application settings of your identity provider. It is usually named something like Assertion Consumer Service (ACS).

Mappings

The SAMLResponse must contain one of the following attribute mappings to be successfully parsed by Civillo:

Email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	User.email	mail	email
First name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	User.FirstName	first_name	givenName	firstName
Last name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	User.LastName	last_name	email	lastName

Sign-out

URL

If you wish to have your organization members sign out from Civillo after signing out from your identity provider, they should be redirected to the Civillo sign out page using HTTP-REDIRECT binding. https://app.civillo.com/i/user/signout

Reverting back to Civillo credentials

If for any reason you wish to revert your organization back to using Civillo credentials, you can just disable single sign-on using the toggle in the top right of the page.

TIP

When reverting back to Civillo credentials, any users who originally automatically registered by signing in with single sign-on, a password can be generated for them by using the password recovery (opens new window) service.

Notes on sign-in and user identification

The name ID format of the identity provider's SAML response (after successfully logging in at the identity provider) determines how the user is stored and identified in Civillo.

• If the format is emailAddress, the user from the identity provider is identified in Civillo solely by their email address. With this implementation, a user changing their email in the identity provider will result in a new user being created when logging into Civillo and losing access to their old Civillo information. To rectify this, you will have to contact Civillo support at support@civillo.com.
• If the format is unspecified or persistent, the user from the identity provider is identified in Civillo by the name ID of the SAML response (decoupled from email). With this implementation, a user can change their email in the identity provider and still be identified with their old account in Civillo. The email stored in Civillo will be updated for this user when they next log in.
• Any other format is not supported by Civillo and any attempts to authorize the user in Civillo using this SAML response will be rejected.
• If a response for a existing user is received with a name format different to one stored previously then authorization will be rejected; you will again have to contact Civillo support.

Note that users in organizations whose SSO integrations only allow sign-in via SSO are forbidden from changing their email and password or enabling MFA in Civillo.

An edge case is when a SSO user in an organization permitting sign-in via both Civillo or SSO (and the identity provider of which has name format unspecified or persistent) changes their email in Civillo. In this case, the email should then be changed accordingly in the identity provider to allow the user to log in with this new email. If it is not, and they sign in to Civillo using their old email at the identity provider, then their email stored in Civillo will be reverted to the old email.