Register an Office Add-in that uses SSO with the Azure AD v2.0 endpoint
This article explains how to register an Office Add-in with the Azure AD v2.0 endpoint. You need to register the add-in when you begin developing it. 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.
|A human readable name for the add-in. (Uniqueness recommended, but not required.)||
|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
|The permissions to AAD and Microsoft Graph that your add-in needs. (
Navigate to the Azure portal - App registrations page to register your app.
Sign in with the admin credentials to your Microsoft 365 tenancy. For example, MyName@contoso.onmicrosoft.com.
Select 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 and personal Microsoft accounts (e.g. Skype, Xbox, Outlook.com).
- Leave Redirect URI empty.
- Choose Register.
On the $ADD-IN-NAME$ page, copy and save the values for the Application (client) ID and the Directory (tenant) ID. You'll use both of them in later procedures.
This ID is the "audience" value when other applications, such as the Office host 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.
Select Certificates & secrets under Manage. Select the New client secret button. Enter a value for Description then select an appropriate option for Expires and choose Add. Copy the client secret value immediately and save it with the application ID before proceeding as you'll need it in a later procedure.
Select Expose an API under Manage. Select the Set link to generate the Application ID URI in the form "api://$App ID GUID$". Insert the $FQDN-WITHOUT-PROTOCOL$ (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form
api://$FQDN-WITHOUT-PROTOCOL$/$App ID GUID$; for example
You may get an inaccurate error at this point saying "The application ID URI must be a valid URI starting with HTTPS, API, URN, MS-APPX. It must not end in a slash." If the ID meets the stated conditions, ignore the error and save your change.
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.)
Select the Add a scope button. In the panel that opens, enter
access_as_useras the Scope name.
Set Who can consent? to Admins and users.
Fill in the fields for configuring the admin and user consent prompts with values that are appropriate for the
access_as_userscope which enables the Office host application to use your add-in's web APIs with the same rights as the current user. Suggestions:
- Admin consent title: 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 title: Office can act as you.
- Admin consent description: Enable Office to call the add-in's web APIs with the same rights that you have.
Ensure that State is set to Enabled.
Select Add scope.
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_userappended to the end; for example,
In the Authorized client applications section, you identify the applications that you want to authorize to your add-in's web application. Each of the following IDs needs to be pre-authorized.
57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office on the web)
bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook on the web)
For each ID, take these steps:
a. Select Add a client application button then, in the panel that opens, set the Client ID to the respective GUID and check the box for
api://$FQDN-WITHOUT-PROTOCOL$/$App ID GUID$/access_as_user.
b. Select Add application.
Select Authentication under Manage. In the Redirect URIs section, select Web in the Type dropdown then set the Redirect URI value to
Select Save at the top of the form.
Select API permissions under Manage and select Add a permission. On the panel that opens, choose Microsoft Graph and then choose Delegated permissions.
Use the Select permissions search box to search for the permissions your add-in needs. The following are examples.
User.Readpermission may already be listed by default. It is a good practice not to ask for permissions that are not needed, so we recommend that you uncheck the box for this permission if your add-in does not actually need it.
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 at the bottom of the panel.