Logging and analyzing the protection usage from Azure Information Protection

Use this information to help you understand how you can use usage logging for the protection service (Azure Rights Management) from Azure Information Protection. This protection service provides the data protection for your organization's documents and emails and it can log every request to it. These requests include when users protect documents and email and also consume this content, actions performed by your administrators for this service, and actions performed by Microsoft operators to support your Azure Information Protection deployment.

You can then use these protection usage logs to support the following business scenarios:

• Analyze for business insights

  The logs generated by the protection service can be imported into a repository of your choice (such as a database, an online analytical processing (OLAP) system, or a map-reduce system) to analyze the information and produce reports. As an example, you could identify who is accessing your protected data. You can determine what protected data people are accessing, and from what devices and from where. You can find out whether people can successfully read protected content. You can also identify which people have read an important document that was protected.

• Monitor for abuse

  Logging information about the protection use is available to you in near-real time, so that you can continuously monitor your company’s use of the protection service. 99.9% of logs are available within 15 minutes of an initiated action to the service.

  For example, you might want to be alerted if there is a sudden increase of people reading protected data outside standard working hours, which could indicate that a malicious user is collecting information to sell to competitors. Or, if the same user apparently accesses data from two different IP addresses within a short time frame, which could indicate that a user account has been compromised.

• Perform forensic analysis

  If you have an information leak, you are likely to be asked who recently accessed specific documents and what information did a suspected person access recently. You can answer these types of questions when you use this logging because people who use protected content must always get a Rights Management license to open documents and pictures that are protected by Azure Information Protection, even if these files are moved by email or copied to USB drives or other storage devices. This means that you can use these logs as a definitive source of information for forensic analysis when you protect your data by using Azure Information Protection.

In addition to this usage logging, you also have the following logging options:

Logging option	Description
Admin log	Logs administrative tasks for the protection service. For example, if the service is deactivated, when the super user feature is enabled, and when users are delegated admin permissions to the service. For more information, see the PowerShell cmdlet, Get-AipServiceAdminLog.
Document tracking	Lets users track and revoke their documents that they have tracked with the Azure Information Protection client. Global administrators can also track these documents on behalf of users. For more information, see Configuring and using document tracking for Azure Information Protection.
Client event logs	Usage activity for the Azure Information Protection client, logged in the local Windows Applications and Services event log, Azure Information Protection. For more information, see Usage logging for the Azure Information Protection client.
Client log files	Troubleshooting logs for the Azure Information Protection client, located in %localappdata%\Microsoft\MSIP. These files are designed for Microsoft Support.

In addition, information from the Azure Information Protection client usage logs and the Azure Information Protection scanner is collected and aggregated to create reports in the Azure portal. For more information, see Reporting for Azure Information Protection.

Use the following sections for more information about the usage logging for the protection service.

How to enable logging for protection usage

Protection usage logging is enabled by default for all customers.

There is no extra cost for the log storage or for the logging feature functionality.

How to access and use your protection usage logs

Azure Information Protection writes logs as a series of blobs to an Azure storage account that it automatically creates for your tenant. Each blob contains one or more log records, in W3C extended log format. The blob names are numbers, in the order in which they were created. The How to interpret your Azure Rights Management usage logs section later in this document contains more information about the log contents and their creation.

It can take a while for logs to appear in your storage account after a protection action. Most logs appear within 15 minutes. Usage logs are only available when the "date" field name contains a value of a previous date (in UTC time). Usage logs from the current date are not available. We recommend that you download the logs to local storage, such as a local folder, a database, or a map-reduce repository.

To download your usage logs, you will use the AIPService PowerShell module for Azure Information Protection. For installation instructions, see Installing the AIPService PowerShell module.

To download your usage logs by using PowerShell

1. Start Windows PowerShell with the Run as administrator option and use the Connect-AipService cmdlet to connect to Azure Information Protection:

   Connect-AipService -EnvironmentName AzureChinaCloud
   

2. Run the following command to download the logs for a specific date:

   Get-AipServiceUserLog -Path <location> -fordate <date>
   

   For example, after creating a folder called Logs on your E: drive:

   • To download logs for a specific date (such as 2/1/2016), run the following command: Get-AipServiceUserLog -Path E:\Logs -fordate 2/1/2016

   • To download logs for a date range (such as from 2/1/2016 through 2/14/2016), run the following command: Get-AipServiceUserLog -Path E:\Logs -fromdate 2/1/2016 -todate 2/14/2016

