Get Usage Logs from Azure Rights Management

Overview Technical Article

Microsoft France

Published: November 2013 (Updated: October 2014)

Version:1.0b

Author: Philippe Beraud, Arnaud Jumelet (Microsoft France)

Contributors/Reviewers:Enrique Saggese, Amrita Satapathy (Microsoft Corporation)

For the latest information on RMS, please see

Copyright© 2014Microsoft Corporation. All rights reserved.

Abstract: The Microsoft Azure Rights Management service(Azure RMS) provides the logging capability that lets you receive a log of every request that the Microsoft Rights Management cloud-hosted service serves on your behalf. This includes requests from users, actions by the Azure Rights Management service administrators in your organization, as well as actions taken by Microsoft operators on your behalf. These logs empower you to accomplish a variety of outcomes, either on your own or by purchasing 3rd party applications to process your Azure Rights Management service logs.

By following the steps outlined in this document you should be able to successfully prepare your environment to leverage this capability, enable it,and monitor the usage of yourAzure Rights Management service’s tenantover the time, and thus start using the service within your organization to create and consume protected content in compliance with your own security and IT policies in place.

Table of Contents

Feedbacks

Introduction

Objectives of this paper

Non-objectives of this paper

Organization of this paper

About the audience

Opting in to receive logs

Understanding the pre-requisites

Setting up an Azure storage

Configuring the Azure Rights Management service to log to the Azure storage account

Retrieving your logs

Retrieving your logs with Windows PowerShell

Retrieving your logs with Azure Storage SDK

Processing your logs

Managing the logging capability

Suspending and resuming logging

Managing your log storage

Rolling your storage account details

Delegating access to your logs

Understanding the log format

Understanding the storage account layout

Understanding the log sequence and how to interpret it

Understanding the blob format

Understanding the special values of user-id

Understanding the common request types

Feedback

For any feedback or comment regarding this document, please send a mail to .

Introduction

You can configure the Azure Rights Management serviceto generate and give you a log of every request that the Azure Rights Management service fulfils for your tenantas soon as it happens.

This information is very useful for a variety of reasons:

  • Analyzing for business insight. The Azure Rights Management service writes logs in W3C Extended Log (Weblog) format[1] into anAzure storage account[2] that you provide for this purpose. You can then feed the logs into a repository of your choice (database, OLAP, Map/Reduce, etc.) in order to analyze and report.

Examples of insight you can gain are: who is accessing your RMS-protected assets, what are they accessing, from what devices, from where, are they getting a satisfactory experience, who all has read a given document etc.

  • Monitoring for abuse. The Azure Rights Management service shares logs with you in near-realtime (99.9% of logs available to you within 15 minutes of the action). This allows you to continuously monitor usage of your Azure Rights Management service’s assets.

You know your employees best and are uniquely qualified to identify an abuse pattern.As an example, your administrators may want to be alerted if there is a spike in accesses to your assets during off hours (insider trying to steal a bunch of documents?), or if the same user accesses from two different IP addresses within 15 minutes (potential password compromise?).

  • Performing Forensics. When there is an information leak, the top two questions are:
  1. Who recently accessed the specific document that leaked?
  2. What information did a specific suspect access recently?

With the Azure Rights Management service’s architecture, your documents can flow any way you want (email, cloud storage such as Dropbox, USB, etc.) but recipients must get a license from the Azure Rights Management service to open and consume those documents. Therefore the Azure Rights Management service’s logs are a definitive source of information for forensics, as long as your assets are protected with the Azure Rights Management service.

Objectives of this paper

This document provides information about the logging capability of the Azure Rights Management service and thus about monitoring and controlling its usage. More particularly, it provided an in-depth description of this capability, how to enable it in your environment and your related subscription of the Microsoft Rights Management cloud-hosted service along with the standard format used for the log files.

Furthermore, by following the steps outlined in this document you should be able to successfully prepare your environment to leverage the logging capability, enable it and efficiently monitor the usage of the service over the time, and consequently start using the Azure Rights Management service within your organization to create and consume protected content in compliance with your own security and IT policies in place.

NoteThe logging capability is available to you whether you let Microsoft generate your key (the default) or you bring your own key (BYOK) (see whitepaper Bring Your Own Key with Azure Rights Management[3]). But when you bring your own key, the Azure Rights Management service also logs every usage of your key in addition to front-end request logs. This allows you to monitor in near real-time how your key is being used.

Non-objectives of this paper

This document doesn’t offer a full description of the Microsoft Rights Management services offerings. It rather simply focusses on key aspects in the context of this paper that aims at providing the readers an understanding on how to leverage and enable logging capability in your environment and your related subscription of the Microsoft Rights Management cloud-hosted service.

NoteFor an overview of the NEW Microsoft Rights Management services offerings, see the whitepaper Microsoft Rights Management services[4], the online documentation[5], the series of whitepapers[6] on RMS to which the current document belong as well as the posts on the RMS Team blog[7].

Organization of this paper

