Office 365 Reporting web service

Článek
09/01/2022

The Office 365 Reporting web service enables developers to integrate information on email and spam, antivirus activity, compliance status, and Lync Online activities into their custom service reporting applications and web portals. This topic provides an overview of the REST web service, the functional architecture, the reports available, and other ways you can access the reports.

Note

A number of the reports and corresponding cmdlets that are described in this article have been deprecated. For more information, see Announcing the General Availability of Microsoft Graph reporting APIs and Email security report changes in the Microsoft 365 Defender portal.

Applies to: Office 365

Welcome to the Office 365 Reporting web service

The Office 365 Reporting web service enables developers to integrate information on email and spam, antivirus activity, compliance status and Lync Online conferences and sessions into their custom service reporting applications and web portals. All the reports available in the admin portal, within the downloadable Microsoft Excel spreadsheets, and those accessed through Windows PowerShell cmdlets, are accessible using the Reporting web service. Users accessing the Reporting web service must have administrative rights in the organization.

This topic contains the following sections:

Administrator permissions

Functional architecture

The service description document and MailFilterList report

Reports available in the Reporting web service

Get started with Reporting Web Service (Added Sept 1, 2022)

Register your application in Azure AD
Get Office 365 tenant admin consent
Request access tokens from Azure AD
Build your app

Additional resources

Administrator permissions

To be able to see the reports, you need the right permissions in Office 365. If you aren't already able to see them, ask your org's administrator to add you to one of the administrator roles. We recommend you start at the lowest-level administrator range, "Service Admin". You might also ask your administrator to create a separate administrator account that you can use just for exploring the reporting system.

The reports in the admin portal are available at: https://portal.microsoftonline.com/Reports/AllReports.aspx. There will be more data available if your organization is active and has lots of users, but even small organizations can have a lot of spam and malware in their email.

Functional architecture

The following high-level conceptual diagram gives you an idea of how the reporting system functions.

Office 365 Reporting web service architecture

The primary sources of reporting information are the Exchange Online service, Microsoft Forefront Protection services, Lync Online service, Exchange Server mailbox servers, and Active Directory Domain Services (AD DS). The various sources deposit their log information to the data mart. On the scale at which Office 365 is operating, thousands of servers can be involved feeding data to the reporting system.

Because of the huge amount of data and replication delays, it can take a while for the data to become available for reports. Typically it’s just a couple hours, but new accounts definitely lag. What that means is that the Reporting web service really isn’t intended for up-to-the-minute system monitoring. It’s more for analysis of historical resource usage.

Once the reporting data appears in the data mart, it can be returned in your requests to the Reporting web service. The Office 365 admin portal also gets data from the Reporting web service.

In addition to the Reporting web service, there are three other ways you can retrieve reports. You already know about the web service and the admin portal but you can also download a customizable spreadsheet that gets its data from the web service. And, if your situation requires the data in Windows PowerShell scripts, there are reporting cmdlets you can call by way of remote-Windows PowerShell. The four ways of retrieving reports are compared in the following table.

Ways to get the reports	Ease of use	Customizable	Getting there
Office 365 admin center predefined charts and lists	Simple, interactive status-and health-checks.	Low. Interactive filtering by date, triggered transport policy rules, and so on.	https://portal.office365.com/admin/default.aspx#AllReportsRootV2. Remember: you must be logged in to an account that has administrator rights to access the reports.
Downloadable spreadsheet	Detailed, flexible analysis of historical and live service data, for example in Microsoft Excel-based score-cards.	Medium. Updates may require reapplying customizations, and internal source code not exposed.	https://www.microsoft.com/en-us/download/details.aspx?id=30716
Reporting PowerShell cmdlets	Scripting necessary. Precise data for periodically generated reports in script-based IT maintenance tools.	High. Perfect for script-based analytical tools.	https://technet.microsoft.com/en-us/library/jj200677(v=exchg.150).aspx
REST Reporting web service	Programming required service-monitoring portals, or for scorecards requiring integration with custom and non-Office 365 services.	Very high. REST Web service provides ODATA2 query filtering and a full programming IDE in Microsoft Visual Studio.	https://reports.office365.com/ecp/reportingwebservice/reporting.svc

