Single sign-on (SSO) lets your team sign in to Pencil through your organisation's identity provider (IdP), with no separate Pencil password. SCIM keeps Pencil's user accounts in step with your IdP, so people gain and lose access as your directory changes.
Think of SSO as the door check and SCIM as the guest list.
You need the Subscription Admin role to set up either one. Open Settings and select Single sign-on, under the Subscription heading. If you can't see the page, ask your subscription admin. Read more about subscription admin access.
Some steps happen in your IdP rather than in Pencil. If someone else manages your IdP, you'll need their help for those steps. This setup walkthrough video takes you through the process.
Test sign-in first. Get SSO sign-in working on its own before you switch on Set group access, SCIM or ‘Require SSO to sign in’. Each of those can take access away, so confirm people can sign in as expected first.
How do I set up SSO?
Connect your identity provider
Add your IdP. If you have no IdP connections yet, click Add identity provider. If you already have one and don't need a second, click Configure on it instead. Pencil supports more than one IdP on the same subscription.
Download SP metadata. Click Download metadata to get Pencil's Service Provider (SP) metadata. Your IdP must provide information using exactly the field names in this file, or SSO won't work.
Add IdP metadata. Click Metadata URL, enter the URL of your IdP's metadata XML file and click Fetch. If you have the XML file but no URL, use Upload XML file instead.
Check advanced settings. These cover details such as whether the assertion or response is signed. Leave them at their defaults unless your IdP's IT admin tells you to change them.
Enter email domains. Under Email domains, add every email domain your people use to sign in to Pencil through this IdP.
Save your changes. Click Save Changes in the ‘Connect your identity provider’ section.
Switch on SSO and test it
When you're ready to test, turn on the Enable SSO toggle at the top of the page. People in your IdP can then choose ‘Sign in with SSO’ on the Pencil login page.
Check that a few people can sign in this way before you go further. If you only want SSO for sign-in, you can skip the next two sections.
Control workspace access with IdP groups
This step is optional. Use it if you want your IdP groups to decide which workspaces people reach in Pencil, and with which role. Under Set group access, add a mapping for each IdP group that should grant workspace access.
Add a mapping. Click Add mapping, then Add new group.
Name the group. Enter the IdP group name exactly as it appears in your IdP, then click Add group. If you've set up SCIM group provisioning, pick the group from the dropdown instead.
Choose access. Select the workspaces people in that group should reach, and the role they get there. If a group needs different roles in different workspaces, add a row for each.
Save your changes. Click Save Changes in the Set group access section.
Switch it on. Read the warning below, then turn on the Set group access toggle.
Check mappings first. With Set group access on, Pencil creates users when they first sign in through your IdP and adds them to the workspaces their groups map to. It also removes them from any workspace their groups don't map to, even one you added them to by hand. A missing or misspelt mapping can lock people out of workspaces they need.
Once group access is on, Pencil matches each person's workspaces and roles to their IdP groups when they sign in with SSO. With SCIM user provisioning, changes apply as they happen in your IdP, without waiting for the next sign-in.
Set which role wins when groups overlap
Someone can belong to several IdP groups that map to the same workspace with different roles. Each person still holds one role per workspace, so Pencil gives them whichever of those roles ranks highest in your role priority list.
To change the order, click Amend Role Priority in the Set group access section. Drag the roles into the order you want and click Save.
Pencil's standard roles start in a sensible default order, and custom roles sit in the same list. You only need to change it if you use custom roles and have overlapping group mappings. This short video shows how it works.
How do I set up SCIM?
SCIM (System for Cross-domain Identity Management) handles provisioning, while SSO handles authentication. With SSO alone, Pencil only learns someone's details and group memberships when they sign in. SCIM lets your IdP tell Pencil as things change.
Group lists. Your IdP group names appear in a dropdown under Set group access, so you never type them by hand. That removes the risk of a typo silently breaking a mapping.
New starters. Your IdP creates Pencil users and keeps their names and group memberships up to date.
Team moves. When someone changes groups in your IdP, their Pencil access updates on their next action, without signing in again.
Leavers. When you offboard someone in your IdP, Pencil deactivates them, revokes their access and ends every active session straight away.
SCIM needs an IdP that supports it. If yours doesn't, Pencil updates users and group memberships each time they sign in with SSO instead.
SCIM works per subscription. If your organisation has more than one Pencil subscription, set up SCIM separately for each one.
To start, turn on SCIM in the SCIM section of the Single sign-on page. Then send the details shown there to your IdP's IT admin. You can set up group provisioning on its own, or group and user provisioning together.
Group provisioning only
Your IT admin completes these steps in your IdP:
Add the credentials. Open the Pencil application and enter the SCIM credentials from Pencil.
Assign groups. Assign the groups you want available in Pencil to that application.
Enable group provisioning. Leave user provisioning off for now.
Start the sync. Your IdP sends the assigned groups to Pencil.
Once the first sync finishes, the group names appear in the dropdown under Set group access. The sync runs on your IdP's schedule rather than instantly, so allow a little time. Most IdPs also offer a ‘provision on demand’ option to push a group straight away. Until then, you can still type group names by hand, so nothing is blocked.
Group and user provisioning
User provisioning lets your IdP create users in Pencil and add or remove them from workspaces as changes happen. When someone is offboarded in your IdP, they lose Pencil access automatically. Your IT admin completes these steps in your IdP:
Add the credentials. Enter the SCIM credentials from Pencil, if that isn't done yet.
Assign people. Assign the users and groups you want in Pencil to the application.
Enable user provisioning. Switch it on alongside group provisioning.
Start the sync. Your IdP sends the assigned users and groups to Pencil.
Rotate the SCIM secret
The SCIM client secret expires every 365 days. The Single sign-on page shows the current secret's expiry date. Before that date, click Rotate secret to get a new one.
The old secret keeps working for one hour after you rotate it. Update your IdP with the new secret within that hour.
Frequently asked questions
Will turning on SSO create duplicate users?
No, as long as each person's email address in your IdP matches the one used when they were added to Pencil by hand. They stay one team member and can sign in with SSO or with their username and password.
What does ‘Require SSO to sign in’ do?
It switches off password sign-in for anyone whose email domain matches one of your SSO email domains. Those people can then only sign in with SSO. Test SSO sign-in before you switch it on.
What happens if someone signs in with a password once SSO is required?
Their password no longer signs them in. They need to choose ‘Sign in with SSO’ on the login page instead.