When you specify the day only, as in our examples, the time is assumed to be 00:00:00 in your local time, and then converted to UTC. When you specify a time with your -fromdate or -todate parameters (for example, -fordate "2/1/2016 15:00:00"), that date and time is converted to UTC. The Get-AipServiceUserLog command then gets the logs for that UTC time period.

You cannot specify less than a whole day to download.

By default, this cmdlet uses three threads to download the logs. If you have sufficient network bandwidth and want to decrease the time required to download the logs, use the -NumberOfThreads parameter, which supports a value from 1 through 32. For example, if you run the following command, the cmdlet spawns 10 threads to download the logs: Get-AipServiceUserLog -Path E:\Logs -fromdate 2/1/2016 -todate 2/14/2016 -numberofthreads 10

How to interpret your usage logs

Use the following information to help you interpret the protection usage logs.

The log sequence

Azure Information Protection writes the logs as a series of blobs.

Each entry in the log has a UTC timestamp. Because the protection service runs on multiple servers across multiple data centers, sometimes the logs might seem to be out of sequence, even when they are sorted by their timestamp. However, the difference is small and usually within a minute. In most cases, this is not an issue that would be a problem for log analysis.

The blob format

Each blob is in W3C extended log format. It starts with the following two lines:

#Software: RMS

#Version: 1.1

The first line identifies that these are protection logs from Azure Information Protection. The second line identifies that the rest of the blob follows the version 1.1 specification. We recommend that any applications that parse these logs verify these two lines before continuing to parse the rest of the blob.

The third line enumerates a list of field names that are separated by tabs:

#Fields: date      time      row-id      request-type      user-id      result      correlation-id      content-id      owner-email      issuer      template-id      file-name      date-published      c-info      c-ip      admin-action      acting-as-user

Each of the subsequent lines is a log record. The values of the fields are in the same order as the preceding line, and are separated by tabs. Use the following table to interpret the fields.

Field name	W3C data type	Description	Example value
date	Date	UTC date when the request was served. The source is the local clock on the server that served the request.	2013-06-25
time	Time	UTC time in 24-hour format when the request was served. The source is the local clock on the server that served the request.	21:59:28
row-id	Text	Unique GUID for this log record. If a value is not present, use the correlation-id value to identify the entry. This value is useful when you aggregate logs or copy logs into another format.	1c3fe7a9-d9e0-4654-97b7-14fafa72ea63
request-type	Name	Name of the RMS API that was requested.	AcquireLicense
user-id	String	The user who made the request. The value is enclosed in single quotation marks. Calls from a tenant key that is managed by you (BYOK) have a value of ", which also applies when the request types are anonymous.	‘joe@contoso.com’
result	String	'Success' if the request was served successful. The error type in single quotation marks if the request failed.	'Success'
correlation-id	Text	GUID that is common between the RMS client log and server log for a given request. This value can be useful to help troubleshooting client issues.	cab52088-8925-4371-be34-4b71a3112356
content-id	Text	GUID, enclosed in curly braces that identifies the protected content (for example, a document). This field has a value only if request-type is AcquireLicense and is blank for all other request types.	{bb4af47b-cfed-4719-831d-71b98191a4f2}
owner-email	String	Email address of the owner of the document. This field is blank if the request type is RevokeAccess.	alice@contoso.com
issuer	String	Email address of the document issuer. This field is blank if the request type is RevokeAccess.	alice@contoso.com (or) FederatedEmail.4c1f4d-93bf-00a95fa1e042@contoso.partner.onmschina.cn'
template-id	String	ID of the template used to protect the document. This field is blank if the request type is RevokeAccess.	{6d9371a6-4e2d-4e97-9a38-202233fed26e}
file-name	String	File name of a protected document that is tracked by using the Azure Information Protection client for Windows. Currently, some files (such as Office documents) display as GUIDs rather than the actual file name. This field is blank if the request type is RevokeAccess.	TopSecretDocument.docx
date-published	Date	Date when the document was protected. This field is blank if the request type is RevokeAccess.	2015-10-15T21:37:00
c-info	String	Information about the client platform that is making the request. The specific string varies, depending on the application (for example, the operating system or the browser).	'MSIPC;version=1.0.623.47;AppName=WINWORD.EXE;AppVersion=15.0.4753.1000;AppArch=x86;OSName=Windows;OSVersion=6.1.7601;OSArch=amd64'
c-ip	Address	IP address of the client that makes the request.	64.51.202.144
admin-action	Bool	Whether an administrator has accessed the document tracking site in Administrator mode.	True
acting-as-user	String	The email address of the user for whom an administrator is accessing the document tracking site.	'joe@contoso.com'

