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 data
- Prerequisites for registering your apps with Azure AD
- Using the Azure Management Portal to register your app
- Configure your app properties in Azure AD
- Specifying the permission levels your app requires from the Office 365 API services
- Next steps
- Additional resources
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
- Sign into the Azure Management Portal, using your Office 365 business account credentials.
In the left navigation panel, select Active Directory. Make sure the Directory tab is selected, and then click on the directory name.
On the directory page, select Applications.
Azure AD displays a list of the applications currently installed in your tenancy.
- Select Add an application my organization is developing.
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.
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.
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
- 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
- In the Azure Management Portal, select your application and choose Configure in the top menu. Scroll down to keys.
Select the duration for your client secret, and click the Save icon.
Azure displays the app secret.
Click the Clipboard icon to copy the client secret to the Clipboard.
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.
- 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.
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.
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.)
- Select the service name, and click the plus symbol to add the service.
- The service is then listed under the Selected column.
Click the check mark icon to save your choices.
You are returned to your app's configuration page.
Under permissions to other applications, click the Delegated Permissions column for each service you added, and specify the permissions your app needs.
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.
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.