Logging and analyzing Azure Rights Management usage

Carol Bailey
Contributors

Applies to: Azure Rights Management, Office 365

Use the information in this topic to help you understand how you can use usage logging with Azure Rights Management (Azure RMS). The Azure Rights Management service can log every request that it makes for your organization, which includes requests from users, actions performed by Rights Management administrators in your organization, and actions performed by Microsoft operators to support your Azure Rights Management deployment.

You can then use these Azure Rights Management logs to support the following business scenarios:

  • Analyze for business insights

    The logs generated by Azure Rights Management 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 RMS-protected data. You can determine what RMS-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 Rights Management. 99.9% of logs are available within 15 minutes of an RMS-initiated action.

    For example, you might want to be alerted if there is a sudden increase of people reading RMS-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 Azure Rights Management and logging because people who use protected content must always get a Rights Management license to open documents and pictures that are protected by Azure Rights Management, even if these files are moved by email or copied to USB drives or other storage devices. This means that you can use Azure Rights Management logs as a definitive source of information for forensic analysis when you protect your data by using Azure Rights Management.

Note

If you are interested only in the logging of administrative tasks for Azure Rights Management, and do not want to track how users are using Rights Management, you can use the Get-AadrmAdminLog Windows PowerShell cmdlet for Azure Rights Management.

You can also use the Azure classic portal for high-level usage reports that include 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,

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

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 RMS 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 RMS 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

Azure Rights Management 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 RMS 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 RMS 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 RMS 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 Azure Rights Management on or before February 22, 2016 but did not enable the usage logging feature.

  • You activated Azure Rights Management 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

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

Each entry in the log has a UTC timestamp. Because Azure Rights Management 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

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. alice@contoso.com
issuer String Email address of the document issuer. alice@contoso.com (or) FederatedEmail.4c1f4d-93bf-00a95fa1e042@contoso.onmicrosoft.com'
template-id String ID of the template used to protect the document. {6d9371a6-4e2d-4e97-9a38-202233fed26e}
file-name String File name of the document that was protected.

Currently, some files (such as Office documents) display as GUIDs rather than the actual file name.
TopSecretDocument.docx
date-published Date Date when the document was protected. 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

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 Azure Rights Management 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 classic portal to add a template.
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.
KMSPDecrypt The client is attempting to decrypt the RMS-protected content. Applicable only for a customer-managed tenant key (BYOK).
DeleteTemplateById A call is made from the Azure classic portal, to delete a template by template ID.
ExportTemplateById A call is made from the Azure classic 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.
GetAllTemplates A call is made from the Azure classic 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.
GetTenantFunctionalState The Azure classic portal is checking whether Azure RMS is activated.
GetTemplateById A call is made from the Azure classic portal to get a template by specifying a template ID.
ExportTemplateById A call is being made from the Azure classic portal to export a template by specifying a template ID.
FindServiceLocationsForUser A call is made to query for URLs, which is used to call Certify or AcquireLicense.
ImportTemplate A call is made from the Azure classic portal to import a template.
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 RMS logs.
KMSPSignDigest A call is made when a customer-managed key (BYOK) is used for signing purposes. This is called typically once per AcquireLicence (or FECreateEndUserLicenseV1), Certify, and GetClientLicensorCert (or FECreatePublishingLicenseV1).
UpdateTemplate A call is made from the Azure classic portal to update an existing template.

Windows PowerShell reference

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

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

If you have logs in your own Azure storage from before the Azure RMS 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 Azure Rights Management, see Administering Azure Rights Management by Using Windows PowerShell.