With four different ways to get the data, how can you be sure that all reports return the same data? The spreadsheet and the admin portal both call the Reporting web service, which in turns calls the Windows PowerShell cmdlets. You can also call those cmdlets directly. The Windows PowerShell cmdlets are the only things that access the datamart directly, which ensures that every different type of access method has the same data.

The Reporting web service is handled by the Exchange Server front-end servers in the datacenter, which has a few important effects: one is that when email access is down, the reports are often down. Also, Exchange Server has network-bandwidth protection in the form of response "throttling" that can sometimes affect the Reporting web service. But you’re unlikely to be affected by that unless you’re requesting a lot of detailed reports very quickly.

The service description document and MailFilterList report

The Reporting web service uses the organization subscription options, configuration settings, and the user's permissions to control access to the reports, and the options available in them.

Applications that access the Reporting web service need to make two initial requests from the web service. The first is the service description document, reporting.svc. That XML document tells the application which reports the authenticated user is allowed to access. If a report is present in the reporting.svc document, then the user can access it. For more details, see Office 365 Reporting web service reporting.svc document.

The second request the application usually makes retrieves the MailFilterList report, which is crucial to the functioning of custom applications. The MailFilterList report provides several categories of string values that are to be used with the other reports. For more details, see MailFilterList report.

Reports available in the Reporting web service

The following table describes the reports available in the web service. Exchange reports available in Office 365 Reporting web service and Lync reports available in Office 365 Reporting web service provide complete information.

Report	Description
ConnectionbyClientType* reports ConnectionbyClientTypeDetail* reports	The number and types of email client-access methods used by the organization's users during the reporting period. For example, Outlook Web Access, Exchange Web services, and so on. Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Email app usage reports instead.
CsActiveUser* reports	The number of active, logged-in Lync Online users during the reporting period Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Skype for Business activity reports instead.
CsAVConferenceTime* reports CsP2PAVTime* reports	The amount of time logged-in organization users participated in Lync Online conferences during the reporting period Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Skype for Business organizer activity reports, Skype for Business participant activity reports, and Skype for Business peer-to-peer activity reports instead.
CsConference* reports CsP2PSession* reports	The count of Lync Online conferences and peer-to-peer sessions during the reporting period. Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Skype for Business organizer activity reports, Skype for Business participant activity reports, and Skype for Business peer-to-peer activity reports instead.
GroupActivity* reports	Office 365 user groups created and deleted, summarized over the indicated time periods. Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Office 365 Groups activity reports instead.
MailboxActivity* reports GroupActivity* reports	Office 365 users created and deleted, summarized over the indicated time periods. Active Directory Domain Services (AD DS) replication can sometimes delay this information up to a day. Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Mailbox usage reports and Office 365 Groups activity reports instead.
MailboxUsage report MailboxUsageDetail report	Summary and detailed statistics about organization user mailboxes. Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Mailbox usage reports instead.
MailDetail report	Although this is present in the service document, it won’t return any data, so don’t call it.
MailDetailDlpPolicy report	The details about messages that have triggered Data Loss Prevention (DLP) policy rules.
MailDetailMalware report	Messages containing malware detected in incoming and outgoing emails.
MailDetailSpam report	Messages containing spam detected in incoming and outgoing emails.
MailDetailTransportRule report	Exchange Server transport rules that were used in processing individual email messages.
MailFilterList report	The defined string constants used as options when requesting the other reports.
MailTrafficPolicy report	Messages that have triggered DLP policy rules.
MailTraffic report	How much mail is sent to, and received from, domains outside the organization.
MailTrafficSummary reports	A wide selection of reports listing the top users, events, malware detected, and so on.
MailTrafficTop report	Which users have sent and received the most messages.
MessageTrace report MessageTraceDetail report	step-by-step and detailed history of how a specific email was transferred through the Office 365 systems, to help diagnose delivery problems.
MxRecordReport report	Returns current settings and status for the mailer-exchange (MX) DNS records.
OutboundConnectorReport report ServiceDeliveryReport report	Information about the current settings and status of outbound mail (send) connectors defined for the organization.
StaleMailbox report StaleMailboxDetail report	The details and summary counts of mailboxes that have not been accessed within the indicated time period. Important These reports are deprecated as of January 29, 2018. We recommend that you use the Microsoft Graph Email activity reports instead.

