Set up Microsoft Entra ID sign-in and provisioning for Aquil

This guide is for the Aquil administrator and the Microsoft Entra administrator of an organization that wants its people to sign in to Aquil with their Microsoft work accounts. It covers single sign-on, just-in-time accounts, automatic provisioning (SCIM), group rules and what happens when people leave. Everything here is included in every Aquil plan, Free included.

Plan for about an hour if one person holds both roles. Most of that is waiting for DNS.

What you need

• An Admin role in your Aquil organization. Only administrators see Settings → Single sign-on.
• Someone who can approve an application for your Microsoft Entra tenant: a Global Administrator, Privileged Role Administrator or Cloud Application Administrator.
• Access to the DNS of your e-mail domain, to add one TXT record.
• For automatic provisioning of groups: Microsoft Entra ID P1 or P2. Assigning groups to an enterprise application needs one of those licences. Single sign-on and provisioning of individually assigned users work without it.

How it works, in four sentences

Your organization proves it owns its e-mail domain with a DNS record, and an Entra administrator approves the Aquil app in your tenant. You then sign in with Microsoft once, and from that moment your Aquil organization is bound to your Entra tenant: Aquil identifies people by the tenant and their Microsoft object id, never by e-mail address alone. People sign in with the "Microsoft Entra ID" button, and automatic provisioning creates, updates and deactivates their Aquil accounts from the users and groups you assign in Entra. Aquil never receives a password or a secret from your tenant.

Step 1: verify your e-mail domain

Open Settings → Single sign-on → Verified domains, type your domain (for example example.com) and choose Add domain. Aquil shows a TXT record:

Add it at your DNS provider and choose Verify. A record added after a failed attempt can take several minutes to be seen.

Keep the record in place. Aquil checks it every day; if it disappears, the domain shows "Verified, DNS check failing" and stops being verified after 14 days in a row. Your last verified domain can't be removed while Entra ID is connected.

Verify every domain your employees' addresses use. Only addresses on verified domains can be linked, created or required to use Microsoft. Personal e-mail domains, onmicrosoft.com domains and public suffixes can't be verified.

Step 2: approve the Aquil app

Under Connect Microsoft Entra ID, an Entra administrator approves the app once for the whole tenant:

• If that's you, choose Approve with Microsoft.
• If not, choose Copy approval link and send it to your Entra administrator. The link works for 10 minutes.
• The app can also be approved from the Microsoft Entra admin center (Enterprise applications).

The consent screen names the app "Aquil-Entra-Authentication-PROD" and asks for four delegated permissions: openid, profile, email and User.Read. That lets a person sign in and lets Aquil read their own basic profile at that moment. Aquil asks for nothing else: no directory-wide read, no application permissions.

Step 3: sign in with Microsoft to finish

Choose Sign in with Microsoft and use your own Microsoft work account, the one with the same e-mail address as your Aquil account. Finish within 10 minutes of starting. Afterwards you're signed in to Aquil with Microsoft and the page shows Connected to Microsoft Entra ID.

Before you finish, decide who may sign in at all. In the Microsoft Entra admin center, open Enterprise applications → Aquil-Entra-Authentication-PROD → Properties and set Assignment required to Yes, then assign the users or groups who should use Aquil under Users and groups. Do it. A freshly approved app has Assignment required set to No, which means every account in your tenant can sign in to Aquil with Microsoft. Aquil can't change this setting for you.

Who can sign in with Microsoft now

Connecting changes nothing for people who already use a password. When someone signs in with Microsoft:

• An existing member whose Aquil address is on a verified domain is linked to their account the first time. Their role, scopes and history stay. They can keep using their password too, until you require Microsoft sign-in.
• Someone with a pending invitation joins with the invited role. An invitation to the Admin role must be accepted through the invitation link in the e-mail.
• Anyone else in your tenant is refused ("You don't have access to Aquil yet") unless you allow just-in-time sign-in or provisioning creates their account first.

Break-glass administrators and Sokigo staff accounts are never linked automatically. They link their Microsoft account themselves under Settings → Security → Link Microsoft account.

Just-in-time sign-in (optional)

Just-in-time sign-in creates an Aquil account the first time someone in your tenant signs in with Microsoft. It's off by default.

