Azure Active Directory Provider for OAuth 2.0 Client

This package provides Azure Active Directory OAuth 2.0 support for the PHP League's OAuth 2.0 Client.

Table of Contents

• Installation
• Usage
  • Authorization Code Flow
    • Advanced flow
    • Using custom parameters
    • NEW - Call on behalf of a token provided by another app
  • NEW - Logging out
• Making API Requests
  • Variables
• Resource Owner
• UPDATED - Microsoft Graph
• NEW - Protecting your API - experimental
• Azure Active Directory B2C - experimental
• Multipurpose refresh tokens - experimental
• Known users
• Contributing
• Credits
• Support
• License

Installation

To install, use composer:

composer require thenetworg/oauth2-azure

Usage

Usage is the same as The League's OAuth client, using

\TheNetworg\OAuth2\Client\Provider\Azure

Authorization Code Flow

$provider = new TheNetworg\OAuth2\Client\Provider\Azure([
    'clientId'          => '{azure-client-id}',
    'clientSecret'      => '{azure-client-secret}',
    'redirectUri'       => 'https://example.com/callback-url',
    //Optional
    'scopes'            => ['openid'],
    //Optional
    'defaultEndPointVersion' => '2.0'
]);

// Set to use v2 API, skip the line or set the value to Azure::ENDPOINT_VERSION_1_0 if willing to use v1 API
$provider->defaultEndPointVersion = TheNetworg\OAuth2\Client\Provider\Azure::ENDPOINT_VERSION_2_0;
$baseGraphUri = $provider->getRootMicrosoftGraphUri(null);
$provider->scope = 'openid profile email offline_access ' . $baseGraphUri . '/User.Read';
if (isset($_GET['code']) && isset($_SESSION['OAuth2.state']) && isset($_GET['state'])) {
    if ($_GET['state'] == $_SESSION['OAuth2.state']) {
        unset($_SESSION['OAuth2.state']);
    // Try to get an access token (using the authorization code grant)
    /** @var AccessToken $token */
    $token = $provider->getAccessToken('authorization_code', [
        'scope' => $provider->scope,
        'code' => $_GET['code'],
    ]);

    // Verify token
    // Save it to local server session data

    return $token->getToken();
} else {
    echo 'Invalid state';

    return null;
}
} else {
    // // Check local server's session data for a token
    // // and verify if still valid 
    // /** @var ?AccessToken $token */
    // $token = // token cached in session data, null if not found;
    //
    // if (isset($token)) {
    //    $me = $provider->get($provider->getRootMicrosoftGraphUri($token) . '/v1.0/me', $token);
    //    $userEmail = $me['mail'];
    //
    //    if ($token->hasExpired()) {
    //        if (!is_null($token->getRefreshToken())) {
    //            $token = $provider->getAccessToken('refresh_token', [
    //                'scope' => $provider->scope,
    //                'refresh_token' => $token->getRefreshToken()
    //            ]);
    //        } else {
    //            $token = null;
    //        }
    //    }
    //}
    //
    // If the token is not found in 
    // if (!isset($token)) {
        $authorizationUrl = $provider->getAuthorizationUrl(['scope' => $provider->scope]);
    $_SESSION['OAuth2.state'] = $provider->getState();

    header('Location: ' . $authorizationUrl);

    exit;
// }

return $token->getToken();
}

Advanced flow

The Authorization Code Grant Flow is a little bit different for Azure Active Directory. Instead of scopes, you specify the resource which you would like to access - there is a param

$provider->authWithResource

resource

$provider->resource

$provider->urlAPI

Using custom parameters

With oauth2-client of version 1.3.0 and higher, it is now possible to specify custom parameters for the authorization URL, so you can now make use of options like

prompt

login_hint

php
$authUrl = $provider->getAuthorizationUrl([
    'prompt' => 'login'
]);

Logging out

If you need to quickly generate a logout URL for the user, you can do following:

php
// Assuming you have provider properly initialized.
$post_logout_redirect_uri = 'https://www.msn.com'; // The logout destination after the user is logged out from their account.
$logoutUrl = $provider->getLogoutUrl($post_logout_redirect_uri);
header('Location: '.$logoutUrl); // Redirect the user to the generated URL

Call on behalf of a token provided by another app

// Use token provided by the other app
// Make sure the other app mentioned this app in the scope when requesting the token
$suppliedToken = '';  

