Skip to content

Latest commit

 

History

History
121 lines (78 loc) · 11.6 KB

secured-web-api-design.md

File metadata and controls

121 lines (78 loc) · 11.6 KB
Raw

Secured Web API Design

Table of Contents

Scenario

In this Azure Communication Services Authentication Server sample, we would protect custom Web APIs using the Microsoft Identity Platform. The Web API, supporting authenticated users with personal Microsoft accounts as well as work and school accounts, will be protected using Azure Active Directory OAuth Bearer Authorization. Further on the API will also call a downstream API (Microsoft Graph) on-behalf of the signed-in user to provide additional value to its apps.

Overview

This sample demonstrates how to call a Node.js web API, protected by Azure Active Directory using the OAuth 2.0 Authorization Code Grant flow. The web API then calls the Microsoft Graph API using the OAuth 2.0 On-Behalf-Of flow. The web API's call to Microsoft Graph is made using the Microsoft Graph SDK.

Developers who wish to become more familiar with programming using Microsoft Graph are advised to go through the An introduction to Microsoft Graph for developers recorded session, and also make requests and see responses against the Microsoft Graph using Microsoft Graph explorer.

As displayed in the Azure Communication Services Authentication Server flow diagram below, the secured Web API contains two parts:

  1. Authenticate users to call a Web API through Authorization Code Grant flow (Client side) - This is outside of the scope for sample solution, however there are necessary tools provided for testing which can be learned from deployment section.
  2. Make authenticated requests by a Web API to call a downstream API through On-Behalf-Of flow (Server side)

Client Side (Steps 1&2 in below dagram):

  1. Signs-in users using the Microsoft Authentication Library for JavaScript (MSAL.js).
  2. Acquires an access token for the Web API using the Authorization Code Grant flow.
  3. Calls the Nodejs Web API by using the access token as a bearer token in the Authorization header of the http request.

Server Side (Steps 3&4 in below dagram):

  1. Once the user is passing the Azure Active Directory token (as would be gained on client side) in Authorization Header of the API call request, the flow acquires another access token on behalf of the signed-in user using the On-Behalf-Of flow.
  2. The Web API then uses this new access token to call downstream APIs (Microsoft Graph in this sample).

OBO Flow

Authorization Code Grant Flow (ACG Flow)

In order to gain access to protected resources, such as web APIs, the application needs to:

  • obtain an authentication code from the Microsoft identity platform authorize endpoint (https://login.microsoftonline.com/common/oauth2/v2.0/authorize),
  • redeem it for an access token using the Microsoft identity platform token endpoint (https://login.microsoftonline.com/common/oauth2/v2.0/token) and a refresh token using cross-site web requests.

The access token expires every 24 hours, and the application must request another code using the refresh token.

The OAuth 2.0 authorization code grant can be used in apps that are installed on a device to gain access to protected resources, such as web APIs. To learn more, please visit Microsoft identity platform and OAuth 2.0 authorization code flow. :information_source: It is worth mentioning that the Authorization Code Grant flow (ACG flow) is implemented on the client side which is excluded from this Azure Communication Services Authentication Server Sample. Therefore, users need to either integrate the ACG flow into their client applications or manually generate the access token via the ACG flow following our local deployment guide.

Below is a diagram and step-by-step explanation of the ACG flow for better understanding.

ACG Sequence

  1. Request an authorization code

    1. User signs in with their credentials and consents to permissions indicated in the scope query parameter through the SPA.

      If the user has not consented to any of those permissions, it will ask the user to consent to the required permissions. Details of permissions, consent, and multi-tenant apps are provided here.

    2. The user is directed to the authorize endpoint for authentication and consent grant.

    3. Once the user authenticates and grants their consent, the Microsoft identity platform will return a response containing an authentication code to the SPA at the indicated redirect_uri.

  2. Redeem a code for an access token

  3. The SPA redeems the authentication code for an access token and a refresh token using cross-site web requests through token endpoint.

    The access token expires every 24 hours, and the app must request another code using the refresh token.

  4. Once the SPA receives the access token, it can use it to call Web APIs in the Authorization header.

On-Behalf-Of Flow (OBO Flow)

In many cases, web APIs also need to make outbound requests to other downstream web APIs secured by Microsoft identity platform. To do so, web APIs can take advantage of the On-Behalf-Of flow, which allows a web API to exchange an incoming access token for another access token to be used in outbound requests.

Therefore, after authenticating on an application using the OAuth 2.0 authorization code grant flow, the application now has an access token for Web API with the user's claims and consent to access the middle-tier web API. Now, Web API needs to make an authenticated request to the downstream API (Microsoft Graph in this sample).

The OAuth 2.0 On-Behalf-Of flow (OBO flow) serves the use case where an application invokes a service/web API, which in turn needs to call another service/web API. The idea is to propagate the delegated user identity and permissions through the request chain. For the middle-tier service to make authenticated requests to the downstream service, it needs to secure an access token from the Microsoft identity platform, on behalf of the user. To learn more, please visit Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow ℹ️ It is worth mentioning that the On-Behalf-Of flow (OBO flow) is already integrated into this Azure Communication Services Authentication Server sample. Users only to need to follow our documentations in contribution guides folder to make it work.

Below is a diagram and step-by-step explanation of the OBO flow for better understanding.

OBO Sequence

  1. The application makes a request to the Web API with token A obtained from previous step via the Authorization Code Grant flow.
  2. The Web API authenticates to the Microsoft identity platform token issuance endpoint and requests a token to access the downstream API (Microsoft Graph API here).
  3. The Microsoft identity platform token issuance endpoint validates the Web API's credentials along with token A and issues the access token for the downstream Microsoft Graph API (token B) to the Web API.
  4. Token B is set by the Web API in the Authorization header of the request to the downstream Microsoft Graph API.
  5. Data from the secured resource are returned by the downstream Microsoft Graph API to the Web API and then surfaced as API response.

Community Help and Support

Use Stack Overflow to get support from the community. Ask your questions on Stack Overflow first and browse existing issues to see if someone has already asked something similar before. Make sure that your questions or comments are tagged with [azure-active-directory msal node.js].

If you find a bug in the sample, please raise the issue on GitHub Issues.

Contributing

If you'd like to contribute to this sample, please refer to our contribution guidelines.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

More Information

For more information, visit the following links: