There are two general approaches to building web applications today: traditional web applications that perform most of the application logic on the server, and single-page applications (SPAs) that perform most of the user interface logic in a web browser, communicating with the web server primarily using web APIs. A hybrid approach is also possible, the simplest being host one or more rich SPA-like sub-applications within a larger traditional web application.

Use traditional web applications when:

• Your application’s client-side requirements are simple or even read-only.
• Your application needs to function in browsers without JavaScript support.

Use a SPA when:

• Your application must expose a rich user interface with many features.
• Your team is familiar with JavaScript, TypeScript, ASP.net or any other scripting environment that contains Azure SSO friendly libraries for development.
• Your application must already expose an API for other (internal or public) clients.

Additionally, SPA frameworks require greater architectural and security expertise. They experience greater churn due to frequent updates and new client frameworks than traditional web applications. Configuring automated build and deployment processes and utilizing deployment options like containers may be more difficult with SPA applications than traditional web apps.

Web App Sign-in Flow

When a user navigates in the browser to a web app, the following happens:

The web app determines whether the user is authenticated. If the user isn’t authenticated, the web app delegates to Azure AD to sign in the user. That sign in will be compliant with the policy of the organization, which may mean asking the user to enter their credentials and use multi-factor authentication (sometimes referred to as two-factor authentication or 2FA).

The user is then (depending on the set up) asked to consent to the access that the client app needs. This is why client apps need to be registered with Azure AD, so that the Microsoft identity platform can deliver tokens representing the access that the user has consented to. When the user has successfully authenticated, Microsoft identity platform sends a token to the web app. A cookie containing the identity of the user associated with Azure AD’s domain is saved in the browser’s cookie jar. The next time an app uses the browser to navigate to the Microsoft identity platform authorization endpoint, the browser presents the cookie so that the user doesn’t have to sign in again. This is also the way that SSO is achieved. The cookie is produced by Azure AD and can only be understood by Azure AD.

The web app then validates the token. If the validation succeeds, the web app displays the protected page and saves a session cookie in the browser’s cookie jar. When the user navigates to another page that also requires the same type of session, the web app will know that the user is authenticated based on the session cookie.

The following sequence diagram summarizes this interaction:

Single-Page Applications (SPA)

Most modern web apps are built as client-side single-page applications. These applications might use plain JavaScript or a JS framework like Angular, Vue, React or Node and all these run in a web browser. Single-page applications differ from traditional server-side web apps in terms of authentication characteristics. By using the Microsoft identity platform, single-page applications can sign in users and get tokens to access back-end services or web APIs.

How Authorization Flows Work

The flow diagram below demonstrates the OAuth 2.0 authorization code grant (with details around PKCE omitted), where the app receives a code from the Microsoft identity platform authorize endpoint, and redeems it for an access token and a refresh token using cross-site web requests. The access token expires every 24 hours, and the app must request another code using the refresh token. In addition to the access token, an id_token that represents the signed-in user to the client application is typically also requested through the same flow and/or a separate OpenID Connect request (not shown here)

Configuring an SPA App to Authenticate Via Azure

• Step 1
  • Determine the type of sign-in flow your app will be using (implicit or authorization code); this will determine the way the application registration is set up on the Azure side.
• Step 2
  • Have UTS register your application using the proposed flow from step 1. To register your app, a redirect URL will be required. If your app is in development, you might have to use a custom configuration such as http://localhost:<port>/  where<port> is the custom TCP port number. This will be used by Azure to respond back to your application. The location has to be “web discoverable”. This means that your page must be hosted by a web server of some sort depending on your scripting environment and which can produce a well formed “return URL”.
• Step 3
  • Configure your application project. Your code should be configured to work as shown (example is for a JS based app):

 

• • If your application is designed to call a web API, we recommend that you call the acquireTokenSilent method to acquire or renew an access token before you call a web API. After you have a token, you can call a protected web API. Use the acquired access token as a bearer in an HTTP request to call any web API, such as Microsoft Graph API.
  • Coding examples: PHP and JS
• Step 4
  • Setup the UI for your SPA app. Before you can get tokens to access APIs in your application, you need an authenticated user context. You can sign in users to your application via the MSAL.js library from Microsoft or any other scripting library that supports Azure SSO for development.
  • You application can use either:
    • Pop-up window, by using the loginPopup method (JS)
    • Redirect, by using the loginRedirect method (JS)
  • The choice between a pop-up or redirect experience depends on your application flow:
    • If you don’t want users to move away from your main application page during authentication, we recommend the pop-up method. Because the authentication redirect happens in a pop-up window, the state of the main application is preserved.
    • If users have browser constraints or policies where pop-up windows are disabled, you can use the redirect method.
  • Sign-in
    • Sign-out
      • The MSAL library or any other scripting library of your choice should provide a logout method that clears the cache in browser storage and send a sign-out request to Azure Active Directory (Azure AD). After sign-out, the library can redirect back to the application start page by default.
      • Use either of these Microsoft resources for samples of how to accomplish these:
        • Tutorial: Sign in users and call the Microsoft Graph API from a JavaScript single-page application (SPA)

        • Tutorial: Sign in users and call the Microsoft Graph API from a JavaScript single-page app (SPA) using auth code flow

• Step 5
  • test your application. Once you have completed the creation of the application, you are now ready to  test the app’s functionality. In your browser, navigate to your local host’s web server and locate the index.html file and/or the Sign In button. If things are properly connected, you should get a prompt to sign in with the Microsoft identity platform. Sign-in using a test account and consent to requested permissions if applicable. If your application is working correctly, you should pass the login test and be transferred to the restricted area of your site and/or obtain extra data via the API call (depends on your design and the scope granted to your app).
• Step 6
  • Move your app to production. Once your app can  sign-in users and acquire a token to call web APIs, it is time to move to production. Enable logging to make your app is production ready and follow the Microsoft identity platform integration checklist:
    • Make sure your application requests the least privilege permissions. Only ask for permissions that your application absolutely needs, and only when you need them.
    • Maintain ownership of all your redirect URIs and keep the DNS records for them up-to-date.
    • Ensure all URIs are secure and encrypted (i.e. using https schemes).
    • Ensure that your app adheres to the terms of your organization in terms of protecting user’s identity and data and the platform.
    • Make sure the information associated with the app registration and management is up-to-date.
    • Adhere to your organization’s branding guidelines for applications.
    • Use a meaningful name and logo for your application and make sure these are representative of your organization so that users trust using it.
    • Ensure you app is not violating any trademarks.
    • Provide links to your app’s terms of service and privacy statement.