From b6f25a691f8be73c72d5705748518e92bfca0f64 Mon Sep 17 00:00:00 2001 From: max furman Date: Fri, 24 Jul 2026 18:35:53 -0700 Subject: [PATCH] Map Entra email attribute through Coalesce, not mail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Entra SCIM tutorial told readers to leave `emails[type eq "work"].value` at its default Direct mapping from `mail`. Microsoft documents that `mail` "is only populated if the user has a Microsoft Exchange Mailbox," and that Entra skips null attributes rather than sending them, so users without a mailbox sync into Smallstep with no email address at all. SSO login matches users by email, so those users appear correctly provisioned in the directory but cannot sign in — they get "You are not authorized to access this account," which also wrongly suggests email/password as a fallback that directory users do not have. Map the attribute through `Coalesce([mail],[userPrincipalName])` instead — Microsoft's own documented example for exactly this case — and link the reference docs. Also note that mapping changes require Restart provisioning to reach already-synced users, and add a troubleshooting entry for the sign-in failure. The screenshot in graphics/entra-id-mappings.png still shows the `mail` mapping; the text now calls that out until it can be retaken. Co-Authored-By: Claude Opus 5 (1M context) --- tutorials/sync-entra-id-users-to-smallstep.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tutorials/sync-entra-id-users-to-smallstep.mdx b/tutorials/sync-entra-id-users-to-smallstep.mdx index 6494b85c..e14f0bfc 100644 --- a/tutorials/sync-entra-id-users-to-smallstep.mdx +++ b/tutorials/sync-entra-id-users-to-smallstep.mdx @@ -96,9 +96,12 @@ The following provisioning features are supported: Most of these are part of the default mappings. - The only one you will need to customize is: + Two of them need to be customized: - `externalId` should map to `objectId`. This is a unique ID representing the user that is not reusable. + - `emails[type eq "work"].value` should map to the expression [`Coalesce([mail],[userPrincipalName])`](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/functions-for-customizing-application-data#coalesce). Entra maps this attribute to `mail` by default, including in the screenshot above; change the **Mapping type** from **Direct** to **Expression** to replace it. + + > **Why not map `emails[type eq "work"].value` straight to `mail`?** Microsoft [documents](https://learn.microsoft.com/en-us/entra/identity/saas-apps/atlassian-cloud-provisioning-tutorial#connector-limitations) that the `mail` attribute "is only populated if the user has a Microsoft Exchange Mailbox," and Entra [skips null attributes](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/known-issues#null-attribute-cant-be-provisioned) rather than sending them. Users without a mailbox — contractors, service accounts, shared and bot accounts — therefore sync to Smallstep with no email address at all. Smallstep matches SSO logins by email address, so those users appear in your directory looking correctly provisioned, but signing in fails with "You are not authorized to access this account." `Coalesce` falls back to `userPrincipalName`, which every user has, so nobody syncs without an email address. 4. Remove any other default attributes that are not in the list above. The only attributes you need to send to Smallstep are: - `userName` @@ -109,6 +112,7 @@ The following provisioning features are supported: - `externalId` 5. Save your user attribute mappings. 6. Change "Provisioning Status" to "On", and save the settings. +7. If you changed a mapping on a configuration that had already synced users, choose **Restart provisioning** in the Provisioning panel. Entra only sends users it considers changed, so users that synced under the old mappings are not re-sent otherwise. To check the new mapping against a single user first, use **Provision on demand**. It may take up to 40 minutes to enable provisioning. @@ -124,3 +128,5 @@ It may take up to 40 minutes to enable provisioning. > **Don't see your users and groups?** Microsoft's SCIM service may add a 40-minute delay after you set it up. You can force an update by clicking **Restart provisioning** in the Provisioning panel. Even then, it may take a minute to sync with Smallstep. +> **A synced user can't sign in with SSO?** If a user reaches Smallstep after signing in to Entra but is told "You are not authorized to access this account," check that user in the Users tab. If they have no email address listed, they were provisioned without one and Smallstep can't match them to the account they signed in with. Correct the `emails[type eq "work"].value` mapping in [Step 5](#step-5-adjust-user-attribute-mappings), then **Restart provisioning**. +