Exceptions for the user-id field

Although the user-id field usually indicates the user who made the request, there are two exceptions where the value does not map to a real user:

• The value 'microsoftrmsonline@<YourTenantID>.rms.<region>.aadrm.cn'.

  This indicates an Office 365 service, such as Exchange Online or Microsoft SharePoint, is making the request. In the string, <YourTenantID> is the GUID for your tenant and <region> is the region where your tenant is registered. For example, na represents North America, eu represents Europe, and ap represents Asia.

• If you are using the RMS connector.

  Requests from this connector are logged with the service principal name of Aadrm_S-1-7-0, which is automatically generated when you install the RMS connector.

Typical request types

There are many request types for the protection service but the following table identifies some of the most typically used request types.

Request type	Description
AcquireLicense	A client from a Windows-based computer is requesting a license for protected content.
AcquirePreLicense	A client, on behalf of the user, is requesting for a license for protected content.
AcquireTemplates	A call was made to acquires templates based on template IDs
AcquireTemplateInformation	A call was made to get the IDs of the template from the service.
AddTemplate	A call is made from the Azure portal to add a template.
AllDocsCsv	A call is made from the document tracking site to download the CSV file from the All Documents page.
BECreateEndUserLicenseV1	A call is made from a mobile device to create an end-user license.
BEGetAllTemplatesV1	A call is made from a mobile device (back-end) to get all the templates.
Certify	The client is certifying the user for the consumption and creation of protected content.
FECreateEndUserLicenseV1	Similar to the AcquireLicense request but from mobile devices.
FECreatePublishingLicenseV1	The same as Certify and GetClientLicensorCert combined, from mobile clients.
FEGetAllTemplates	A call is made, from a mobile device (front-end) to get the templates.
FindServiceLocationsForUser	A call is made to query for URLs, which is used to call Certify or AcquireLicense.
GetClientLicensorCert	The client is requesting a publishing certificate (that is later used to protect content) from a Windows-based computer.
GetConfiguration	An Azure PowerShell cmdlet is called to get the configuration of the Azure RMS tenant.
GetConnectorAuthorizations	A call is made from the RMS connectors to get their configuration from the cloud.
GetRecipients	A call is made from the document tracking site to navigate to the list view for a single document.
GetTenantFunctionalState	The Azure portal is checking whether the protection service (Azure Rights Management) is activated.
KeyVaultDecryptRequest	The client is attempting to decrypt the RMS-protected content. Applicable only for a customer-managed tenant key (BYOK) in Azure Key Vault.
KeyVaultGetKeyInfoRequest	A call is made to verify that the key specified to be used in Azure Key Vault for the Azure Information Protection tenant key is accessible and not already used.
KeyVaultSignDigest	A call is made when a customer-managed key (BYOK) in Azure Key Vault is used for signing purposes. This is called typically once per AcquireLicence (or FECreateEndUserLicenseV1), Certify, and GetClientLicensorCert (or FECreatePublishingLicenseV1).
KMSPDecrypt	The client is attempting to decrypt the RMS-protected content. Applicable only for a legacy customer-managed tenant key (BYOK).
KMSPSignDigest	A call is made when a legacy customer-managed key (BYOK) is used for signing purposes. This is called typically once per AcquireLicence (or FECreateEndUserLicenseV1), Certify, and GetClientLicensorCert (or FECreatePublishingLicenseV1).
ServerCertify	A call is made from an RMS-enabled client (such as SharePoint) to certify the server.
SetUsageLogFeatureState	A call is made to enable usage logging.
SetUsageLogStorageAccount	A call is made to specify the location of the Azure Rights Management service logs.
UpdateTemplate	A call is made from the Azure portal to update an existing template.

Protection usage logs and Microsoft 365 unified audit log

File access and denied events do not currently include file name and are not accessible in the Microsoft 365 unified audit log. These events will be enhanced to be standalone useful and added from the Rights Management Service at a later date.

PowerShell reference

The only PowerShell cmdlet that you need to access your protection usage logging is Get-AipServiceUserLog.

For more information about using PowerShell for Azure Information Protection, see Administering protection from Azure Information Protection by using PowerShell.