Get started with Reporting Web Service

When you create an application that needs access to secured services like the Reporting Web Service, you need to provide a way to let the service know if your application has rights to access it. The Reporting Web Service uses Azure Active Directory (Azure AD) to provide authentication services that you can use to grant rights for your application to access them. There are four key steps:

Register your application in Azure AD—To allow your application access to the Reporting Web Service APIs, you need to register your application in Azure AD. This allows you to establish an identity for your application and specify the permission levels it needs to access the APIs.
Get Office 365 tenant admin consent—An Office 365 tenant admin must explicitly grant consent to allow your application to access their tenant data by means of the Reporting Web Service. The consent process is a browser-based experience that requires the tenant admin to sign in to the Azure AD consent UI, review the access permissions that your application is requesting, and then either grant or deny the request. After consent is granted, the UI redirects the user back to your application with an authorization code in the URL. Your application makes a service-to-service call to Azure AD to exchange this authorization code for an access token, which contains information about both the tenant admin and your application. The tenant ID must be extracted from the access token and stored for future use.
Request access tokens from Azure AD—Using your application's credentials as configured in Azure AD, your application requests additional access tokens for a consented tenant on an ongoing basis, without the need for further tenant admin interaction. These access tokens are called app-only tokens because they do not include information about the tenant admin.
Call the Reporting Web Service—The app-only access tokens are passed to the Reporting Web Service to authenticate and authorize your application.

The following diagram shows the sequence of consent and access token requests.

Office 365 Reporting web service sequence of consent and access token requests

Register your application in Azure AD

The Reporting Web Service uses Azure AD to provide secure authentication to Office 365 tenant data. To access the Reporting Web Service, register your app in Azure AD, and as part of the configuration specify the permission levels your app needs to access the APIs.

Prerequisites

To register your app in Azure AD, you need a subscription to Office 365 and a subscription to Azure that has been associated with your Office 365 subscription. You can use trial subscriptions to both Office 365 and Azure to get started. For more details, see Welcome to the Office 365 Developer Program.

Use the Azure Portal to register your application in Azure AD

After you have a Microsoft tenant with the proper subscriptions, register your application in Azure AD.

Sign into the Azure portal using the credential of your Microsoft tenant that has the subscription to Office 365 you wish to use. You can also access the Azure Portal via a link that appears in the left navigation pane in the Microsoft 365 admin center.
In the left navigation pane, select Azure Active Directory.
On the Azure Active Directory page, in the left navigation pane select App registrations, and then select New registration.
On the App registrations page, select New registration. A new page appears for you to start the registration of your app.
On the Register an application page, do the following:
- Name your app.
- Choose who can use the app and access the API.
- Provide a redirect URL for user redirect after authentication, if needed.
Click Register to register the new app.

Configure your application properties in Azure AD

Now that your application is registered, there are several important properties you must specify that determine how your application functions within Azure AD and how tenant admins will grant consent to allow your application to access their data using the Reporting Web Service. For more information about Azure AD application configuration in general, see Application Object Properties.

Client ID. This value is automatically generated by Azure AD. Your application will use this value when requesting consent from tenant admins and when requesting app-only tokens from Azure AD.
Application is multi-tenant. This property must be set to YES to allow tenant admins to grant consent to your app to access their data using the Reporting Web Service APIs. If this property is set to NO, your application will only be able to access your own tenant's data.
Reply URL. This is the URL that a tenant admin will be redirected to after granting consent to allow your application to access their data using the Reporting Web Service. You can configure multiple reply URLs as needed. Azure automatically sets the first one to match the sign-on URL you specified when you created the application, but you can change this value as needed.

