Manually register your app with Azure AD so it can access Office 365 APIs

Last modified: June 23, 2015

Applies to: Office 365

In this article

Register your app with Azure AD to provide access to Office 365 user data

The Office 365 API services use Azure AD to provide secure authentication to users' Office 365 data. To access the Office 365 APIs, you need to register your app with Azure AD.

If you are creating a Visual Studio project, app registration is handled for you when you add an Office 365 service to your project. Otherwise, you can manually register your app.

As part of registration, you specify whether your app is a Web application, such as an MVC or Web Forms solution, or a native app, such as a smart phone or other mobile device. Azure AD uses this information to generate resources your app will need to authenticate with Azure. For web applications, Azure generates both a client ID and app secret. For native apps, Azure generates a client ID.

After you register your app, you can configure its properties, including:

  • Specifying the app endpoint(s) Azure will use for redirection during authentication.
  • For web applications, whether to make your app available only in the Azure tenancy you registered it in, or across multiple tenancies.
  • For web applications, generating the app secret and its duration.

Once your app is registered, you can then specify which Office 365 services your app requires access to. This includes specifying the permissions level for the Office 365 APIs your app requires.

Prerequisites for registering your apps with Azure AD

To register your apps, you'll need two accounts:

  • An Office 365 business account

    If you don't have an existing Office 365 business account, there are several ways to create one. For more information, see Get an Office 365 account.

  • An Azure AD subscription associated with your Office 365 business account

    This is where you'll actually register your app. You can use an existing Azure AD tenancy, or create a new one. When you sign up for an Office 365 business account, a Microsoft Azure subscription is automatically created and associated with that Office 365 account.

    So, if you have an existing Microsoft Azure subscription, you can associate your Office 365 business account with it. If not, you'll need to create an association to the Azure subscription that was created when you signed up for your Office 365 business account.

    For more information, see Associate your Office 365 account with Azure AD to create and manage apps.

Using the Azure Management Portal to register your app

  1. Sign into the Azure Management Portal, using your Office 365 business account credentials.
  2. In the left navigation panel, select Active Directory. Make sure the Directory tab is selected, and then click on the directory name.

    A screenshot of the Azure Management Portal website. The item 'Active Directory' is selected in the left navigation pane. In the main pane, the Directory tab is selected. The name of the current directory is highlighted.

  3. On the directory page, select Applications.

    Azure AD displays a list of the applications currently installed in your tenancy.

  4. Click Add.

    A screenshot of the directory information page. In the menu bar at the bottom of the page, the New icon is highlighted.

  5. Select Add an application my organization is developing.
  6. Enter the name of your application, and specify whether it is a Web application or web API, such as an MVC or Web Forms solution, or a native app, such as a smart phone or other mobile device.

  7. Enter the appropriate app identifying information, based on whether you specified your app was a web application or native application.

    If your app is a web application, you'll be asked to specify a sign-on URL and an App ID URL.

    • The sign-on URL will be set as the reply URL for your app. The reply URL specifies the physical address of your app. Azure AD sends a token with the single sign-on response to this address.
    • The App ID URL is a unique logical identifier for your app. It does not need to resolve to an Internet address.

      If your app is a native application, you'll need to specify a redirect URL. This is the URI to which Windows Azure AD will redirect the user-agent in response to an OAuth 2.0 request. The value does not need to be a physical endpoint, but must be a valid URI. You can think of the redirect URL as a unique identifier for your app.

  8. Click the check mark to complete your app registration.

Your app is now registered with Azure AD, and has been assigned a client ID. However, there are several important aspects of your app left to configure.

Configure your app properties in Azure AD

While your app is now registered, there are several important properties you can specify which determine how your app functions within Azure AD.

For more information about Azure AD app property configuration in general, see Application Object Properties.

Find out your app's client ID

  1. In the Azure Management Portal, select your application and choose Configure in the top menu. Scroll down to Client ID.

Generate a new app secret for your web application

  1. In the Azure Management Portal, select your application and choose Configure in the top menu. Scroll down to keys.
  2. Select the duration for your client secret, and click the Save icon.

    A screenshot of the app configuration page for your app, on the Azure Management Portal website. Under the page section titled 'keys', a drop-down list is shown for selecting the duration of the new key. In the menu bar at the bottom of the page, the SAVE icon is highlighted.

    Azure displays the app secret.

  3. Click the Clipboard icon to copy the client secret to the Clipboard.

    A screenshot of the app configuration page for your app, on the Azure Management Portal website. Under the page section titled 'keys', the new client secret is now displayed. Next to the client secret, the Clipboard icon is highlighted.

    Important Azure only displays the client secret at the time you initially generate it. You cannot navigate back to this page and retrieve the client secret later.

Specify whether your web app is single or multi-tenant

For web applications, you can also configure the Azure tenancy scope of your app: whether the app should be available only within the single Azure tenancy in which you register it, or if it should be available across multiple Azure tenancies.

The default is No. You can change the tenancy scope later, if necessary.

  1. In the Azure Management Portal, select your application and choose Configure in the top menu. Scroll down to Application is multi-tenant, and select Yes or No.

Specifying the permission levels your app requires from the Office 365 API services

Finally, you'll need to specify exactly what permissions your app requires of the Office 365 APIs. To do so, you add access to the Office 365 service containing the API you require to your app, and then specify the permission(s) you need from the APIs in that service. See Office 365 application manifest and permission details for information about Office 365 permissions.

  1. In the Azure Management Portal, on the configuration page for your app, scroll to the bottom of the page and, under permissions to other applications, select Add application.

    A screenshot of the app configuration page for your app, on the Azure Management Portal website. Under the page section titled 'permission to other applications', the 'Add application' button is highlighted.

  2. Select the Office 365 service for which your app requires permissions.

    If your app requires permissions to the Office 365 Mail, Calendar, or Contacts APIs, select the Office 365 Exchange Online service.

    If your app requires permissions to the Office 365 Files APIs, select the Office 365 SharePoint Online service. (This is true if your app needs permission to access files in either SharePoint Online or OneDrive for Business.)

    1. Select the service name, and click the plus symbol to add the service.
    2. The service is then listed under the Selected column.
    3. Click the check mark icon to save your choices. A screenshot of the 'permissions to other applications' page. The available services are listed in a table. Next to the name of the selected service is a plus icon. At the far right is a column that will list the applications you add to your app. The check mark icon that you click to save your choices is highlighted at the top of the page.

      You are returned to your app's configuration page.

  3. Under permissions to other applications, click the Delegated Permissions column for each service you added, and specify the permissions your app needs.

    A screenshot of the app configuration page for your app, on the Azure Management Portal website. Under the page section titled 'permissions to other applications', the services that you just added are listed in a table. Next to the name of each application is a column titled 'Delegated Permissions'. This column displays a drop-down menu of the permissions you can request for your app from each application you added.

    These are the permissions that will be displayed to your app user when Azure prompts them to consent to your app's permission request. In general, request only the services your app actually requires, and specify the least level of permissions in each service that still enable your app to perform its functions.

    Also, be aware that permission levels are additive. There is no need to request multiple permission levels for a given API, as the more expansive permission level already includes the more restricted permission. For example, for the Mail API, the Send email as a user permission already includes the Read and write access to users' email permission.

    For more information on specific permissions, see Office 365 application manifest and permission details.

Next steps

Now, with your app registered, configured, and connected to the Office 365 services, you're ready to add code to your app that authenticates with Azure AD and accesses your user's Office 365 data.

Use the starter projects, code samples, procedural topics, and reference material listed in the next section get your app up and running.

Additional resources