Authenticate your app

Learn about the new Common Consent feature that has been added to Office 365 to provide a consistent consent experience for users and administrators of apps.

Last modified: June 18, 2014

Applies to: Office 365

Prerelease content Prerelease content

The features and APIs documented in this article are in preview and are subject to change. Do not use them in production.

Your feedback about these features and APIs is important. Let us know what you think. Have questions? Connect with us on StackOverflow. Tag your questions with [ms-office].

The Common Consent Framework enables web applications to access multiple workloads and resources across Office 365. For example, you can create web applications that access Microsoft OneDrive for Business files, SharePoint Lists, Exchange Calendars using Single-Sign On and an OAuth Provider.

Windows Azure Active Directory implements common consent. All user accounts, application registrations, and permissions are stored in Windows Azure AD, and it implements the OAuth protocol for authorizing access from your web application to Office 365 resources. Once your web application is registered in Windows Azure AD, administrators can grant it access to Office 365 resources or users can grant access to their own resources in Office 365.

Before an app can use Windows Azure ADfor authentication, the app must be registered with Windows Azure AD by using the Windows Azure Management Portal. This information can be found in the following topics:

Figure 1 demonstrates the flow of authentication and authorization used by a web server app

Figure 1 - Common Consent authentication flow

Common Consent Web Server App Authentication Flow

The following steps are all involved in the authentication of an app using Windows Azure AD. Two scenarios are covered:

  • An Office 365 tenant administrator grants access to a web application

  • A user grants access to their Office 365

Both scenarios are covered by the following steps as they correspond to figure 1:

  1. A user or administrator types a URL in a browser to go to a page in a particular web application.

  2. The web application page redirects to Windows Azure AD to log on and to initiate the consent dialog box.

  3. Administrator or user consent is displayed:

    1. If Administrator consent is required:

      Windows Azure AD presents a consent dialog which details what resources and level of permissions are needed for the web application to work correctly. The administrator can grant or deny the request at this point.

    2. If End user consent is required:

      If the web application only requested access to resources under control of the user, then administrator consent is not required. The user is presented with a consent dialog from Windows Azure AD. The user grants or denies access at this point.

      Depending on the requirements of the resource and the level of permission needed to access the resources, administrator consent may be required. If that’s the case, then the user will be presented with a request dialog that will ask the user to send an email to the administrator. This starts the administrator consent flow. Once the user sends the request for permissions, the administrator will receive a notification that a request has been made.

  4. Windows Azure Active Directory creates an authorization code that is sent back to the app.

  5. The app receives the authorization code.

    The app then uses the authorization code, along with the app ID, app secret, and the resource that it needs access to, to request a token for the token endpoint.

  6. Windows Azure AD then generates the access and multi-resource refresh tokens.

  7. The access token is returned to the requesting app along with a multi-resource refresh token that can be used against the token endpoint to get an access token for any other service that the application requested upon registration.

  8. The app receives the access and multi-resource refresh tokens.

  9. The app embeds the access token in the request, and then calls the resource.

  10. The resource receives the request from the app.

  11. The resource uses the token to authorize the app to access resources based on the scope of the request.

  12. When the web application needs to access another resource (for example, switching from a SharePoint call to an Exchange call), it needs a new token. The app can use the multi-resource refresh token received previously to request a new access token for the new resource from Windows Azure AD.

  13. Windows Azure AD validates the multi-resource refresh token.

  14. Windows Azure AD then creates a new access and multi-resource refresh token for the new resource (such as Exchange).

  15. The new tokens are sent back to the requesting app.

  16. The app receives the new tokens.

  17. The app calls the new resource (such as Exchange) using the new access token.

  18. The resource receives the request along with the embedded access token.

  19. The resource or service uses the new token to authorize the app to access resources based on the scope of the request.

The flow for authenticating native apps such as Office 365 clients is slightly different. The same steps are performed, but the native client does not pass a secret on the calls to the token endpoint.

Information about the application is stored in the application manifest (manifest) found in the Azure Management Portal (Portal). The format of the manifest is JSON.

With the manifest, the developer can define the APIs that his app will use and the permissions that the app will expose. You can also make these changes through the Portal.

To make modifications to the application manifest

  1. Log into the Azure Management Portal

  2. View the application definition.

  3. Download the application manifest.

  4. Open the manifest and modify it according to the needs of the app.

Scopes are used to limit access to Office 365 data to a specific level in SharePoint and Exchange. Scope information is stored in the app’s application manifest.

The following scopes are available at this time.

For SharePoint

ScopeId

Description

AllSites.Read

Allow the application to read documents and list  items in all site collections on behalf of the signed-in user.

AllSites.Write

Allow the application to edit or delete documents and list items in all site collections on behalf of the signed-in user.

AllSites.Manage

Allow the application to create or delete document libraries and lists in all site collections on behalf of the signed-in user.

AllSites.FullControl

Allow the application to have full control of all site collections on behalf of the current signed-in user.

MyFiles.Read

Allow the application to read current signed-in user's files.

MyFiles.Write

Allow the application to edit or delete current signed-in user's files.

ScopeId

Description

user_impersonation

Allows this application full access to mailboxes acting as users in the organization.

full_access

Allow this application access to all Exchange Web Services (EWS) APIs for all mailboxes in this organization.

Mail.Read

Allows this application to read messages in users' mailboxes.

Mail.Write

Allows the application to read, update, create, and delete messages in users' mailboxes.

Mail.Send

Allows the application to send messages as users in the organization.

Calendars.Read

Allows the application to read events in users' calendars.

Calendars.Write

Allows the application to read, update, create, and delete events in users' calendars.

Contacts.Read

Allows the application to read users' contacts.

Contacts.Write

Allows the application to read, update, create and delete users' contacts.

Sample of scope registration

The following code is an example of the manifest.

{
     "applicationIdentityManifestVersion": "0.1",
     "objectId": "0ac9c84d-d299-4c67-9222-22a5ddccf7f2",
     "generalProperties":[
          {
               "displayName": "Adatum Travel App",
               "homepage": "https://adatum.com",
               "availableToOtherTenants": true
          }
     ]
     "authProtocols":[
          {
               "OAuth": [
                    {
                         "appId": "f5349996-f4ba-45d8-a28c-1912207c6244",
                         "publicClient": false,
                    }
               ],
               "SAML": [
                    {
                         "logoutUrl": "https://adatum.com/signout/",
                         "samlMetadataUrl": "https://adatum.com/metadata/",
                    }
               ],
               "identifierUrls": [
                    "https://adatumisv.onmicrosoft.com/supercool"
               ]
               "replyUrls": [
                    "https://goo.com",
                    "https://localhost:44307/"
               ]
               "errorUrl": "https://adatum.com/error/"
     ]
     "requiredResourceAccess": [],
     "appRoles": […],
     "appPermissions": […]
}

To provide access to multiple resources and for the common consent integration with Office 365 to work, a multi-resource refresh token is required.

A multi-resource refresh token is simply a token issued by one resource that can then be used to authenticate a user or app to another resource regardless of where it was issued by creating new multi-resource refresh and access tokens for the new resource.

Show:
© 2014 Microsoft