Logging and analyzing usage of the Azure Rights Management service

Applies to: Azure Information Protection, Office 365

Use this information to help you understand how you can use usage logging for the Azure Rights Management service from Azure Information Protection. This 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 Azure Rights Management service logs to support the following business scenarios:

  • Analyze for business insights

    The logs generated by the Azure Rights Management 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

    Azure Rights Management logging information is available to you in near-real time, so that you can continuously monitor your company’s use of the Rights Management 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 type 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 the Azure Rights Management service, 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 the Azure Rights Management service.

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

Logging option Description
Admin log Logs administrative tasks for the the Azure Rights Management 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-AadrmAdminLog.
Web reports High-level usage reports from the Azure classic portal: RMS summary, RMS active users, RMS device platforms, and RMS application usage.

To access these reports from the Azure classic portal, click Active Directory, select and open a directory, and then click REPORTS.
Document tracking Lets users track and revoke their documents that they have tracked with the Azure Information Protection client or the RMS sharing app. 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 f or the Azure Information Protection client, located in %localappdata%\Microsoft\MSIP.

These files are designed for Microsoft Support.

Use the following sections for more information about the usage logging for the Azure Rights Management service.

How to enable Azure Rights Management usage logging

Starting February 2016, Azure Rights Management usage logging is enabled by default for all customers. This applies to customers who activated their Azure Rights Management service before February 2016 and to customers who activate the service after February 2016.

Note

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

If you used usage logging for Azure Rights Management prior to February 2016, you needed a subscription to Azure and sufficient storage on Azure, which is no longer the case.

How to access and use your Azure Rights Management usage logs

The Azure Rights Management service writes logs to your Azure storage account as a series of blobs. 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 an Azure Rights Management action. Most logs appear within 15 minutes. 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 Azure Rights Management administration module for Windows PowerShell. For installation instructions, see Installing Windows PowerShell for Azure Rights Management. If you have previously downloaded this Windows PowerShell module, run the following command to check that your version number is at least 2.4.0.0: (Get-Module aadrm -ListAvailable).Version

To download your usage logs by using PowerShell

  1. Start Windows PowerShell with the Run as administrator option and use the Connect-AadrmService cmdlet to connect to the Azure Rights Management service:

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

    Get-AadrmUserLog -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-AadrmUserLog -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-AadrmUserLog -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-AadrmUserLog 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-AadrmUserLog -Path E:\Logs -fromdate 2/1/2016 –todate 2/14/2016 -numberofthreads 10

Tip

You can aggregate all your downloaded log files into a CSV format by using Microsoft’s Log Parser, which is a tool to convert between various well-known log formats. You can also use this tool to convert data to SYSLOG format, or import it into a database. After you have installed the tool, run LogParser.exe /? for help and information to use this tool.

For example, you might run the following command to import all information into a .log file format: logparser –i:w3c –o:csv "SELECT * INTO AllLogs.csv FROM *.log"

If you manually enabled Azure Rights Management usage logging before the logging change February 22, 2016

If you used usage logging prior to the logging change, you will have usage logs in your configured Azure storage account. Microsoft will not copy these logs from your storage account to the new Azure Rights Management managed storage account as part of this logging change. You are responsible for managing the lifecycle of the previously generated logs and can use the Get-AadrmUsageLog cmdlet to download your old logs. For example:

  • To download all available logs to your E:\logs folder: Get-AadrmUsageLog -Path "E:\Logs"

  • To download a specific range of blobs: Get-AadrmUsageLog –Path "E:\Logs" –FromCounter 1024 –ToCounter 2047

Note that you do not have to download logs using the Get-AadrmUsageLog cmdlet if either of the following applies:

  • You activated the Azure Rights Management service on or before February 22, 2016 but did not enable the usage logging feature.

  • You activated the Azure Rights Management service after February 22, 2016.

How to interpret your Azure Rights Management usage logs

Use the following information to help you interpret the Azure Rights Management usage logs.

The log sequence

The Azure Rights Management service writes the logs as a series of blobs.

Each entry in the log has a UTC timestamp. Because the Azure Rights Management 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 Azure Rights Management logs. 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.onmicrosoft.com'
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 or the Rights Management sharing application 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.com'.

    This indicates an Office 365 service, such as Exchange Online or SharePoint Online, 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 Azure Rights Management service but the following table identifies some of the most typically used request types.

Request type Description
AcquireLicense A client from a Windows based machine is requesting a license for RMS-protected content.
AcquirePreLicense A client, on behalf of the user, is requesting for a license for RMS-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 content for protection.
DeleteTemplateById A call is made from the Azure portal, to delete a template by template ID.
DocumentEventsCsv A call is made from the document tracking site to download the .CSV file for a single document.
ExportTemplateById A call is made from the Azure portal to export a template based on a template ID.
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.
GetAllDocs A call is made from the document tracking site to load the all documents page for a user, or search all documents for the tenant. Use this value with the admin-action and acting-as-admin fields:

- admin-action is empty: A user views the all documents page for their own documents.

- admin-action is true and acting-as-user is empty: An administrator views all documents for their tenant.

- admin-action is true and acting-as-user is not empty: An administrator views the all documents page for a user.
GetAllTemplates A call is made from the Azure portal, to get all the templates.
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.
GetSingle A call is made from the document tracking site to navigate to a single document page.
GetTenantFunctionalState The Azure portal is checking whether the Azure Rights Management service is activated.
GetTemplateById A call is made from the Azure portal to get a template by specifying a template ID.
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).
LoadEventsForMap A call is made from the document tracking site to navigate to the map view for a single document.
LoadEventsForSummary A call is made from the document tracking site to navigate to the timeline view for a single document.
LoadEventsForTimeline A call is made from the document tracking site to navigate to the map view for a single document.
ImportTemplate A call is made from the Azure portal to import a template.
RevokeAccess A call is made from the document tracking site to revoke a document.
SearchUsers A call is made from the document tracking site to search all users in a tenant.
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.
UpdateNotificationSettings A call is made from the document tracking site to change the notification settings for a single document.
UpdateTemplate A call is made from the Azure portal to update an existing template.

Windows PowerShell reference

Starting February 2016, the only Windows PowerShell cmdlet that you need for Azure Rights Management usage logging is Get-AadrmUserLog.

Before this change, the following cmdlets were needed for Azure Rights Management usage logs, and are now deprecated:

If you have logs in your own Azure storage from before the Azure Rights Management logging change, you can download them with these older cmdlets, using Get-AadrmUsageLog and Get-AadrmUsageLogLastCounterValue, as before. But all new usage logs will write to the new Azure RMS storage and must be downloaded with Get-AadrmUserLog.

For more information about using Windows PowerShell for the Azure Rights Management service, see Administering the Azure Rights Management service by Using Windows PowerShell.

Comments

Before commenting, we ask that you review our House rules.