Connect Microsoft Entra ID (SSO and SCIM)

What you need

• The Application Administrator role or higher in the Microsoft Entra admin center (https://entra.microsoft.com).
• SSO (OpenID Connect) is available on the free tier of Entra ID.
• SCIM (automatic provisioning) for an app that isn’t in the gallery requires Entra ID P1 or higher (included in Microsoft 365 E3 and E5, Business Premium and others).
• The administrator of the Aiyori organization must be able to open “Settings” → “Connect your company’s identity provider” on the trainer’s screen.

You set up both SSO and SCIM on one app. Creating an enterprise application also creates an app registration with the same name. SSO is set up in the app registration, and SCIM in the enterprise application.

1. Create the app

1. Entra admin center → Entra ID → Enterprise applications → + New application → + Create your own application.
2. Enter Aiyori as the name, choose Integrate any other application you don’t find in the gallery (Non-gallery), then Create.
3. In the app’s Properties, set Assignment required? to Yes (only assigned people can log in). To put a tile in My Apps, enter https://app.aiyori.app/api/web/sso/start?code=(organization code) as the Home page URL. Then Save.

2. SSO (OpenID Connect)

1. Entra ID → App registrations → All applications → open the Aiyori app you created in section 1.
2. On Overview, note the Directory (tenant) ID and the Application (client) ID.
3. Authentication → + Add a platform → Web → enter https://app.aiyori.app/api/web/sso/callback as the redirect URI → Configure. Don’t check the two implicit grant boxes (Aiyori uses the authorization code flow with PKCE).
4. Certificates & secrets → Client secrets → + New client secret → description Aiyori, expiry 12 months recommended (24 months at most) → Add → note the Value (it’s shown only on this screen).
5. Token configuration → + Add optional claim → ID → check email → Add. If asked whether to turn on the Microsoft Graph email permission, check it and add.
6. API permissions can stay at the default User.Read (Aiyori asks only for openid email profile, so no admin consent is needed).
7. On Aiyori’s trainer screen, go to “Settings” → “Connect your company’s identity provider” → “SSO”, enter the values in the table below and press “Save”.
8. Enterprise applications → Aiyori → Users and groups → + Add user/group, and assign one person to test with.
9. If that person can go from Aiyori’s login screen → “Log in with company account” → organization code → Microsoft login → back to Aiyori, the connection works. If SCIM isn’t connected yet, register them as a learner first (with their work email address), or turn on “When someone who isn’t registered yet logs in, register them as a learner”.
10. Once you have confirmed that everyone can get in, turn on “Turn off PIN login and allow company accounts only” if you need it.

Issuer URL

https://login.microsoftonline.com/(Directory (tenant) ID)/v2.0

Client ID

Application (client) ID

Client secret

The Value you noted in step 4 (not the Secret ID)

Allowed email domains

Your company’s email domains (e.g. example.com). If people with onmicrosoft.com addresses should get in too, add that on its own line. People whose token has no email are checked by the domain of their UPN, so if your UPN domain differs from your email domain, add it as well.

When the secret expires, nobody can get in with a company account. Create a new secret before it expires and replace it on Aiyori’s screen. It helps to put the date in your IT team’s calendar.

The common, organizations and consumers issuers, and issuers without the trailing /v2.0, are refused with a reason when you save (they would let people from any tenant in). If you enter a tenant name such as contoso.onmicrosoft.com instead of the tenant ID, it’s converted to the tenant ID form when you save.

Even if your UPNs differ from your email addresses, people added through SCIM are also found by their UPN, so adding email in step 5 isn’t required. If you add people with bulk registration or automatic registration instead of SCIM, add email in step 5 (otherwise they are registered as a separate person under their UPN address).

3. SCIM (automatic provisioning)

1. In Aiyori, go to “Connect your company’s identity provider” → “SCIM”, enter Entra ID as the “Key name” and press “Create key” → note the key that appears (it’s shown only on this screen).
2. Enterprise applications → Aiyori → Provisioning → + New configuration (on the older screen, Get started → set Provisioning Mode to Automatic).
3. Under Admin Credentials, choose Bearer authentication, enter https://app.aiyori.app/api/scim/v2 as the Tenant URL, and the key from step 1 as the Secret Token.
4. Test Connection → if it succeeds, Create (or Save). Entra ID looks up one person who doesn’t exist and checks that an empty list comes back.
5. Mappings can stay at their defaults (what to check is in the table below).
6. Under Settings, keep Scope at Sync only assigned users and groups (the default). Enter your IT team’s address as the Notification Email for when sync stops, and turn on Prevent accidental deletion.
7. Under Users and groups, assign the groups that should use Aiyori (departments, hiring years and so on).
8. Send one person with Provision on demand, and check that they appear in Aiyori’s list of learners.
9. Start provisioning. The first cycle takes time depending on the number of people; after that, it syncs about every 40 minutes. Results are in the Provisioning logs.

4. Check on the day you connect

• One assigned person can get in with a company account. People who aren’t assigned are stopped on the Microsoft screen (because assignment is required).
• The person sent on demand appears as an Aiyori learner and is in their groups.
• When you unassign that person and send them on demand again, they show as “Disabled by company settings” in Aiyori and can’t log in. When you restore them, they can get in again.
• The secret’s expiry date is in your IT team’s calendar.

How Entra ID works with Aiyori

• The issuer is per tenant. Both iss and tid (the tenant ID) in the ID token must match the registered tenant, so people from other companies’ tenants can’t get in.
• Entra ID doesn’t send email_verified. Aiyori narrows things down by issuer, tenant and allowed domains, then uses the email it receives (or the UPN if there is none).
• SCIM PATCH requests with "op": "Replace" (capitalized, as are Add and Remove), the string "False", and PATCH without a path are all accepted. Bodies are application/scim+json.
• People can be looked up with filter=userName eq (the UPN, case-insensitive) or by externalId. Adding and removing group members (Add and Remove on members) is accepted.
• Sync runs about every 40 minutes. When you’re in a hurry, send people on demand.
• SCIM keys don’t expire. Once a year or so, create a new key, enter it in Entra ID, and set the old key to “Revoke” in Aiyori.
• Of the Microsoft Entra SCIM Validator checks, only one isn’t met: a GET for a deleted user returning 404. This is because Aiyori doesn’t erase records on delete but suspends the learner instead. Regular sync sends active: false when someone is unassigned, so it isn’t affected.