Country and Region Information in current_principal_details

Kusto has introduced a new feature that allows users to access information about the country of a user and their tenant region or country as provided by Microsoft Entra ID through the current_principal_details() function. This addition provides enhanced granularity and control in data security and accessibility.

For the function to provide this information, it is essential to understand the authentication (AuthN) and authorization (AuthZ) flow for a query in Kusto.

It begins with the client application requesting access to the Kusto service. The client uses the Microsoft Authentication Library (MSAL) to acquire an access token from Microsoft Entra ID, which serves as proof of the client’s identity. This access token is included in the authorization header of the request. Upon receiving the request, Kusto validates the access token to ensure it is issued by a trusted authority and is still valid. Next, Kusto checks the roles assigned to the authenticated principal to determine if they have the necessary permissions to execute the query. If the principal is authorized, the query is executed; otherwise, access is denied. In the case of current_principal_details(), the function extracts information from optional claims in the token to enrich the result about the identity. The newly added properties are:

• Country – based on the optional claim “ctry” (standard two-letter country/region code)
• TenantCountry – based on the optional claim “tenant_ctry” (standard two-letter country/region code configured by a tenant admin)
• TenantRegion – based on the optional claim “tenant_region_scope” (standard two-letter region code of the resource tenant)

The following Kusto Query Language (KQL) statement prints the information of the Entra ID user Alice:

print details=current_principal_details()

The result of the function provides detailed information about the authenticated user, Alice.

{ 
  "Country": "DE",
  "TenantCountry": "US",
  "TenantRegion": "WW",
  "UserPrincipalName": "alice@contoso.com",
  "Type": "aaduser",
  "IdentityProvider": "https://sts.windows.net",
  "DisplayName": "Alice (upn: alice@contoso.com)",
  "Authority": "<tenantId>",
  "ObjectId": "<objectId>",
  "Mfa": "True",
  "FQN": "aaduser=<objectId;tenantId "
}

With the integration of location information, users are now able to formulate advanced Row Level Security (RLS) policies. These policies can control access to specific rows based on the data provided by Entra ID tokens. This capability is particularly advantageous for organizations operating across multiple countries or regions, as it ensures that sensitive data is accessible only to authorized individuals within specified locations.

The ContosoSales table provides a straightforward yet illustrative dataset that includes sales information segmented by country. The table comprises two columns: Country and Product, with corresponding Amount of sales. For instance, it shows that 10 units of Espresso were sold in Germany (DE) and 5 units in the United States (US). This data can be used to implement and test Row Level Security policies based on geographical location, ensuring that access to sales data is restricted according to the specified country codes.

The following function can be used as a predicate in Row Level Security policy:

.create-or-alter function RLSForContoso(TableName: string) {
    table(TableName)
    | where Country == current_principal_details()["Country"]
}

A user with the Country property set to "DE" in Entra ID will get the following result when querying the ContosoSales table:

Please note that the information provided by Entra ID is based on static properties configured in the user's profile. Therefore, it does not necessarily represent the user's actual location at the time the query is executed. For example, a user with the Country attribute set to "DE" might not be physically located in Germany when the query runs.

This new capability not only bolsters data security but also enhances compliance with regional data protection regulations. By leveraging the properties from Microsoft Entra ID, enterprises can enforce their data governance policies more effectively and with greater precision.

The introduction of Country/Region-based filtering in Kusto RLS policies underscores Microsoft's commitment to providing robust, secure, and versatile data management solutions. As organizations navigate the complexities of data privacy and security, this feature offers a critical tool for maintaining control over their data landscape.

Stay tuned for more updates and detailed guides on how to implement and make the most out of this exciting new feature!