Be sure to Save after making any changes to these properties.

Generate a new key for your application

Keys, also known as client secrets, are used when exchanging an authorization code for an access token.

On the Azure Active Directory page in the Azure portal, in the left navigation pane select App registrations, and then select your application.
In the page for your app, in the left navigation pane select Certificates & secrets.
Select New client secret, in the Add a client secret pane, enter a description, and select the duration for your key, and then select Add.
After creating the client secret, the value is displayed. Copy the client secret value to the clipboard.

Important

Azure only displays the client secret value at the time you initially generate it. You can't go back to this page and retrieve the client secret value later. Be sure to copy it and save it to a secure location so you can use it later.

Configure an X.509 certificate to enable service-to-service calls

An application that is running in the background, such as a daemon or service, can use client credentials to request app-only access tokens without repeatedly requesting consent from the tenant admin after initial consent is granted.

For more information, see Service to Service Calls Using Client Credentials.

You must configure an X.509 certificate with your application to be used as client credentials when requesting app-only access tokens from Azure AD. There are two steps to the process:

Obtain an X.509 certificate. You can use a self-signed certificate, or a certificate issued by a publicly trusted certificate authority.
Modify your application manifest to include the thumbprint and public key of your certificate.

The following instructions show you how to use the Visual Studio or Windows SDK makecert tool to generate a self-signed certificate and export the public key to a base64-encoded file.

From the command line, run the following:
```
makecert -r -pe -n "CN=MyCompanyName MyAppName Cert" -b 03/15/2015 -e 03/15/2017 -ss my -len 2048
```
Note

When you generate the X.509 certificate, make sure the key length is at least 2048. Shorter key lengths are not accepted as valid keys.
Open the Certificates MMC snap-in and connect to your user account.
Find the new certificate in the Personal folder and export the public key to a base64-encoded file (for example, mycompanyname.cer). Your application will use this certificate to communicate with Azure AD, so make sure you retain access to the private key as well.

Note

You can use Windows PowerShell to extract the thumbprint and base64-encoded public key. Other platforms provide similar tools to retrieve properties of certificates.

From a Windows PowerShell prompt, type and run the following:


$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$cer.Import("mycer.cer")
$bin = $cer.GetRawCertData()
$base64Value = [System.Convert]::ToBase64String($bin)
$bin = $cer.GetCertHash()
$base64Thumbprint = [System.Convert]::ToBase64String($bin)
$keyid = [System.Guid]::NewGuid().ToString()

Store the values for $base64Thumbprint, $base64Value, and $keyid to use when you update your application manifest in the next set of steps. Using the values extracted from the certificate and the generated key ID, you must now update your application manifest in Azure AD.
In the Azure Portal, go to App registrations > All applications, select your application, and then select Manifest in the left navigation pane.
On the Manifest page, in the top navigation bar, select Download.
Open the downloaded manifest in an editor and replace the empty keyCredentials property with the following JSON:
```
  "keyCredentials": [
    {
        "customKeyIdentifier" : "$base64Thumbprint_from_above",
        "keyId": "$keyid_from_above",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value": "$base64Value_from_above"
    }
],
```
Note

The KeyCredentials property is a collection, making it possible to upload multiple X.509 certificates for rollover scenarios or delete certificates for compromise scenarios.
To upload the updated manifest, in the command bar, select Manage manifest > Upload manifest, browse to your updated manifest file, and then select it. Save your changes.

Assign Azure AD roles to the application

The supported roles for the applications to access the Reporting Web Service are:

Global Reader
Security Reader

For general instructions about assigning roles in Azure AD, see View and assign administrator roles in Azure Active Directory.

Specify the permissions your app requires to access the Reporting Web Service

Finally, you need to specify exactly what permissions your app requires of the Reporting Web Service. To do this, add access to the Reporting Web Service to your app, and then specify the permission(s) you need.

