Claims configuration

TL;DR

Background

Authentication between Episerver and ImageVault is used by reusing the user identity in Episerver and creating an identity in ImageVault using these identities. In versions prior to ImageVault.EPiServer.UI 11.12, only the values (username, group/role names) were sent over. From 11.12 the user claims are used to create a token in ImageVault. If Episerver and ImageVault uses different tokens or different authentication systems the authorization might fail. To troubleshoot this we need to make sure that the same claims are used in both systems.

ImageVault claims

When a user authenticates with ImageVault, it gets a set of claims that defines the user identity and what groups/roles it belongs to (among other things). A claim consist of a type (like http://schemas.microsoft.com/ws/2008/06/identity/claims/groups that identifies a group of users) and a value (like Administrators). To see what claims a user has in ImageVault you can navigate to the path /account/userinfo on your ImageVault instance.

Among other things on that page, all claims for the user is listed.

Assigning access rights in ImageVault

When assigning access rights in ImageVault, an access right is connected to a claim by it's type and value. For a user to be granted the access right, it must own the matching claim. In ImageVault prior to 5.18, the access right was only mapped to the claim value.

For instance, when assigning the group Administrator to be part of the Global administrator role, the group claim Administrator (Type:http://schemas.microsoft.com/ws/2008/06/identity/claims/groups value:Administrator) is connected to that role. All users who has the claim is assigned the global administrator role.

Episerver claims

When a user authenticates with Episerver, it also get a set of claims that defines the user in Episerver. Since these are different systems, the claims for a user in Episerver can differ from the Claims in ImageVault (depending on configuration). To check which claims a user has in Episerver you can navigate to the path /episerver/ImageVault.EPiServer.UI/Stores/claimsdebug/ on your Episerver instance. This will list all claims assigned to the user in Episerver.

Note: the claimsdebug store was added in ImageVault.EPiServer.UI v11.12.

Note: the /episerver/ path segment might be reconfigured to use another path. It should be the Episerver UI path.

If comparing the claims assigned to the user in ImageVault and Episerver you might detect differences. For example, in ImageVault the user has the following claim

Type:  http://schemas.microsoft.com/ws/2008/06/identity/claims/groups   
Value: 2919e100-b494-4e34-8c89-c89a170e81c1

but in Episerver the following claim is found

Type:  groups
Value: 2919e100-b494-4e34-8c89-c89a170e81c1

You can notice that both claims refer to the same value (in this case a group object identifier from an Microsoft Entra ID) but the claim types differs. If this is the case, the rights assignments will not work since the type differs.

Claim remapping

In this case, there is a built in system for remapping claims that will fix the above mentioned discrepancy. Default setting in ImageVault Connect for Episerver tries to mend all known issues regarding different claim setups. To see what claims actually are sent to ImageVault you can use the following path /episerver/ImageVault.EPiServer.UI/Stores/claimsdebug/?remap=true

In this case you can see that the claim type has been remapped to use the same claim type as used in ImageVault

Type:  http://schemas.microsoft.com/ws/2008/06/identity/claims/groups   
Value: 2919e100-b494-4e34-8c89-c89a170e81c1

This remapping can be modified by adding new remapping rules or rewriting the default remap rules added in ImageVault Connect for Episerver.

var mapper = ImageVault.Client.RestApiClientFactory.DefaultClaimTypeRemapper;
mapper.ClaimTypeRemapDictionary.Clear();
//if set to true, only the list of claims in the list below will be sent over to ImageVault
mapper.OnlyIncludeMappedClaims = true;
//a name identifier must be supplied. Unique identifier for the user
mapper.AddClaimType("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier");
//a user name is also required
mapper.AddClaimType("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name");
//map any role claims
mapper.AddClaimType("http://schemas.microsoft.com/ws/2008/06/identity/claims/role");
//groups are added, even if they goes by the "groups" alias
mapper.AddClaimType("http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", "groups");

The default remap behavior is activated by the ImageVaultModule (CMS11) or by the AddImageVault() method during startup (CMS12) so be sure to perform any modifications after the module is initialized or disable the default remap rules and provide a custom remap rule during application startup.

Claim values

In some cases the difference is not in claim types but in claim values. For instance, both system lists the Adminstrators group claim but in one system, the guid (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) is used and on the other, the group name (Administrators) is used.

In this case, the system that creates the claims (your idp/Microsoft Entra ID/adfs/saml2 provider) is configured differently. The claim values cannot be translated using the remap tool.

Summary

If problem with image url:s being broken in Epi or the ImageVault gadget shows no assets when searching.

  • Make sure you have ImageVault v5.18 or later
  • Make sure you have ImageVault.EPiServer.UI v11.12 or later
  • Inspect ImageVault claims using /account/userinfo on your ImageVault instance
  • Inspect claims sent from Episerver using /episerver/ImageVault.EPiServer.UI/Stores/claimsdebug/?remap=true
  • If difference in claim type => custom remapping
  • If difference in claim values => idp configuration