Turn it on under Just-in-time sign-in only if you don't plan to use automatic provisioning. Pick the Role for new accounts (Viewer is the safest; Admin is never offered) and keep Verified domains only on. With Assignment required set to No, just-in-time sign-in gives every account in your tenant an Aquil account at its first sign-in, so set Assignment required to Yes first.

Once automatic provisioning runs, turn just-in-time sign-in off. Accounts are then only created by provisioning, from the people you assign.

Automatic provisioning (SCIM)

Provisioning keeps Aquil in step with Entra: Entra creates accounts for the users you assign, updates names and addresses, adds and removes group members, and deactivates people you disable or unassign. Entra runs a provisioning cycle roughly every 40 minutes.

Create the token

Under Automatic provisioning (SCIM), choose Create token and give it a name, for example the name of the provisioning app. Copy the token straight away: it's shown once. Copy the Tenant URL too. It ends with ?aadOptscim062020; keep that part.

Treat the token like an administrator password. Whoever holds it can create and deactivate users in your organization and, through group rules, decide their roles. You can have two active tokens, so you can replace one without stopping provisioning. A token is valid for one year; Aquil reminds the single sign-on administrators 30, 14, 7 and 1 days before it expires.

Set up the provisioning app in Entra

Provisioning uses a separate enterprise application from the one people sign in with.

1. In the Microsoft Entra admin center, choose Enterprise applications → New application → Create your own application, and pick the option for an application you don't find in the gallery (non-gallery). Name it, for example, "Aquil provisioning".
2. Open Provisioning, set the provisioning mode to Automatic, and under Admin Credentials paste the Tenant URL and the token. Choose Test Connection and save. (In the newer provisioning view the same fields sit under New configuration.)
3. Under Mappings → Provision Microsoft Entra ID Users, change the externalId mapping from the default mailNickname to objectId. Aquil refuses users whose externalId isn't their Entra object id, because that id is how Aquil recognizes the person at sign-in. Then set Match objects using this attribute to Yes for externalId with matching precedence 1, and keep userName as precedence 2. Existing Aquil accounts are still found by user name the first time; after that, a recycled user name can't attach a new hire to a former employee's account.
4. Keep the default mail → emails[type eq "work"].value mapping. Aquil uses the work e-mail address as the login address. Addresses must be on your verified domains.
5. Under Mappings → Provision Microsoft Entra ID Groups, map objectId to externalId and match groups on it: set Match objects using this attribute to Yes for externalId with matching precedence 1, instead of displayName. Group rules use the group's object id, never its name.
6. Give each assigned group a unique display name. Aquil refuses a group whose name is already used by another provisioned group, ignoring upper and lower case (Sales and sales count as the same name). The refusal only shows in the provisioning logs.
7. Assign the same users and groups to this provisioning app as to the Aquil sign-in app. They are separate applications with separate assignments; someone assigned to only one of them either can't sign in or isn't provisioned.
8. Under Settings, keep the scope at Sync only assigned users and groups, set Provisioning Status to On and save.

Test with Provision on demand on one user before the first full cycle. You'll see the result in Entra at once and the account on Aquil's Team page.

What provisioning does to existing accounts

When Entra finds an existing Aquil member by user name, Aquil takes the account over ("adopts" it): from then on Entra keeps its name and address up to date, and group rules can decide its role. Three cases are protected:

• An account that hasn't proven it belongs to the Entra user (no Microsoft sign-in yet) can only lose access through group rules until the person signs in with Microsoft once; a higher role or new scopes wait for that sign-in. While group rules decide roles, the Team page marks such accounts Waiting for Microsoft sign-in. That keeps a former employee's account from inheriting rights through a re-used address.
• Members who signed in with Microsoft before provisioning reached them, usually the administrator who connected Entra, aren't taken over. Group rules list them under Members Microsoft Entra ID does not manage; choose Hand over to let Entra manage one of them. That can't be undone in Aquil.
• Break-glass administrators and Sokigo staff accounts are never changed by Entra.

Provisioning never fails because you're out of seats. A person Entra creates when no seat of their kind is free gets the status Waiting for a seat and is activated automatically as soon as a seat is freed or added. Aquil also tells the single sign-on administrators how many people are waiting.

Guests and external collaborators aren't provisioned: their addresses aren't on your verified domains, and their Microsoft sign-in happens in their own company's tenant. Invite them from the Team page; they sign in with their e-mail address and password.