In the Azure Portal, go to App registrations > All applications, and select your application. In the API Permissions page, in the left navigation pane, select API Permissions, and then select Add a permission to display the Request API permission flyout in the right pane.
In the Request API permissions pane, on the APIs my organization uses tab, select Office 365 Exchange Online.
Select Delegated Permissions and then select Add permissions. This enables your client app to perform operations on behalf of the signed-in user, such as reading email or modifying the user's profile.
Select Application Permissions and then select Add permissions. These are permissions that enable the client app to authenticate as itself without user interaction or consent, such as an app used by background services or daemon apps.
Reporting Web Service now appears in the list of applications that your app requires permissions for. Under both Application Permissions and Delegated Permissions, if needed, select the permissions your application requires. Refer to the specific API reference for more details about each permission
Select Grant admin consent for tenant name to consent to the permissions given to your app.

Now that your application is configured with the permissions, it needs to use the Reporting Web Service. A tenant admin must explicitly grant your application these permissions to access their tenant's data using the APIs. To grant consent, the tenant admin must sign in to Azure AD using the following specially constructed URL, where they can review your application's requested permissions. This step is not required when using the APIs to access data from your own tenant.

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Foutlook.office365.com&client_id={your_client_id}&redirect_uri={your_redirect_url }

The redirect URL must match or be a sub-path under one of the Reply URLs configured for your application in Azure AD as shown in the following example:

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Foutlook.office365.com&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&redirect_uri=http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F

To test the consent URL, paste it into a browser and sign in using the credentials of an Office 365 admin for a tenant other than the tenant that you used to register the application. You’ll see the request to grant your application permission to use the Reporting Web Service.

Office 365 Reporting web service review permissions requested for your organization

Choose Accept. You’re then redirected to the specified page where there will be a code in the query string as shown in the following example:

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

Your application uses this authorization code to obtain an access token from Azure AD, from which the tenant ID can be extracted. After you have extracted and stored the tenant ID, you can obtain subsequent access tokens without requiring the tenant admin to sign in.

Request access tokens from Azure AD

There are two methods for requesting access tokens from Azure AD:

The Authorization Code Grant Flow involves a tenant admin granting explicit consent, which returns an authorization code to your application. Your application then exchanges the authorization code for an access token. This method is required to obtain the initial consent that your application needs to access the tenant data using the API, and this first access token is needed to obtain and store the tenant ID.
The Client Credentials Grant Flow allows your application to request subsequent access tokens as old ones expire, without requiring the tenant admin to sign in and explicitly grant consent. This method must be used for applications that run continuously in the background calling the APIs once the initial tenant admin consent has been granted.

Request an access token using the authorization code

After a tenant admin grants consent, your application receives an authorization code as a query string parameter when Azure AD redirects the tenant admin to your designated URL:

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

Your application makes an HTTP REST POST to Azure AD to exchange the authorization code for an access token. Because the tenant ID is not yet known, the POST will be to the "common" endpoint, which does not have the tenant ID embedded in the URL:

https://login.windows.net/common/oauth2/token

The body of the POST contains the following:

resource=https%3A%2F%2Foutlook.office365.com&amp;client_id=a6099727-6b7b-482c-b509-1df309acc563 &amp;redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &amp;client_secret={your_client_key}&amp;grant_type=authorization_code&amp;code= AAABAAAAvPM1KaPlrEqdFSB...

Sample request

POST https://login.windows.net/common/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 944

resource=https%3A%2F%2Foutlook.office365.com&amp;client_id=a6099727-6b7b-482c-b509-1df309acc563 &amp;redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &amp;client_secret={your_client_key}&amp;grant_type=authorization_code&amp;code=AAABAAAAvPM1KaPlrEqdFSB...

The body of the response will include several properties, including the access token.

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 3265

{"expires_in":"3599","token_type":"Bearer","scope":"ActivityFeed.Read ActivityReports.Read ServiceHealth.Read","expires_on":"1438290275","not_before":"1438286375","resource":"https://outlook.office365.com","access_token":"eyJ0eX...","refresh_token":"AAABAAA...","id_token":"eyJ0eXAi..."}