To cover the aforementioned objectives, this document is organized by themes, which are covered in the following sections:

  • Opting in to receive logs.
  • Retrieving your logs.
  • Processing your logs.
  • Managing the logging capability.
  • Understanding the log format.

About the audience

This document is intended for IT professionals and system architects who are interested in understanding the logging capability of the Azure Rights Management service and, thus monitoring and controlling its usage.

Opting in to receive logs

Opting in for logs is completely optional. All functionality of the Azure Rights Management service will work the same way whether or not you opt in to receive logs.

The Azure Rights Management service provides you logs for no extra charge. You must provide an Azure storage account to receive logs in, and you will be billed for the storage used.

Understanding the pre-requisites

To exercise the Usage Logging feature,the pre-requisites are as follows:

Pre-requisite / Description
An IT-managedAzure Rights Management service subscription / You must have anAzure Rights Management service subscription managed by your organization. Organizations that use the free ‘RMS for Individuals’ offer cannot get logs.
AnAzure subscription / You must have a subscription to Azure and sufficient Azure storage to store your logs.

The rest of this document will guide you through the entire process to benefit from such a capability.

Setting up an Azure storage

As previously outlined, the Azure Rights Management service writes logs to anAzure storage account[8] that you provide. The rest of this section steps you through how to create such an account.

The stepsbelow assumes you already have anAzure account. For testing purpose, you can subscribe for a free Azure 1-month trial[9].

We support individual accounts, but recommend organizational accounts.

We recommend you set up a dedicated storage account for the Azure Rights Management service’s logs. You will need to share the storage account keys with the Azure Rights Management service, and potentially with other staff in your organization that report on your logs.

To set up an Azure storage, proceed with the following steps:

  1. Open a browser and navigate to the Azure management portal at
  2. Sign in with your Azure account credentials
  3. Select STORAGEin the left pane and click NEWat the bottom of the screen. Select STORAGE and QUICK CREATE.

  1. Type a unique name for your storage account URL, for example “corpcontoso” for our factious company Contoso Corporation and select a location corresponding to the one of your RMS tenant, North Europe in our case. Click CREATESTORAGEACCOUNT.

Wait for Azure to create your account. Once complete, you will see a status of Online as shown next.

  1. Click MANAGE ACCESS KEYS at the bottom of the screen. A Manage Access Keys dialog pops up and shows your primary and secondary access keys. Copy the primary access key to the clipboard, you will need this in the next step.

Configuring the Azure Rights Management service to log to the Azure storage account

The configuration leverages the cmdlets of theAzure Rights Management administration module for Windows PowerShell[10]. Most Azure Rights Management service’s administrative tasks need this package.

NoteWindows PowerShellis a task-based command-line shell and scripting language that is designed for system/service administration and automation. It uses administrative tasks called cmdlets. Each cmdlet has required and optional arguments, called parameters, that identify which objects to act on or control how the cmdlet performs its task. You can combine cmdlets in scripts to perform complex functions that give you more control and help you automate the administration of Windows, applications and online services in the Cloud. It has become a common way to manage the latest generation of Microsoft products and services.

A Windows PowerShell "module" is a package that contains Windows PowerShell commands, cmdlets, providers, functions, variables, and aliases.The Azure Rights ManagementAdministration ModuleforWindowsPowerShell is a separate installation package which includes cmdlets specifically designed for the Azure Rights Management service tenant-based administration.

For more information about Windows PowerShell, please see the Windows PowerShell Web site[11], the Windows PowerShell online help[12], and the Windows PowerShell Weblog[13]Windows PowerShell Software Development Kit (SDK)[14] that includes a programmer’s guide along with a full reference.

Installing Windows PowerShell for Azure Rights Management

This section walks you through the installation of the Microsoft Rights Management administration module.

NoteFor additional information, see the Microsoft TechNet article Install Windows PowerShell for rights management[15].

Installing the prerequisite software

The Microsoft Rights Management administration module requires the MicrosoftOnlineServicesSign-InAssistant (MOS SIA) 7.0, which is 7.250.4551.0 as of this writing. So we will install it manually.

NoteThe Microsoft Online Services Sign-In Assistant (MOS SIA) 7.0 provides end user sign-in capabilities to Microsoft Online Services, such Office 365 and the Azure Rights Management service. In the context of this paper, the MOS SIA is used to authenticate users to these services through a set of dynamic link library files (DLLs) and a Windows service as described in the community article Description of Microsoft Online Services Sign-In Assistant (MOS SIA)[16].

To install the Microsoft Online Sign-In Assistant (MOS SIA) 7.0, proceed with the following steps:

  1. Open a browser session and navigate to the following link: Microsoft Online Services Sign-In Assistant for IT Professionals RTW[17]and click Download.
  2. In the Choose the download you want page, check msoidcli_64bit.msi (or msoidcli_32bit.msi depending on your Windows environment) and click Next.
  1. Click Run. The Microsoft Online Services Sign-in Assistant Setup wizard opens.

  1. On the license terms page, select I accept the terms in the License Agreement and Privacy Statement and click Install. A User Account Control dialog pops up.
  1. In the User Account Control dialog, click Yes to execute the setup.

  1. On the completion page, click Finish.