$provider = xxxxx;// Initialize provider
// Call this to get claims
// $claims = $provider->validateAccessToken($suppliedToken);
/** @var AccessToken $token */
$token = $provider->getAccessToken('jwt_bearer', [
    'scope' => $provider->scope,
    'assertion' => $suppliedToken,
    'requested_token_use' => 'on_behalf_of',
]);

Making API Requests

This library also provides easy interface to make it easier to interact with Azure Graph API and Microsoft Graph, the following methods are available on

provider

• get($ref, $accessToken, $headers = [])

• post($ref, $body, $accessToken, $headers = [])

• put($ref, $body, $accessToken, $headers = [])

• delete($ref, $body, $accessToken, $headers = [])

• patch($ref, $body, $accessToken, $headers = [])

• getObjects($tenant, $ref, $accessToken, $headers = [])

  This is used for example for listing large amount of data - where you need to list all users for example - it automatically follows

  odata.nextLink

  until the end.

  • $tenant

    tenant has to be provided since the

    odata.nextLink

    doesn't contain it.

• request($method, $ref, $accessToken, $options = [])

  See #36 for use case.

Please note that if you need to create a custom request, the method getAuthenticatedRequest and getResponse can still be used.

Variables

• $ref

  The URL reference without the leading

  /

  , for example

  myOrganization/groups

• $body

  The contents of the request, make has to be either string (so make sure to use

  json_encode

  to encode the request)s or stream (see Guzzle HTTP)

• $accessToken

  The access token object obtained by using

  getAccessToken

  method

• $headers

  Ability to set custom headers for the request (see Guzzle HTTP)

Resource Owner

With version 1.1.0 and onward, the Resource Owner information is parsed from the JWT passed in

access_token

Example:

php
$resourceOwner = $provider->getResourceOwner($token);
echo 'Hello, '.$resourceOwner->getFirstName().'!';

getId()

getFirstName()

getLastName()

getTenantId()

getUpn()

claim($name)

$name

Microsoft Graph

Calling Microsoft Graph is very simple with this library. After provider initialization simply change the API URL followingly (replace

v1.0

// Call a query $provider->get($provider->getRootMicrosoftGraphUri($token) . '/v1.0/me', $token); ``

After that, when requesting access token, refresh token or so, provide the

with value

in order to be able to make calls to the Graph (see more about

Protecting your API - experimental

With version 1.2.0 you can now use this library to protect your API with Azure Active Directory authentication very easily. The Provider now also exposes

validateAccessToken(string $token)

Authorization

// Obtain the accessToken - in this case, we are getting it from Authorization header $headers = getallheaders(); // Assuming you got the value of Authorization header as "Bearer [theaccesstoken]" we parse it $authorization = explode(' ', $headers['Authorization']); $accessToken = $authorization[1];

try { $claims = $provider->validateAccessToken($accessToken); } catch (Exception $e) { // Something happened, handle the error }

// The access token is valid, you can now proceed with your code. You can also access the $claims as defined in JWT - for example roles, group memberships etc. ```

You may also need to access some other resource from the API like the Microsoft Graph to get some additional information. In order to do that, there is

urn:ietf:params:oauth:grant-type:jwt-bearer

$me = $provider->get('https://graph.microsoft.com/v1.0/me', $graphAccessToken); printr($me); ``

Just to make it easier so you don't have to remember entire name for

(

), you just use short

Azure Active Directory B2C - experimental

You can also now very simply make use of Azure Active Directory B2C. Before authentication, change the endpoints using

pathAuthorize

pathToken

scope

// Specify custom policy in our authorization URL $authUrl = $provider->getAuthorizationUrl([ 'p' => 'b2c1siup' ]); ```

Multipurpose refresh tokens - experimental

In cause that you need to access multiple resources (like your API and Microsoft Graph), you can use multipurpose refresh tokens. Once obtaining a token for first resource, you can simply request another token for different resource like so:

php
$accessToken2 = $provider->getAccessToken('refresh_token', [
    'refresh_token' => $accessToken1->getRefreshToken(),
    'resource' => 'http://urlOfYourSecondResource'
]);

$provider->urlAPI

$accessToken2

$provider->urlAPI

Known users

If you are using this library and would like to be listed here, please let us know! - TheNetworg/DreamSpark-SSO

Contributing

We accept contributions via Pull Requests on Github.

Credits

• Jan Hajek (TheNetw.org)
• Vittorio Bertocci (Microsoft)
  • Thanks for the splendid support while implementing #16
• Martin Cetkovský (cetkovsky.eu]
• All Contributors

Support

If you find a bug or encounter any issue or have a problem/question with this library please create a new issue.

License

The MIT License (MIT). Please see License File for more information.