The access token that is returned is a JWT token that includes information about both the admin that granted consent and the application requesting access. The following shows an example of an un-encoded token. Your application must extract the tenant ID "tid" from this token and store it so that it can be used to request additional access tokens as they expire, without further admin interaction.

Sample token

{
  "aud": "https://outlook.office365.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1427246416,
  "nbf": 1427246416,
  "exp": 1427250316,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "amr": [
    "pwd"
  ],
  "oid": "1cef1fdb-ff52-48c4-8e4e-dfb5ea83d357",
  "upn": "admin@contoso.onmicrosoft.com",
  "puid": "1003BFFD8EC47CA6",
  "sub": "7XpD5OWAXM1OWmKiVKh1FOkKXV4N3OSRol6mz1pxxhU",
  "given_name": "John",
  "family_name": "Doe",
  "name": "Contoso, Inc.",
  "unique_name": "admin@contoso.onmicrosoft.com",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1",
  "scp": "ActivityFeed.Read ServiceHealth.Read",
  "acr": "1"
}

Request an access token using client credentials

After the tenant ID is known, your application can make service-to-service calls to Azure AD to request additional access tokens as they expire. These tokens include information only about the requesting application and not about the admin that originally granted consent. Service-to-service calls require that your application use an X.509 certificate to create client assertion in the form of a base64-encoded, SHA256 signed JWT bearer token.

When you are developing your application in .NET, you can use the Microsoft Authentication Library (MSAL) to create client assertions. Other development platforms should have similar libraries.

An un-encoded JWT token consists of a header and payload that have the following properties.

HEADER:

{
  "alg": "RS256",
  "x5t": "{thumbprint of your X.509 certificate used to sign the token",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/{tenantid}/oauth2/token",
  "iss": "{your app client ID}",
  "sub": "{your app client ID}"
  "jti": "{random GUID}",
  "nbf": {epoch time, before which the token is not valid},
  "exp": {epoch time, after which the token is not valid},
}

Sample JWT token

HEADER:

{
  "alg": "RS256",
  "x5t": "YyfshJC3rPQ-kpGo5dUaiY5t3iU",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token",
  "iss": "a6099727-6b7b-482c-b509-1df309acc563",
  "sub": "a6099727-6b7b-482c-b509-1df309acc563"
  "jti": "0ce254c4-81b1-4a2e-8436-9a8c3b49dfb9",
  "nbf": 1427248048,
  "exp": 1427248648,
}

The client assertion is then passed to Azure AD as part of a service-to-service call to request an access token. When using client credentials to request an access token, use an HTTP POST to a tenant-specific endpoint, where the previously extracted and stored tenant ID is embedded in the URL. For example:

https://login.windows.net/{tenantid}/oauth2/token

The body of the POST contains the following:

resource=https%3A%2F%2Foutlook.office365.com&amp;client_id={your_app_client_id}&amp;grant_type=client_credentials&amp;client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&amp;client_assertion={encoded_signed_JWT_token}

Sample request

POST https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 994

resource=https%3A%2F%2Foutlook.office365.com&amp;client_id= a6099727-6b7b-482c-b509-1df309acc563&amp;grant_type=client_credentials &amp;client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&amp;client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Ill5ZnNoSkMzclBRLWtwR281ZFVhaVk1dDNpVSJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ud2luZG93cy5uZXRcLzQxNDYzZjUzLTg4MTItNDBmNC04OTBmLTg2NWJmNmUzNTE5MFwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQyNzI0ODY0OCwiaXNzIjoiYTYwOTk3MjctNmI3Yi00ODJjLWI1MDktMWRmMzA5YWNjNTYzIiwianRpIjoiMGNlMjU0YzQtODFiMS00YTJlLTg0MzYtOWE4YzNiNDlkZmI5IiwibmJmIjoxNDI3MjQ4MDQ4LCJzdWIiOiJhNjA5OTcyNy02YjdiLTQ4MmMtYjUwOS0xZGYzMDlhY2M1NjMifQ.vfDrmCjiXgoj2JrTkwyOpr-NOeQTzlXQcGlKGNpLLe0oh4Zvjdcim5C7E0UbI3Z2yb9uKQdx9G7GeqS-gVc9kNV_XSSNP4wEQj3iYNKpf_JD2ikUVIWBkOg41BiTuknRJAYOMjiuBE2a6Wyk-vPCs_JMd7Sr-N3LiNZ-TjluuVzWHfok_HWz_wH8AzdoMF3S0HtrjNd9Ld5eI7MVMt4OTpRfh-Syofi7Ow0HN07nKT5FYeC_ThBpGiIoODnMQQtDA2tM7D3D6OlLQRgLfI8ir73PVXWL7V7Zj2RcOiooIeXx38dvuSwYreJYtdphmrDBZ2ehqtduzUZhaHL1iDvLlw

