Howdy folks,
Big news for developers: Today we're introducing a preview of new capabilities which enable you to build richer applications with lower barriers to adoption by users in organizations. Now you can:
-
Develop web site and native client applications that access APIs in Office 365 and other Microsoft services. So now you can write mobile applications for iOS, Android, and Windows that access data such as email, calendar, and files in Office 365. To access these APIs, applications use OAuth 2.0 to get access tokens from Windows Azure AD.
- Enable end users in your organization or in other organizations to access your application using their organizational account without intervention by an IT administrator. End users can even allow your application to access their data in Office 365 and other applications.
- Expose your own APIs, secured by Windows Azure AD, which can be accessed by single or multi-tenant client applications.
To learn more about this, read the documentation for the Office 365 APIs preview and the Office team's blog post about the Office 365 platform . For further technical details you can read about authentication and authorization using the preview functionality, and Visual Studio tooling that supports this. To see an example of how to use this new functionality, read the howto . If you don't already have Office 365, you can get a trial here .
To try out these new features, sign in to the Windows Azure Management Portal , and click on Active Directory in the left navigation bar. Then click on Applications, add an application, and choose "Add an application that your organization is developing."
Accessing Office 365 APIs and Other APIs from Your Applications
With today's release, you can configure your application to access data exposed by Office 365 APIs, letting you build richer applications with more compelling user experiences. For example, if you're writing a travel application for organizations, you can configure your application to access an Office 365 API that enables it to add a just-booked trip to the user's Outlook calendar. You can find this new experience on the Configure page of your registered application in the Windows Azure Management Portal , as shown in Figure 1.
Fig 1. Selecting permissions that an application requires to access other applications
This configuration drives the consent experience that individual users or administrators see when either using or acquiring your application for the first time. Once a user grants permission, your application will be able to call into the Office 365 APIs authorized by the user, as long as the user also has access to those resources. This is because Office 365 trusts AD to tell it which user is accessing this data, and to allow the request only when permission has been granted for your application to access this data.
This functionality works not just with Office 365 APIs, but with any API that secures resources using Windows Azure AD. You can even secure your own API – more on that, below.
User Consent and Application Management
Many compelling applications focus on the needs of individual users within organizations, either as the core of what they do, or as a scoped-down offering from a multi-user solution involving collaboration with other users in the organization. Today we're offering a preview experience by which end users in an organization can grant permission for an application to access their personally-scoped resources in other applications. So for example, an end user could grant permission for an application to access their calendar or their contact list in Office 365. This unblocks you from developing applications that access data in Office 365 and other apps, without requiring a privileged user in IT to get involved as gatekeeper when users in their organization want to try using your application.
Fig 2: End user experience to grant an application access to their data
When a user consents to your web application, the application is visible on their Access Panel at https://myapps.microsoft.com . From the Access Panel the user can see the tile for your application, click on the tile to sign in to your application, or manage the permissions that your application has to access their data.
Fig 3: End user seeing an application on their Access Panel
Administrator Consent for Access to Organizational Resources
For a multi-tenant web site application that requires higher privilege access to resources, such as reading and writing to the directory, a global administrator for your customer's Windows Azure AD will need to consent to your application. This experience can be seen below.
Fig 4: Administrator experience to grant an application access to organizational resources
When an administrator grants consent (through the admin consent page shown above), they do so on behalf of their organization. Then when users in that organization access your application, they will be able to sign in without any access-granting experience because their administrator has already consented on their behalf.
As part of your application's acquisition or registration flow, you can choose, based on a querystring parameter to the authorize endpoint, whether to allow:
-
users to sign up for themselves (in which case they'll see the user consent experience), or
-
administrators to sign up for their organization (in which case they'll see the administrator consent experience), or
-
both.
Exposing your Web API to Other Applications
You can write your own APIs and expose your permission scopes to other application developers as first-class peers of the Office 365 APIs. You can do this by using another new preview experience by which you can download and upload a JSON file representation of your application's identity configuration – known as the "application manifest". Exposing your permissions scopes can be done through the Windows Azure Management Portal, by clicking on the "Application Manifest" command bar button when viewing your application, downloading the application manifest, editing the "appPermissions" node in the manifest file (see below for an example of exposing a travel policy permission), and then uploading it, to re-configure your application.
Fig 5: managing the application manifest in the Windows Azure Management Portal
"appPermissions": [
{
"claimValue": "policy.write",
"description": "Set the travel policy for your organization",
"directAccessGrantTypes": [],
"displayName": "Set policy for travel",
"impersonationAccessGrantTypes": [
{
"impersonated": "User",
"impersonator": "Application"
}
],
"isDisabled": false,
"origin": "Application",
"permissionId": "b69ee3c9-c40d-4f2a-ac80-961cd1534e40",
"resourceScopeType": "Global",
"userConsentDescription": "Set policy for travel",
"userConsentDisplayName": "Set policy for travel"
}
],
Then client application developers can configure their applications to request access to your APIs.
Fig 6: Selecting permissions that a native client application requires to access other applications
Then when a user signs up or begins using that client application, they'll see a consent experience which lets them grant permission for the client application to access your API on behalf of the user or their organization (see below). After consent, as part of a client application's request to your web API, it receives an access token (JWT) where the "scp" claim will contain the permissions that the user or organization granted to the client application. For the example above, if the user granted "Set policy for travel", the "scp" claim would contain the "Policy.Write" value.
Fig 7: Consent experience for an application that consumes permissions in an API
If you're building a multi-tenant web API we'll have additional functionality and additional guidance in the coming weeks that will make it easier to design and implement your solution.
Expanded Capabilities for Native Client Applications
With this release we're expanding the capabilities of native client applications to use Windows Azure AD. First, native client applications can be configured to access all the same APIs that web applications can access, including Office 365 APIs, Windows Azure AD, other Microsoft APIs, your own APIs, and APIs exposed by other API developers. So now you can write a native client application that:
-
enables users to sign on with their organizational account in Windows Azure AD
-
accesses, say, Office 365 to get a user's calendar data, and
-
access your own API to provide resources specific to the requirements of your application
All of this secured by a single authorization model that relies on the user's identity in Windows Azure AD.
When a user installs your native client application and uses it for the first time, they'll be asked to sign on to Windows Azure AD, which authenticates the user. Then, if it's the first time the user has accessed the application, they'll have a consent experience where they grant permission for your application to access APIs on their behalf. Your application can store this consent so the user doesn't need to re-consent each time they open your application.
Fig 8: Consent experience in a native client application
With this release, if your native client application calls only Microsoft APIs, you can distribute your native client application for use by other organizations. So now, not only can you offer a multi-tenant web application for use by your customers, now you can also offer a native client application for use by external organizations. In the near future we plan to make it possible for you to distribute your native client applications to other organizations even if they call APIs that you develop.
Next Steps
Try out these preview experiences and let us know what you think! In the next weeks and months we will be working to improve the experiences for developers, IT Pros, and end users within organizations, both to streamline the process for completing related tasks at all phases of the application lifecycle, and to broaden the scenarios that Windows Azure AD can support. As always, you can ask questions or give us feedback in the Windows Azure AD Forum .
Best Regards,
Alex Simons (twitter: @Alex_A_Simons)
Director of Program Management
Active Directory Team