Group rules: let Entra groups decide roles

Group rules turn group membership in Entra into roles and scopes in Aquil. They apply to the people provisioning manages.

Open Group rules, add a rule for each Entra group (pick a provisioned group, or paste its object id), choose the role it gives, the scopes it adds, and order the rules. How they're read:

• Rules are checked from the top. A member gets the role of the first enabled rule whose group they're in.
• A member gets the scopes of every rule that matches. Scopes added by hand on the Team page stay.
• A member no rule matches gets the Role when no rule matches. It's never Admin.

A rule that gives the Admin role carries a warning, and it should: anyone who can add people to that group in Entra can make them Aquil administrators.

Nothing changes until you switch on Let Microsoft Entra groups decide roles. Switching it on, saving rules while it's on, or changing the default role first shows a preview: who would change, who would become or stop being an administrator, and who keeps their role because they're the last administrator or no seat is free. Nothing is applied until you confirm.

While it's on, the role of an Entra-managed member is locked on the Team page ("Role set by the Entra group …"), and scopes they got through a group can't be removed by hand. Change their groups in Entra instead. Rules are applied when Entra changes a membership, when you save, when you choose Sync now, and every night.

If something goes wrong, switch Let Microsoft Entra groups decide roles off. Nobody's access changes, the locks lift, and you can edit roles on the Team page again. That works even when your subscription has lapsed.

When two Entra groups end up as one

If two assigned groups have the same name, Entra can link the second one to the group Aquil already has. Aquil notices, lists the group under Groups linked to two Entra groups, and the group grants nobody anything until you clear it. Fix it in this order:

1. In Entra, give each assigned group a unique name and match groups on objectId (step 5 above).
2. Choose Clear on the group in Aquil. Its current members are removed in Aquil, since some may belong to the other group.
3. In the provisioning app, restart provisioning with Clear current state, so Entra sends each group's members again.

Don't unassign or delete the second group to fix it: Entra sends that as a deletion of the one group both are linked to.

Require Microsoft sign-in

Once people sign in with Microsoft, you can require it under Require Microsoft sign-in. Then everyone with an address on a verified domain must use Microsoft; a password session is refused the next time they open Aquil. External collaborators on other domains keep their password.

Aquil only lets you turn it on when Entra ID is connected, a domain is verified and an administrator has signed in with Microsoft since the connection was made.

Before you do, exempt one or two administrators as break-glass accounts: on the Team page, open the member's menu and choose Allow password sign-in. If Microsoft sign-in stops working (an outage, or the app is removed in Entra), they can still get in and turn the requirement off. Without one, only Sokigo support can turn it off for you. If Sokigo pauses Microsoft sign-in for everyone, the requirement is suspended automatically so nobody is locked out.

Requiring Microsoft sign-in stops new password sign-ins, but API tokens, connected apps and e-mailed approval links created earlier keep working. Choose Revoke API access to revoke them for everyone on a verified domain who hasn't signed in with Microsoft yet. Exempt members are skipped.

A sign-in link for your users

Sign-in link gives you an address that opens Microsoft sign-in for Aquil directly. Share it, bookmark it, or have your Entra administrator add it to the Aquil app so it appears in Microsoft My Apps.

When people leave

With automatic provisioning, disabling, unassigning or deleting someone in Entra deactivates them in Aquil at the next provisioning cycle. Deactivation signs them out everywhere it can: their web session is refused, and their API tokens, connected apps and e-mailed approval links are revoked at once. Their documents, reports and history stay. Re-enabling or re-assigning them in Entra brings the account back. When Entra deletes the user for good, Aquil closes the account: it can't be reactivated, and a rehire gets a new account.

Without automatic provisioning, removing someone in Entra doesn't reach Aquil. Deactivate them on the Team page as well. Otherwise existing access lasts up to 3 days in the browser, 180 days for API tokens and 365 days for connected apps.

A deactivation an Aquil administrator makes on the Team page wins over Entra: Entra can't reactivate that account, and Aquil reports it back to Entra as inactive. Entra also can't deactivate your organization's last active administrator; that user shows an error in the provisioning logs instead.