The response will be the same as before, but the token will not have the same properties, because it does not contain properties of the admin that granted consent.

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1276

{"token_type":"Bearer","expires_in":"3599","expires_on":"1431659094","not_before":"1431655194","resource":"https://outlook.office365.com","access_token":"eyJ0eXAiOiJKV1QiL..."}

Sample access token

{
  "aud": "https://outlook.office365.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1431655194,
  "nbf": 1431655194,
  "exp": 1431659094,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "roles": [
    "ServiceHealth.Read",
    "ActivityFeed.Read"
  ],
  "oid": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "sub": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "idp": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1"
}

Build your app

Now that you’ve registered your app in Azure AD and configured it with the necessary permissions, you're ready to build your app. The following are some of the key aspects to consider when designing and building your app:

The consent experience. To obtain consent from your customers, you must direct them in a browser to the Azure AD website, using the specially constructed URL described previously, and you must have a website to which Azure AD will redirect the admin once they grant consent. This website must extract the authorization code from the URL and use it to request an access token from which it can obtain the tenant ID.
Store the tenant ID in your system. This will be needed when requesting access tokens from Azure AD and when calling the Reporting Web Service.
Managing access tokens. You'll need a component that requests and manages access tokens as needed. If your app calls the APIs periodically, it can request tokens on demand, or if it calls the APIs continuously to retrieve data, it can request tokens at regular intervals (for example, every 45 minutes).
Implement a webhook listener as needed by the API you are using.
Data retrieval and storage. You'll need a component that retrieves data for each tenant, either by using continuous polling or in response to webhook notifications, depending on the API you are using.

Sdílet prostřednictvím

Office 365 Reporting web service

Welcome to the Office 365 Reporting web service

Administrator permissions

Functional architecture

The service description document and MailFilterList report

Reports available in the Reporting web service

Get started with Reporting Web Service

Register your application in Azure AD

Prerequisites

Use the Azure Portal to register your application in Azure AD

Configure your application properties in Azure AD

Generate a new key for your application

Configure an X.509 certificate to enable service-to-service calls

Assign Azure AD roles to the application

Specify the permissions your app requires to access the Reporting Web Service

Request access tokens from Azure AD

Request an access token using the authorization code

Sample request

Sample response

Sample token

Request an access token using client credentials

Sample JWT token

Sample request

Sample response

Sample access token

Build your app

Additional resources

Další materiály

Sdílet prostřednictvím

Office 365 Reporting web service

Welcome to the Office 365 Reporting web service

Administrator permissions

Functional architecture

The service description document and MailFilterList report

Reports available in the Reporting web service

Get started with Reporting Web Service

Register your application in Azure AD

Prerequisites

Use the Azure Portal to register your application in Azure AD

Configure your application properties in Azure AD

Generate a new key for your application

Configure an X.509 certificate to enable service-to-service calls

Assign Azure AD roles to the application

Specify the permissions your app requires to access the Reporting Web Service

Get Office 365 tenant admin consent

Request access tokens from Azure AD

Request an access token using the authorization code

Sample request

Sample response

Sample token

Request an access token using client credentials

Sample JWT token

Sample request

Sample response

Sample access token

Build your app

Additional resources

Další materiály