Installing the Microsoft Rights Management administration module

To connect Windows PowerShell to the Azure Rights Management service, proceed with the following steps:

  1. Download the Microsoft Rights Management Administration module from
  2. In the Choose the download you want page, check WindowsAzureADRightsManagementAdministration_x64.exe (or WindowsAzureADRightsManagementAdministration_x86.exe depending on your Windows environment) and click Next.
  1. Click Run. A Microsoft Rights Management Administration Setup wizard opens up.
  1. On the Welcome page, select the Next option.
  1. On the End-UserLicense Agreement page, select I accept the terms in the License Agreement and click Next.
  1. On the Ready to Install page, click Install. An User Account Control dialog pops up.
  1. Click Yes.
  1. On the completion page, click Finish.

The Microsoft Rights Management administration module for Windows PowerShell provides a set of Windows PowerShell cmdlets that provide administrative (advanced) capabilities forthe Azure Rights Management service. These cmdlets will be used later in this document with for the logging capability. More especially, in the context of this document, the cmdlets relevant to the logging capability are the following ones:

  • Disable-AadrmUsageLogFeature
  • Enable-AadrmUsageLogFeature
  • Get-AadrmUsageLog
  • Get-AadrmUsageLogFeature
  • Get-AadrmUsageLogLastCounterValue
  • Get-AadrmUsageLogStorageAccount
  • Set-AadrmUsageLogStorageAccount

Detailed help is available from an elevated Windows PowerShell command prompt by executing these commands with the -? option.

Telling Azure Rights Management about your storage account and enabling logging

To configure the Azure Rights Management service to log to the Azure storage account, proceed with the following steps:

  1. Open an elevated Windows PowerShell command prompt.
  2. Then import the Azure Rights Management module for Windows PowerShell and connect to the Azure Rights Management service by typing the following commands.

PS C:\Windows\system32> Import-Module AADRM

PS C:\Windows\system32> Connect-AadrmService -verbose

You will be prompted for your credentials.

  1. Enter your Azure Rights Management service’s tenant credentials (the set of credentials should have Global Administrator privilege) and wait to be authenticated. In the Windows PowerShell Credential Request window that opens up, provide the credentials for the administrator account such as:

Username:

Password: ****************

  1. Next, run the following commands to specify the Azure Rights Management service where you want your logs. Replace the key value in the Convert-SecureString cmdlet with the one that you copied in the Azure management portal for your storage account’s access key (copied to the clipboard). Replace “corpcontoso” in the example below with your storage account name.

PS C:\Windows\system32$accesskey = Convert-SecureString " wUjKVV14XXUCrdpuLsIa8yQ5IgUmLSOLmlgS/CcHNZXiurEORjTItdtPf4OpCaIwGNyijjMPxvDEOG21HRKR7A==" –asplaintext -force

PS C:\Windows\System32> Set-AadrmUsageLogStorageAccount -StorageAccount corpcontoso -AccessKey $accesskey

corpcontoso was set as the storage account for the usage log feature for the Rights management service.

PS C:\Windows\system32

  1. Finally, run the following cmdlet to enable logging:

PS C:\Windows\system32Enable-AadrmUsageLogFeature

The usage log feature is enabled for the Rights management service.

PS C:\Windows\system32

From this point onwards the Azure Rights Management service will log all requests served on behalf of your tenant to your storage account. Logs before this point are not available.

Retrieving your logs

The Azure Rights Management servicewrites logs to your Azure storage account as a series of blobs. Each blob contains one or more log records, in W3C Extended Log (Weblog) format[18]. The blob names are numbers, in the order they were created.

Section § Understanding the log formatdescribes the log format in detail.

Logs may take up to a few minutes to show up in your storage account after the Azure Rights Management service serves a request for your tenant. 99.9% of logs should appear in your account within 15 minutes after the request is served.

You can retrieve these logs in two ways:

  1. The simplest method is to use the Get-AadrmUsageLog cmdlet in the Microsoft Rights Management module for Windows PowerShell package.
  2. Alternatively, if you want to customize what/how/where you download, you can use the Azure SDK[19] or other tooling[20].

Retrieving your logs with Windows PowerShell

The Get-AadrmUsageLog cmdlet lets you download logs to your computer. This cmdlet downloads each blob as a file to the location you specify. You may analyze these files locally or import them into a database or Hadoop storage to do serious crunching.

Example 1: still from the previous elevated Windows PowerShell command prompt, run the following command to downloadALLavailable logs from your storage account to your C:\Logs folder:

PS C:\Windows\system32Get-AadrmUsageLog –Path "C:\Logs"

1527

PS C:\Windows\system32>

Example 2: still from the previous elevated Windows PowerShell command prompt, run the following command to download a specific range of blob: