top of page

Demystify custom-claim rules

Updated: Jun 15, 2023

  • Custom claim rules allow administrators to define logic-based rules that transform, or add claims based on various conditions, or requirements. Administrators can create rules that filter or remove certain claims from the user's identity. For example, they may want to remove sensitive or unnecessary claims before issuing a token.

  • Custom claim rules enable administrators to modify the values of existing claims. This can involve mapping or converting claim values to a different format, concatenating multiple claims into a single claim, or extracting information from existing claims. Administrators can define rules to add new claims to a user's identity. These claims can be derived from existing claims, external data sources, or computed based on specific logic or algorithms. This information should provide you only an overview and not a technical documentation.

  • Custom claim rules can be used to enforce fine-grained authorization policies by adding claims that represent user attributes or permissions. These claims can then be used by downstream systems to make access control decisions. In federated identity scenarios, where identity information is exchanged between different systems or organizations, custom claim rules can be used to map claims between different identity providers, ensuring compatibility and consistency. In this article I will explain custom claim rules, on hand of AzureAD policies.


Azure Application proxy

If you have an enterprise environment with an On-Prem data center and a Cloud-DataCenter, like Azure or M365, you may have alot of legacy applications and systems. You may also publish local certificates to some cloud applications.

In this case you are using Azure Application proxy and have Azure Application proxy connector in your DMZ installed. Azure Application proxy is mostly used for certificate publishing to the cloud environment and is installed together with Network Device Enrollment Service (NDES).

On-Prem application access

If you have an on-prem application and you want to provide access to all mobile phone users, you can use AzureApplication proxy service. AzureApp proxy connector is creating an outbound tunnel directly to your tenant and provide cloud access.

You need to configure an enterprise app and configure internal On-Prem application URL. Application can be protected by conditional access. Only user with active app assignment can access it from the cloud.

On your mobile phone, you are using your cloud identity, but your on-prem app is connected only to your local identity provider. You can use only your local identity for authentication to your on-prem application.

Hybrid-Identity (Identity federation)

To solve this authentication issue, you need a federation provider to transform cloud and local identity to a hybrid-identity. Federation provider can map both identities, using sourceanchorattribute and issue user access token, which is valid for both environments.

To solve this authentication issue, you need a federation provider to transform cloud and local identity to a hybrid-identity. Federation provider can map both identities, using sourceanchor attribute and issue user access token, which is valid for both environments.

Why do you need custom claims?

Federation provider will allways translate only specific claims (attributes) which are configured on Cloud / Local identity provider and specific application. So if the application requires „onpremissessamaccountname“ it will not persist bei default and authentication will not work.

To add „onpremissessamaccountname“, or other „extensionattributes“ you need to create a CUSTOM „ClaimMappingPolicy“ to transport required claims / attributes to your on-prem application.

How to configure custom claims in AzureAD?

First you need to make sure, that you have Azure AD powershell module installed. You can find instruction how to install powershell modules in the internet.

In the next step you need to configure which claims you want to transport in your token. In this script you can see two custom claims, so that you can customize this part and get desired result.

$claimdefinition = @('{
               "Version": 1,
               "IncludeBasicClaimSet": "true",
               "ClaimsSchema": [
                       "Source": "user",
                       "ID": "onpremisessamaccountname",
                       "JwtClaimType": "onpremisessamaccountname"
                       "Source": "user",
                       "ID": "extensionattribute12",
                       "JwtClaimType": "extensionattribute12"

In the next step you need to configure the name of your policy so that you can identify it later. Make sure that you are using unique and speaking name.

$claimrulename = 'SamAccountName-Attribute12' #Here you can configure the name of your policy 

After you have completed previous steps, we can create the policy. Make sure that you have Global Administrator permissions for this task, or it will fail.

$custompolicy = New-AzureADPolicy -Definition $claimdefinition -DisplayName $claimrulename -Type "ClaimsMappingPolicy" -ErrorAction stop #policy is created in this line 

You have successful created the policy. Now we need to activate it for your tenant. Be ware that you have only one Custom Claim policy per tenant. If you need additional claims you need to remove the policy and create a new one with all required claims.

$serviceprincipal = (Get-AzureADServicePrincipal -top 1).objectid #geting ServicePrincipalID from your tenant 
Add-AzureADServicePrincipalPolicy -Id $serviceprincipal -RefObjectId $ -ErrorAction stop 

After successful activation of your policy, you can validate your configuration by using service principal ID. We have already saved this value into a variable. In the output you can see the displayname of your policy and ID. Additionally you can see the type and make the policy to default for your tenant.

Token Lifetime

If you need a custom tokenlifen, you can configure it also via AzureAD policies.

You can find Microsoft documentation how to configure the token lifetime here.

First you need again, your AzureADServicePrincipal ID.

 $serviceprincipal = (Get-AzureADServicePrincipal -top 1).objectid #geting ServicePrincipalID from your tenant

In the next step you need to configure the policy.

New-AzureADPolicy -Definition @('{"TokenLifetimePolicy":{"Version":1,"AccessTokenLifetime":"00:10:00"}}') -DisplayName "Custom-TokenLifetime" -IsOrganizationDefault $false -Type "TokenLifetimePolicy"

Now we need to activate the policy in the same way as we did with Custom-Claim policy

$custompolicy = Get-AzureADPolicy -id '5965e7e1-d2f9-4406-9ca1-6b3b82153c09' #ID of your policy
Add-AzureADServicePrincipalPolicy -Id $serviceprincipal -RefObjectId $ 

After the activation of tokenlifetime policy you can validate the configuration with

Get-AzureADServicePrincipalPolicy -Id $serviceprincipal

If you have additional questions, just reach out to me.

Visit my GITHUB repository! You can find this script and all steps right there.

I hope you have enjoyed this demystification article.

If you have any questions just leave me a feedback.

69 views0 comments


bottom of page