Register an Office Add-in that uses single sign-on (SSO) with the Microsoft identity platform

This article explains how to register an Office Add-in with the Microsoft identity platform so that you can use SSO. Register the add-in when you begin developing it so that when you progress to testing or production, you can change the existing registration or create separate registrations for development, testing, and production versions of the add-in.

The following table itemizes the information that you need to carry out this procedure and the corresponding placeholders that appear in the instructions.

Information Examples Placeholder
A human readable name for the add-in. (Uniqueness recommended, but not required.) Contoso Marketing Excel Add-in (Prod) N/A
An application ID which Azure generates for you as part of the registration process. c6c1f32b-5e55-4997-881a-753cc1d563b7 <application-id>
The fully qualified domain name (except for protocol) of the add-in. You must use a domain that you own. For this reason, you cannot use certain well-known domains such as azurewebsites.net or cloudapp.net. The domain must be the same, including any subdomains, as is used in the URLs in the <Resources> section of the add-in's manifest. localhost:6789, addins.contoso.com <fully-qualified-domain-name>
The permissions to the Microsoft identity platform and Microsoft Graph that your add-in needs. (profile is always required.) profile, Files.Read.All N/A

Create an app registration

Registering your application (the add-in) establishes a trust relationship between your add-in and the Microsoft identity platform. The trust is unidirectional: your add-in trusts the Microsoft identity platform, and not the other way around.

  1. Sign in to the Azure portal with the admin credentials to your Microsoft 365 tenancy. For example, MyName@contoso.onmicrosoft.com.

  2. Under Manage, select App registrations > New registration. On the Register an application page, set the values as follows.

    • Set Name to <add-in-name>.
    • Set Supported account types to Accounts in any organizational directory (any Azure AD directory - multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
    • Leave Redirect URI empty.
    • Choose Register.
  3. Copy and save the values for the Application (client) ID and the Directory (tenant) ID. You'll use both of them in later procedures.

    Note

    This ID is the "audience" value when other applications, such as the Office client application (e.g., PowerPoint, Word, Excel), seek authorized access to the application. It is also the "client ID" of the application when it, in turn, seeks authorized access to Microsoft Graph.

Add a client secret

Sometimes called an application password, a client secret is a string value your app can use in place of a certificate to identity itself.

  1. In the Azure portal, in App registrations, select your application.
  2. Select Certificates & secrets > Client secrets > New client secret.
  3. Add a description for your client secret.
  4. Select an expiration for the secret or specify a custom lifetime.
    • Client secret lifetime is limited to two years (24 months) or less. You can't specify a custom lifetime longer than 24 months.
    • Microsoft recommends that you set an expiration value of less than 12 months.
  5. Select Add.
  6. Record the secret's value for use in your client application code. This secret value is never displayed again after you leave this page.

Expose a web API

  1. Be sure you are viewing the app registration you just created.

  2. Under Manage, select Expose an API, and select the Set link. This opens a Set the App ID URI box with a generated Application ID URI in the form api://<application-id>. Insert your fully qualified domain name before the <application-id>. The entire ID should have the form api://<fully-qualified-domain-name>/<application-id>; for example, api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7.

    Note

    If you get an error saying that the domain is already owned but you own it, follow the procedure at Quickstart: Add a custom domain name to Azure Active Directory to register it, and then repeat this step. (This error can also occur if you are not signed in with credentials of an admin in the Microsoft 365 tenancy. See step 2. Sign out and sign in again with admin credentials and repeat the process from step 3.)

Add a scope

  1. Select the Add a scope button. In the panel that opens, enter access_as_user as the Scope name.

  2. Set Who can consent? to Admins and users.

  3. Fill in the fields for configuring the admin and user consent prompts with values that are appropriate for the access_as_user scope which enables the Office client application to use your add-in's web APIs with the same rights as the current user. Suggestions:

    • Admin consent display name: Office can act as the user.
    • Admin consent description: Enable Office to call the add-in's web APIs with the same rights as the current user.
    • User consent display name: Office can act as you.
    • User consent description: Enable Office to call the add-in's web APIs with the same rights that you have.
  4. Ensure that State is set to Enabled.

  5. Select Add scope.

    Note

    The domain part of the Scope name displayed just below the text field should automatically match the Application ID URI set in the previous step, with /access_as_user appended to the end; for example, api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user.

  6. In the Authorized client applications section, enter the following ID to pre-authorize all Microsoft Office application endpoints.

    • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (All Microsoft Office application endpoints)

    Note

    The ea5a67f6-b6f3-4338-b240-c655ddc3cc8e ID pre-authorizes Office on all the following platforms. Alternatively, you can enter a proper subset of the following IDs if for any reason you want to deny authorization to Office on some platforms. Just leave out the IDs of the platforms from which you want to withhold authorization. Users of your add-in on those platforms will not be able to call your Web APIs, but other functionality in your add-in will still work.

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
    • 93d53678-613d-4013-afc1-62e9e444a0a5 (Office on the web)
    • bc59ab01-8403-45c6-8796-ac3ef710b3e3 (Outlook on the web)
  7. Select Add a client application. In the panel that opens, set the Client ID to the respective GUID and check the box for api://<fully-qualified-domain-name>/<application-id>/access_as_user.

  8. Select Add application.

Add Microsoft Graph permissions

  1. Under Manage, select Authentication, then choose Add a platform.

  2. In the Configure platforms pane, select Web, and then set the Redirect URI value to https://<fully-qualified-domain-name>.

  3. Choose Configure.

  4. Under Manage, select API permissions, and select Add a permission. On the panel that opens, choose Microsoft Graph, and then choose Delegated permissions.

  5. Use the Select permissions search box to search for the permissions your add-in needs. The following are examples.

    • Files.Read.All
    • offline_access
    • openid
    • profile

    Note

    The User.Read permission may already be listed by default. It's a good practice to only request permissions that are needed, so we recommend that you uncheck the box for this permission if your add-in does not actually need it.

  6. Select the check box for each permission as it appears (note that the permissions will not remain visible in the list as you select each one). After selecting the permissions that your add-in needs, select the Add permissions button.