Weave Code
Oauth2 Azure Laravel Package
thenetworg/oauth2-azure
Azure Active Directory OAuth 2.0 provider for the PHP League's OAuth client. Adds Azure AD and Microsoft Graph support, authorization code flow, on-behalf-of tokens, logout, B2C, and certificate-based auth.
thenetworg/oauth2-azure provides Azure Active Directory support for the PHP League's OAuth 2.0 Client. It lets PHP and Laravel applications authenticate users and request access tokens using Azure AD, with client secrets or certificate key pairs.
Key capabilities include:
- Authorization Code Flow with custom parameters and advanced options
- On-behalf-of token exchange for calling APIs from another app
- Microsoft Graph integration and resource owner access
- Logout support and multipurpose refresh tokens
- Experimental Azure AD B2C and API protection
Frequently asked questions about Oauth2 Azure
- Is thenetworg/oauth2-azure a Laravel package with a service provider?
- No. It is a framework-agnostic provider class for the PHP League's OAuth 2.0 Client that extends AbstractProvider, so there is no service provider, config file, facade, middleware or migration. In Laravel you install it with Composer and then write your own thin wrapper: a config entry, a container binding for the Azure provider, a token store and a guard or user provider. Budget for that wrapper work separately, because it is where most of the integration effort sits.
- How do I install and configure thenetworg/oauth2-azure in a Laravel app?
- Run composer require thenetworg/oauth2-azure, then construct TheNetworg\OAuth2\Client\Provider\Azure with clientId, clientSecret (or a certificate pair), redirectUri, scopes and an explicit defaultEndPointVersion. Put those values in config/services.php and read them from .env so credentials never live in code. On the Azure side you need an app registration with the same redirect URI and API permissions granted with admin consent. Bind the provider as a singleton in a service provider so you are not rebuilding it on every request.
- Do I need Laravel Socialite to use Azure AD login, or can I use this package directly?
- You can use this package directly and skip Socialite entirely; Socialite is only convenient if you want its guard helpers and driver conventions. With oauth2-azure you manage the redirect, callback and state handling yourself through the League provider methods getAuthorizationUrl, getAccessToken and getResourceOwner. Many teams write a small controller plus a guard that wraps those calls. If you would rather not own that glue, a Socialite Azure driver is a common alternative.
- What is the difference between the v1.0 and v2.0 Azure AD endpoints in this provider?
- v1.0 uses the resource parameter and issues tokens scoped to a specific resource URI, while v2.0 uses scopes and the /.default convention, and the provider handles both semantics. Set defaultEndPointVersion explicitly in the constructor instead of relying on the default, and document the choice. Azure AD is now Entra ID and Microsoft guidance has moved toward v2.0, so treat v1.0 behaviour as legacy. Mixing the two in one app is a common source of confusing consent and audience errors.
- How do I call Microsoft Graph with thenetworg/oauth2-azure?
- Request Graph scopes such as https://graph.microsoft.com/.default or the delegated User.Read scope at authorization time, then use getAuthenticatedRequest against the Graph root URI helper, or call the provider's resource owner methods. For collections, getObjects follows @odata.nextLink so you can page through users, groups or mail without writing your own loop. The provider returns PSR-7 responses through Guzzle, so decode JSON yourself or wrap the calls in a small Graph client. Application permissions (client credentials) and delegated permissions use different grants, so pick the right one for your job.
- Is validateAccessToken() safe for protecting my own API?
- Treat it as unverified until you read the source and test it. The README advertises API protection behind a bearer token but does not state whether the method performs full signature verification against Azure's JWKS and validates iss, aud, exp and nbf, and its wording about feeding it an id token is a red flag. Do not make it the only gate on a production API without a negative test suite covering expired tokens, wrong audience, wrong issuer, alg none and tampered payloads. Microsoft's own libraries or a dedicated JWT verifier are a safer primary control, with this provider used only for the OAuth flow.
- Can I authenticate with a client certificate instead of a client secret?
- Yes, the provider accepts clientCertificatePrivateKey and clientCertificateThumbprint as an alternative to clientSecret. That removes the shared secret from your environment variables and lets you rotate credentials through certificate lifecycle management. The trade-off is that certificate expiry becomes a new failure mode you must monitor, because authentication will simply start failing when it lapses. Store the private key securely and load it from a path or secret manager rather than committing it.
- Does thenetworg/oauth2-azure support B2C, refresh tokens and on-behalf-of?
- The provider includes a jwt_bearer grant shortcut for on-behalf-of token exchange, getLogoutUrl for sign-out, and experimental B2C plus multipurpose refresh token support. The experimental features are explicitly labelled as not fully tested, so adopting them means shared ownership of that code path. Refresh-token rotation and on-behalf-of flows are where subtle bugs show up as intermittent production auth failures instead of clean errors. If you need B2C at scale, budget time for your own integration tests around token refresh.
- How should I test Azure AD authentication in a Laravel test suite?
- Because the provider talks HTTP through Guzzle, you can inject a mock handler and return canned token and user responses without hitting Azure. Keep the client ID, secret, redirect URI and endpoint version in config so tests can override them cleanly. Assert your callback controller handles state mismatch, denied consent and failed token exchange, not just the happy path. For the user-linking and guard logic, use factories and feature tests rather than mocking the provider everywhere.
- Is thenetworg/oauth2-azure actively maintained, and are there alternatives?
- It is a small-maintainer project with roughly a few hundred GitHub stars, so downstream adoption is not a strong proxy for battle testing; recent releases and a changelog are positive signals but plan for a local fork. Alternatives include a Laravel Socialite Azure or Entra ID driver, Microsoft's official MSAL libraries, or using league/oauth2-client with your own Azure provider. For pure login, Socialite is less work; for Graph, on-behalf-of or certificate credentials, this provider gives you more surface out of the box. Whichever you choose, pin the endpoint version and keep the wrapper thin so swapping is cheap.
Weaver
How can I help you explore Laravel packages today?