Signing in users with Microsoft

This document shows you how to use Identity Platform to sign in users with Microsoft. Both personal Microsoft accounts and Azure Active Directory (Azure AD) accounts are supported.

Before you begin

This tutorial assumes you've already enabled Identity Platform, and have a basic web app written using HTML and JavaScript. See the Quickstart to learn how.

Configuring Microsoft as a provider

To configure Microsoft as an identity provider:

  1. Go to the Identity Providers page in the Cloud Console.

    Go to the Identity Providers page

  2. Click Add A Provider.

  3. Select Microsoft from the list.

  4. Enter your Microsoft App ID and App Secret. If you don't already have an ID and secret, follow the steps in Quickstart: Register an app with the Azure AD v2.0 endpoint to obtain one.

    This endpoint supports both personal Microsoft accounts and Azure AD accounts. See the Microsoft identity platform (v2.0) overview to learn more about Azure AD.

  5. Configure the URI listed under Configure Microsoft as a valid OAuth redirect URI for your app.

  6. Register your app's domains by clicking Add Domain under Authorized Domains. For development purposes, localhost is already enabled by default.

  7. Under Configure your application, click Setup Details. Copy the snippet into your app's code to initialize the Identity Platform Client SDK.

  8. Click Save.

Signing in users with the Client SDK

  1. Create an instance of the OAuthProvider object, passing microsoft.com as the provider ID:

    JavaScript

    var provider = new firebase.auth.OAuthProvider('microsoft.com');
  2. Optional: Add OAuth scopes. Scopes specify what data you are requesting from Microsoft. More sensitive data may require specific scopes. Consult Microsoft's documentation to determine what scopes your app needs.

    JavaScript

    provider.addScope('mail.read');
    provider.addScope('calendars.read');
    
  3. Optional: Specify additional custom OAuth parameters. These are specific to Microsoft, and are typically used to customize the authentication experience.

    JavaScript

    provider.setCustomParameters({
      // Force re-consent.
      prompt: 'consent',
      // Target specific email with login hint.
      login_hint: 'user@firstadd.onmicrosoft.com'
    });
    

    You can use the mkt parameter to customize the language of the authentication flow. For example:

    provider.setCustomParameters({
      mkt: 'fr'
    });
    

    You can use the tenant property to limit access to users outside a particular Azure AD domain. Specify either the friendly domain name of the tenant, or its GUID identifier. Users who are not members of this domain will not be able to sign in. For example:

    provider.setCustomParameters({
      // Optional "tenant" parameter in case you are using an Azure AD tenant.
      // eg. '8eaef023-2b34-4da1-9baa-8bc8c9d6a490' or 'contoso.onmicrosoft.com'
      // or "common" for tenant-independent tokens.
      // The default value is "common".
      tenant: 'TENANT_ID'
    });
    

    See the Microsoft OAuth documentation for a full list of parameters Microsoft supports. Note that you can't pass parameters reserved by OAuth or Identity Platform.

  4. Use the OAuthProvider object to sign in the user. You can either open a pop-up window, or redirect the current page. Redirecting is easier for users on mobile devices.

    To show a pop-up, call signInWithPopup():

    JavaScript

    firebase.auth().signInWithPopup(provider).then(function(result) {
      // This gives you a Microsoft Access Token. You can use it to access the Microsoft API.
      var token = result.credential.accessToken;
      // You can also retrieve the OAuth ID token.
      var idToken = result.credential.idToken;
      // The signed-in user info.
      var user = result.user;
      // ...
    }).catch(function(error) {
      // Handle Errors here.
      var errorCode = error.code;
      var errorMessage = error.message;
      // The email of the user's account used.
      var email = error.email;
      // The firebase.auth.AuthCredential type that was used.
      var credential = error.credential;
      // ...
    });

    To redirect the page, first call signInWithRedirect():

    JavaScript

    firebase.auth().signInWithRedirect(provider);

    Then, retrieve the Microsoft token by calling getRedirectResult() when your page loads:

    JavaScript

    firebase.auth().getRedirectResult().then(function(result) {
      if (result.credential) {
        // This gives you a Microsoft Access Token. You can use it to access the Microsoft API.
        var token = result.credential.accessToken;
        // You can also retrieve the OAuth ID token.
        var idToken = result.credential.idToken;
        // ...
      }
      // The signed-in user info.
      var user = result.user;
    }).catch(function(error) {
      // Handle Errors here.
      var errorCode = error.code;
      var errorMessage = error.message;
      // The email of the user's account used.
      var email = error.email;
      // The firebase.auth.AuthCredential type that was used.
      var credential = error.credential;
      // ...
    });

Once you have an access token, you can use it to call the Microsoft Graph API For example:

REST

curl -i -H "Authorization: Bearer [ACCESS_TOKEN]" https://graph.microsoft.com/v1.0/me

Unlike other providers supported by Identity Platform, Microsoft does not provide a photo URL for users. Instead, you'll need to use the Graph API to request the binary data for the photo.

In addition to the access token, you can also retrieve a user's Microsoft ID token. The oid claim on this token contains a unique ID for the user. You can compare this against the ID located at user.providerData[0].uid. If your users are signing in with an Azure AD tenant, these fields will match exactly. If they aren't, the field will be padded with zeroes (for example, the federated ID 4b2eabcdefghijkl will appear as 00000000-0000-0000-4b2e-abcdefghijkl).

Do not use the sub claim to compare user IDs. The sub claim is app-specific, and will not match the ID used by Microsoft.

Signing in users manually

Some other Identity Platform providers, such as Google, Facebook, and Twitter, allow you to sign in users manually by calling signInWithCredential().

This capability is not supported for Microsoft. Identity Platform is not able to verify the audience of Microsoft OAuth access tokens, which is a critical security requirement.

If you can't use the Identity Platform Client SDK to sign in users, you'll need to use a third-party OAuth library to authenticate with Microsoft. You can then use Custom authentication to exchange the Microsoft credential for a custom token.

What's next