Acumatica · Security

Acumatica SSO Setup with Azure AD

A step-by-step walk through setting up Acumatica Single Sign-On with Azure Active Directory — app registration, SAML/OIDC, claim mapping, and the user provisioning flow.

John Kihiu12 min read

Azure AD is the identity provider I set up most often for Acumatica clients, mostly because it's the default for any organization already on Microsoft 365 - the SSO project is frequently just "make Acumatica behave like every other Microsoft-federated app we already have." That framing is mostly right, but there are a few Azure AD-specific details that differ meaningfully from a generic SAML/OIDC setup and from how Okta behaves.

App registration: get the redirect URI and token version right the first time

Azure AD app registration for Acumatica is an OIDC confidential client - register the app in Entra ID (Azure AD's current name), configure the redirect URI to match Acumatica's SSO callback exactly (a trailing slash mismatch here is a surprisingly common source of a redirect_uri_mismatch error that looks like a bigger problem than it is), and generate a client secret for the confidential client flow. The detail that costs people real time: make sure the app registration's token configuration is issuing v2.0 tokens, not v1.0 - Acumatica's OIDC implementation expects the v2.0 token shape, and a v1.0 token's claim structure is different enough to cause opaque authentication failures that don't clearly point at the token version as the cause.

TEXT · The manifest setting that actually matters
// In the App Registration's manifest (or API permissions blade)
"accessTokenAcceptedVersion": 2

Conditional Access policies apply before Acumatica ever sees the login attempt

The advantage Azure AD has over most other identity providers for enterprise clients: Conditional Access policies (MFA requirements, device compliance checks, location-based restrictions) apply at the Azure AD layer, before a token is ever issued to Acumatica. This means Acumatica inherits the client's existing security posture - if the org already requires MFA for financial applications, you tag Acumatica's app registration into the right Conditional Access policy group and it's covered, with zero Acumatica-side configuration for the MFA enforcement itself.

Ask which Conditional Access group Acumatica should join, don't assume "default"

Organizations with mature Azure AD setups usually have multiple Conditional Access policies tiered by application sensitivity. An ERP handling financial data usually belongs in a stricter tier than the default "all cloud apps" policy - ask the client's identity team explicitly which tier Acumatica should sit in rather than accepting whatever the app registration defaults to.

Group claims into Acumatica roles, same requirement as Okta, different UI

Azure AD, like Okta, needs an explicit mapping from AD group membership to Acumatica role, configured via group claims added to the token configuration and then mapped on Acumatica's SSO settings screen. The Azure-specific wrinkle: by default, Azure AD emits group membership as GUIDs, not readable names, in the token claim. Either configure the app registration to emit group names instead of IDs (simpler to map, but breaks if a group gets renamed) or map by GUID (stable across renames, harder to read and audit six months later when someone's trying to remember which GUID was which team). I lean toward mapping by name for smaller clients and by GUID for large orgs with active group governance, where renames are common enough that GUID stability matters more than readability.

Guest users from Azure AD B2B need a deliberate decision, not a default

If the client's Azure AD tenant includes B2B guest users - contractors or partner-org staff invited in from another tenant - decide explicitly whether guests should be able to SSO into Acumatica at all, and if so, whether they get a different, more restricted default role mapping than internal employees. Leaving this undecided means guest accounts inherit whatever the default connected-application role is, which I've seen accidentally grant a contractor broader access than the internal team intended, simply because nobody thought about the guest-user case separately from the employee case during setup.

Wrapping up

Azure AD SSO on Acumatica rides on infrastructure most enterprise clients already have configured - Conditional Access, MFA, device compliance - which is the real advantage over building equivalent policy from scratch. Get the v2.0 token setting right up front to avoid an opaque authentication failure, decide deliberately whether to map roles by group name or GUID based on how actively the client's group structure changes, and don't let B2B guest users fall through to a default role mapping nobody chose on purpose.

John Kihiu
Acumatica ERP Developer · Laravel Engineer

Independent software engineer in Nairobi specialising in Acumatica customisations, Laravel backends, and tax fiscalisation integrations across East and Southern Africa.