60 days after deactivation, Aquil removes the person's personal data: name, e-mail address, directory attributes and sign-in methods. The account then appears as "Former member (xxxx)" everywhere, including as the author of exported documents, and can't be reactivated. The audit history is kept, so older activity entries can still mention the person.

If an administrator deactivated the person by hand, Aquil keeps their Microsoft account blocked even after those 60 days, so the lock-out holds. If the same person should get access again later, open the former member's menu on the Team page and choose Allow Microsoft account again, then invite or provision them; they get a new account. Until you do, provisioning refuses them and the provisioning card counts them under people who could not be provisioned.

Re-used addresses

Before you give a former employee's address or user principal name to someone new, make sure the former employee is deactivated in Aquil (provisioning does this when you disable or unassign them). Match users on objectId first (step 3 of the provisioning setup). Aquil refuses to let a different Entra user take over an account it already knows belongs to another Entra user, and reports "A different directory user is linked to this user" in the provisioning logs.

Changing to another Entra tenant

Moving to a new tenant (a merger, a re-platform) is a disconnect and a new connection:

1. Under Disconnect Microsoft Entra ID, tick Also reset the members' directory links and confirm with your organization's name. Members' Microsoft sign-ins and directory ids, and the groups synced from the old tenant, are removed; accounts, roles and scopes are kept. Let Microsoft Entra groups decide roles is switched off; your group rules stay.
2. Connect the new tenant (steps 2 and 3).
3. If you use group rules, update each rule to the new tenant's group object id once its groups are provisioned, then switch Let Microsoft Entra groups decide roles on again: the preview shows who would change before anything does.
4. Members are matched again by their verified e-mail address the first time they sign in with Microsoft. If someone is refused, they sign in the way they did before (password or Google) and choose Settings → Security → Link Microsoft account. Members who sign in only with Microsoft can't sign in between steps 1 and 4.

Aquil refuses the disconnect if no active administrator would still have a password or Google sign-in afterwards. Give one a password first.

Telling your users

A short message is enough. For example:

From [date], sign in to Aquil with your Microsoft work account: on the sign-in page, choose "Microsoft Entra ID", or use [your sign-in link]. Your documents and access stay the same. If you're refused, contact [IT contact]. People who leave are removed from Aquil automatically.

If you use group rules, add a line about which group gives which access.

Notifications for administrators

Single sign-on administrators get an in-app notification, and an e-mail unless they turn it off, when people wait for a seat, when provisioning needs attention (for example a refused group or a protected account Entra tried to change), when a provisioning token is about to expire, when a verified domain fails its DNS check and when Entra ID is disconnected. The e-mail switches are in Settings → Notifications: "Automatic Provisioning (Microsoft Entra ID)" and "Single Sign-On and Sign-In Methods".

What Aquil stores

For each person: their Entra tenant id and object id, user principal name, given name, family name, display name, e-mail address and, if Entra sends them, job title and department. For each provisioned group: its object id, display name and members. Aquil never asks for or stores a secret from your tenant, and it never writes names, addresses or group names to its logs.

Group names are stored as you name them. If a group's name reveals something sensitive (a health programme, a trade union), don't assign that group to the Aquil apps.

Sign-in passes through Auth0, Aquil's authentication sub-processor, which receives the tenant id, object id, user principal name, name and e-mail address of people who sign in with Microsoft. Details are in the sub-processor list and the data processing agreement.

Troubleshooting

A person is refused at sign-in

The page they land on says why. The most common cases:

Provisioning reports an error

Entra shows each failure in the provisioning logs of the provisioning app. Aquil's messages say what to fix:

The provisioning card in Aquil also counts people who could not be provisioned in the last 30 days and says what to do for each reason, including former members whose Microsoft account is still blocked ("Allow Microsoft account again").

If Entra stops provisioning after repeated errors (quarantine), fix the cause and choose Restart provisioning in the provisioning app.

Errors on Microsoft's own page

Anything else: send Sokigo support the time of the attempt and the code. We never need a password or token for that.

Disconnecting

Disconnect Microsoft Entra ID stops Microsoft sign-in for your organization and turns off the requirement, just-in-time sign-in and Let Microsoft Entra groups decide roles (switching it on again later shows the preview first). Revoke the provisioning tokens and turn provisioning off in Entra too. Members who also have a password or Google sign-in keep using it; members who sign in only with Microsoft lose access until you connect again.

Questions: support@sokigo.com.