Oauth2 Azure Laravel Package

Product Decisions This Supports

• Whether to gate enterprise SSO behind a higher tier. This package makes Azure AD (Entra ID) authorization-code flow a wiring exercise rather than a protocol project. It converts "should we sell SSO?" into a pricing/packaging question instead of an engineering-cost question.
• Multi-tenant vs. single-tenant support. The resource owner exposes getTenantId(), getUpn(), getId(), and arbitrary claims via claim($name). That is enough to decide whether you map a login to an organization, drive invitation/provisioning flows, and support customer-owned tenants — a product decision, not just an auth detail.
• How far into Microsoft's ecosystem the roadmap goes. Built-in get/post/put/patch/delete plus getObjects() (which follows odata.nextLink automatically) means Graph-backed features — calendar sync, mail-to-ticket, OneDrive attachments, directory/seat reconciliation — are incremental scope, not a new integration project.
• API and platform architecture. validateAccessToken() for inbound bearer tokens and the jwt_bearer / on-behalf-of grant let you standardize on "one identity across products and services," which affects whether you offer a public API and how you price platform access.
• Security and procurement posture. Certificate key-pair auth (instead of a shared client secret) is a checkbox that unblocks enterprise security reviews; getLogoutUrl() means you can credibly ship "sign out everywhere."
• Build vs. buy for the identity layer. This is the "buy cheaply" option: MIT-licensed, no vendor, ~1 day of integration versus weeks of OAuth plumbing. It also sets the baseline cost against which you'd justify a commercial IdP or an in-house abstraction.
• Consumer vs. business identity strategy. The B2C section (experimental) is a prompt to decide whether consumer sign-in shares this provider or gets its own path — the answer changes your data model and support burden.
• Support commitments for legacy customers. v1 vs. v2 endpoints and the resource-vs-scope differences matter if any accounts in the field still run older Azure AD app registrations.

When to Consider This Package

Adopt it when:

• You're on PHP/Composer and already use (or plan to use) the League OAuth2 Client — including Laravel Socialite, which builds on it — and need Azure AD without hand-rolling a provider.
• The requirement is not just "a login button" but login plus Microsoft Graph calls in the same session. The built-in request helpers, automatic refresh handling, and pagination are where the real leverage is; pure sign-in could be done with less surface area.
• You need on-behalf-of / JWT bearer grants, or you need to validate tokens issued to your API by a customer's own Azure AD app.
• Certificate-based credentials are a procurement requirement.
• You're comfortable owning the integration glue and isolating it behind your own auth interface.

Look elsewhere, or proceed with explicit caveats, when:

• You only need plain SSO in a Laravel app: Socialite's own Azure driver, or a thin custom provider, is less code you don't control.
• You need vendor guarantees — SLAs, deprecation notice, roadmap commitment. This is community-maintained with a modest footprint (253 stars, no listed dependents). Enterprise buyers will ask, and you should have an answer.
• Your architecture depends on the experimental sections: B2C, "Protecting your API," and multipurpose refresh tokens are explicitly labeled experimental and not fully tested. Prototype with them; don't make them load-bearing.
• You need Microsoft Graph in depth — pair this as the auth layer with an official Graph SDK rather than stretching these helpers into a full Graph client.
• You expect a first-party Laravel package (service provider, config file, auth guard, publishable migrations). You will write that adapter; budget for it.
• You can't tolerate dependency risk in a security-critical path. If so, treat this as a reviewed dependency with a pin and a documented exit, not a casual composer require.

How to Pitch It (Stakeholders)

For executives: This closes the "does it work with Microsoft?" objection that stalls deals in customer IT review. Instead of a multi-week OAuth build, it's roughly a day of integration behind our existing login, at zero license cost, with no new vendor and no lock-in — the code is MIT and we can replace it. It also unlocks the Microsoft-connected features (calendar, mail, files, directory) that upsell existing accounts. The ask is approval of the integration layer for [feature], with two guardrails: we don't build on the library's experimental features, and we keep our own thin wrapper so switching later is contained.

For engineering: It's a provider implementation for the League OAuth2 Client — we supply credentials, get tokens and claims, and call Graph. It gives us certificate auth, token validation for our own API, on-behalf-of grants, and logout URL generation for free. The trade-offs are real: community-maintained, small dependent base, and the B2C/API-protection/refresh-token features are marked experimental. Mitigation is straightforward — pin the version, wrap it in our own auth service, and test the claim-to-user mapping so a future swap is a one-file change rather than an auth rewrite.

Decision requested: Approve as the Azure AD integration layer for the stated scope, with ownership assigned to the platform team and an explicit rule that experimental APIs are not used in production paths.