User Provisioning (SCIM) connects Aligned to Microsoft Entra ID (formerly Azure Active Directory) so that Aligned accounts appear and disappear automatically as people join and leave your organization. SCIM stands for System for Cross-domain Identity Management, the standard that identity providers such as Microsoft Entra ID and Okta use. Assign someone to Aligned in Entra and Aligned creates their account with the role you mapped, remove them and Aligned cuts their access immediately, moving their rooms and content to a colleague you choose. User Provisioning (SCIM) requires Single Sign-On (SSO) on your Aligned account first.
Prerequisites
Plan: Enterprise
Role: Admin
Technical: Single Sign-On (SSO) configured on your Aligned account. Without Single Sign-On, your identity provider has nowhere to accept the connection values.
Technical: Admin access in both Aligned and Microsoft Entra ID.
1. User Provisioning (SCIM) vs. Single Sign-On (SSO)
User Provisioning (SCIM) and Single Sign-On (SSO) solve different problems, and you configure them separately. Single Sign-On controls how people log in to Aligned. User Provisioning controls whether an Aligned account exists at all. Configure Single Sign-On first, because User Provisioning depends on it.
User Provisioning (SCIM) | Single Sign-On (SSO) | |
Best for | Creating and removing accounts automatically as staff join and leave | Letting people sign in to Aligned with your company credentials |
Key difference | Manages account lifecycle and roles | Manages authentication only |
Available on | Enterprise only | Enterprise only |
2. Setting up User Provisioning
Setting up User Provisioning (SCIM) with Microsoft Entra ID takes six tasks:
Copy two values from Aligned.
Choose who gets a leaver's content.
Create the Aligned application in Entra and paste the two values into it.
Map your roles.
Turn on notifications and start provisioning.
Confirm the connection works.
Generating a new API token, in 2.2, is only needed if the original was never copied or has been lost.
2.1 How to get your connection details from Aligned
Your connection details are the SCIM connector base URL and the API token, and both live in the Aligned Admin Center. You open the Admin Center from the menu under your name in the bottom-left corner of Aligned.
Click your name in the bottom-left corner, then navigate to Admin Center → Security.
Locate User provisioning (SCIM).
Click Enable.
Click Copy next to the SCIM connector base URL. This value is not a secret, so you can copy it at any time.
Click Copy next to the API token and store it somewhere safe before you continue.
Copy the API token before you refresh or leave the page. Each token can be copied once: after you copy it the button changes to Generate new token, and refreshing the page without copying loses the value too. Generating a new token gives you a fresh value with its own Copy button - see 2.2.
The same window also holds When someone is removed, move their content to. Set that before you leave Aligned - see 2.3 below.
2.2 Managing your API token
How to generate a new API token
Generate a new API token when nobody copied the original, when the original was lost, or when your security policy requires rotation.
Click your name in the bottom-left corner, then navigate to Admin Center → Security → User provisioning (SCIM).
Click Enable to reopen the connection window.
Click Generate new token.
Read the confirmation and click Generate new token again to confirm.
Click Copy next to the new API token.
Paste the new API token into Entra and save.
The previous API token stops working the moment you generate a new one, and user provisioning pauses until you paste the new token into Entra. Generating a new token never removes anyone: accounts Aligned already created stay exactly as they are.
2.3 How to choose who gets a leaver's content
Choosing who gets a leaver's content means picking one person to receive everything a removed user owned. Aligned fills this field with the Account Owner by default. Wire and invoice accounts have no Owner, so Aligned picks one of the account Admins instead. You can change it to any other user on your account.
Locate When someone is removed, move their content to in the Connect your identity provider window.
Click the field to open the dropdown, then select any user who already has an Aligned account.
Click Done.
You can only choose someone who already has an Aligned account. This field does not create new users.
Set this before you assign any groups. The person you choose gets the leaver's rooms, room templates, tab templates, Library content, and shared files.
2.4 How to connect Microsoft Entra ID
Connecting Entra means creating the Aligned application yourself, pasting both values into its provisioning settings, and letting Entra test the connection. Aligned is not in the Entra gallery, so you add it as your own application.
Navigate to Entra ID → Enterprise apps → + New application → + Create your own application.
Name it Aligned.
Choose integrate any other application you don't find in the gallery.
Click Add.
In your new application, navigate to Provisioning → + New configuration.
Paste the SCIM connector base URL into Tenant URL, exactly as copied and with no trailing slash.
Paste the API token into Secret Token.
Click Test Connection.
Click Create.
Entra marks Secret Token as optional. It is not - Aligned needs the token to know which account to create users in, so fill it in.
2.5 How to map roles in Entra
Mapping roles tells Aligned which permission level to give each user. Aligned accepts three values: Admin, Manager, and User. Case does not matter. Entra sends the role from App Roles rather than from a field on the user, so the mapping has to be an expression - mapping the assignment directly does not work.
Navigate to App registrations → your Aligned app → App roles → Create app role.
Create three roles with Value set to exactly Admin, Manager, and User.
Navigate to Provisioning → Attribute Mapping → Users → Add New Mapping.
Set Mapping type to Expression.
Set the expression to
SingleAppRoleAssignment([appRoleAssignments]).Set the target attribute to
roles[primary eq "True"].value.On the same screen, turn the groups mapping off. Aligned does not import groups, so leaving it on only adds failed entries to your provisioning logs.
Navigate to Users and groups → Add user/group.
Assign each group and pick its role.
Give each person one role. Entra does not guarantee which role it sends when someone holds several, so overlapping assignments make the result unpredictable.
Send any value other than Admin, Manager, or User - including your own role names - and Aligned creates the person as a regular User. An unrecognized value never blocks account creation, and Aligned logs the exact value Entra sent so support can see it.
2.6 How to start provisioning and confirm it is working
Starting provisioning turns the connection on, and checking the Members list in Aligned confirms it worked.
Navigate to Provisioning → Overview → Properties.
Enable notification emails and enter an address for quarantine alerts.
Enable accidental deletions prevention. It stops a scoping mistake from removing everyone at once.
Navigate to Provisioning → Start provisioning.
To check one person straight away, use Provisioning → Provision on demand, search for them, and provision.
In Aligned, click your name in the bottom-left corner, then navigate to Admin Center → Members.
Confirm the assigned people appear with the role you mapped.
Note:
On credit card accounts, Aligned creates new people as Invite Sent and moves them to Active after they sign in.
On wire and invoice accounts, Aligned does the same while you still have free seats. Once they run out, the extra people are created as Pending and wait without access until you arrange more seats. They do not appear in Members until then.
3. Limitations
User Provisioning (SCIM) with Microsoft Entra ID does not support the following:
Ongoing role changes. Aligned applies roles at creation only. Moving someone to a different App Role later leaves their Aligned role unchanged.
Profile syncing in either direction. Change a name in Aligned and Aligned does not send it to Entra. Change a name in Entra and Aligned does not apply it.
Group import. Aligned receives the role Entra decided and does not recreate your group structure.
Setting the Account Owner. The Owner role ties to billing, and only Aligned can change it.
More than one API token per account. Aligned issues one token.
Pulling users. Aligned accepts pushes only.
Applying roles to people who already exist. Turning User Provisioning on leaves current Aligned accounts untouched and applies roles to newly created people only.
Instant syncing. Entra runs its provisioning cycle every 40 minutes, so changes do not appear in Aligned immediately. Use Provision on demand when you need one person now.
4. Troubleshooting & FAQ
4.1 Expected errors and blocks
Permission restriction
What this means: Enabling User Provisioning (SCIM) requires Admin access in Aligned.
How to fix it: Ask an Aligned Admin to complete the setup.
How to avoid it: Check your role in Admin Center → Members before you start.
Test Connection fails in Entra
What this means: The values in Entra do not match the values Aligned issued, the base URL carries a trailing slash, or Secret Token was left empty because Entra marks it optional.
How to fix it: Check both values against the ones Aligned issued, remove any trailing slash from the Tenant URL, and make sure Secret Token is filled in. Only if the API token was never copied or has been lost, generate a new one in Aligned and paste it in again.
How to avoid it: Paste both values in one sitting, immediately after you copy the API token.
Test Connection passes but Aligned creates nobody
What this means: Provisioning has not been started, or nobody is assigned to the Aligned application.
How to fix it: Navigate to Provisioning → Start provisioning, then confirm the person appears under Users and groups. Use Provision on demand to check one person without waiting for the next cycle.
Everyone arrives as a regular User
What this means: The App Role value is not Admin, Manager or User, or the roles expression was not set up.
How to fix it: Check that your App Roles use exactly Admin, Manager or User as their Value, and that Attribute Mapping has the
SingleAppRoleAssignment([appRoleAssignments])expression mapped toroles[primary eq "True"].value.
Someone gets a role you did not expect
What this means: The person holds more than one App Role, and Entra does not guarantee which one it sends.
How to fix it: Give each person a single App Role.
Failed group entries in your provisioning logs
What this means: The groups mapping is still on. Aligned does not accept groups, so every group push fails.
How to fix it: Navigate to Provisioning → Attribute Mapping and turn the groups mapping off.
Some people fail with "already exists" in your provisioning logs
What this means: Their email is already used by a separate Aligned account, often from a trial or another team's sign-up. Aligned rejects the request and sends an error back, which Entra shows in your provisioning logs.
How to fix it: Contact Aligned support with the affected email addresses so we can move them into your account.
The API token shows no Copy button
What this means: That token has already been copied, or the page was refreshed before anyone copied it. Each token can be copied once, and Aligned never shows the same value a second time.
How to fix it: Click Generate new token. Aligned issues a fresh token with its own Copy button - copy that one and paste it into Entra. The previous token stops working straight away.
How to avoid it: Copy the token and paste it into Entra in one sitting, before you refresh or leave the page.
Provisioning worked for weeks and then stopped
What this means: Someone generated a new API token in Aligned and never pasted the new value into Entra. The old token stops working the moment a new one is created.
How to fix it: Check whether a new token was generated in Admin Center → Security, then paste the current token into Entra again. If the token has not changed, contact Aligned support with your account name, the time the last account was created, and the matching entries from your Entra provisioning logs.
How to avoid it: Only generate a new token when you are ready to paste it straight into Entra.
Nothing happens after you assign a large group
What this means: Entra runs its provisioning cycle every 40 minutes, and a first-time sync sends every assigned person at once.
How to fix it: Wait for the next cycle and check Admin Center → Members again, or use Provision on demand for one person. If people are still missing, contact Aligned support with your account name, the group you assigned, and the number of people in it.
4.2 FAQ
Q: Does adding a user through User Provisioning with Microsoft Entra ID cost money?
Q: Does adding a user through User Provisioning with Microsoft Entra ID cost money?
Adding a user through User Provisioning costs nothing while you have free seats. Once they run out, it depends on how you pay. Paying by card, Aligned adds a seat and bills your card straight away: assign forty people with ten free seats and you're billed for thirty more. Paying by wire or invoice, Aligned charges nothing, and the extra people are created as Pending and wait without access until you arrange more seats with Aligned.
Q: What happens when I remove a person in Microsoft Entra ID?
Q: What happens when I remove a person in Microsoft Entra ID?
When you remove a person in Entra, Aligned cuts their access immediately, moves their rooms, templates, Library content and shared files to the person you chose, and frees their seat. Links your clients already hold keep working throughout.
Q: Can I suspend someone in Aligned instead of removing them?
Q: Can I suspend someone in Aligned instead of removing them?
Aligned has no suspended state, so removing someone in Entra removes them in Aligned.
Q: What happens if someone leaves and comes back?
Q: What happens if someone leaves and comes back?
Restore them within 30 days and they keep their own settings and profile, so they skip onboarding. Their rooms, templates and content stay with the person who got them, and Aligned does not give them back automatically.
Q: Can I change someone's role in Aligned after Aligned created their account?
Q: Can I change someone's role in Aligned after Aligned created their account?
You can change a role directly in Aligned, and a later sync from Entra never overwrites it.
Q: Which details does Aligned read from Microsoft Entra ID?
Q: Which details does Aligned read from Microsoft Entra ID?
Aligned reads the person's full name and email address from Entra, and no other profile fields.
Q: Can I copy the API token more than once?
Q: Can I copy the API token more than once?
No. Each API token can be copied once. After you copy it the button changes to Generate new token, and refreshing the page without copying loses the value as well. Generating a new token gives you a fresh value with its own Copy button, which you then paste into Entra.
Q: How do I check who Aligned has created?
Q: How do I check who Aligned has created?
To check who Aligned has created through User Provisioning, click your name in the bottom-left corner of Aligned and navigate to Admin Center → Members. People waiting for a seat appear once the seat is available.
Q: How do I turn off User Provisioning, and what happens to people it already created?
Q: How do I turn off User Provisioning, and what happens to people it already created?
To turn off User Provisioning with Microsoft Entra ID, stop provisioning in Entra under Provisioning → Stop provisioning. There is no separate off switch in Aligned. People Aligned already created stay exactly as they are. From then on, anyone you remove in Entra is no longer removed in Aligned, so remove them directly in Admin Center → Members. Stop provisioning rather than unassigning everyone from the app, because unassigning people removes them in Aligned.
4.3 Security & Data Handling
Aligned stores the API token in a secured form. Once you copy it or refresh the page, Aligned cannot show the value again.
Aligned never writes back to Entra.
Aligned retains a removed person's account record for 30 days, then removes it permanently.
4.4 Pro Tips
Turn on accidental deletions prevention before you start provisioning. A scoping mistake in Entra can unassign everyone at once, and this is what stops it reaching Aligned.
Use Provision on demand for the first person you assign. It saves waiting 40 minutes to find out whether the mapping is right.
Assign one small group first and check Admin Center → Members before you assign the rest of the organization. On credit card accounts, once your free seats run out Aligned buys and bills the extra seats immediately.
