Authentication using Microsoft Entra ID

This SecurityModule uses federated authentication and is using the Microsoft Entra ID v2.0 endpoint (Microsoft.Graph).

Microsoft Entra ID

To be able to use authentication using Microsoft Entra ID you need a tenant in Azure. Create users, groups and App roles in your Azure tenant or set up a directory synchronize with your on-premises AD.

Create application

To create an application in the Microsoft Entra:

  • navigate to the azure portal.
  • Select App registrations and click New application registration
  • Give it a suitable name, preferably the url of the imagevault site.
  • Enter the URL to the ImageVault site as redirect uri.
  • When the application is created you must add an App ID URL. Use the suggested or enter the url of the site. There is no need to specify any scopes.

Create an application key

Since ImageVault needs to read information from the ad, we need to create a key that allows us to communicate with the ad. This is done in the Certificates & Secrets tab for the application. Click on + New client secret and enter a descriptive name as Description and select a duration. It is recommended that you choose the max duration to minimize administration since the key needs to be reissued when it expires.

When saving the key, the key value will be visible (just once) so be sure to copy it and store it before leaving the tab (see its usage below).

Assign permissions

To be able to read information from Microsoft Entra ID you need to add the following permissions for the application. This is done in the API permissions tab.

  • Microsoft.Graph -> Delegated Permission -> User.Read
  • Microsoft.Graph -> Application Permissions -> User.Read.All
  • Microsoft.Graph -> Application Permissions -> Group.Read.All
  • Microsoft.Graph -> Application Permissions -> Application.Read.All
Note

Since some of the permissions above requires Admin permissions you need to click the "Grant permissions" on the required permissions form to complete the assignment.

Warning

Previous versions used the Microsoft Entra ID Graph API and the permissions for this API currently works for Microsoft.Graph as well We recommend that you switch these permissions to the one defined above, since the Microsoft Entra ID Graph api is on a deprecation path

Automatically add groups to user claims

Normally in Microsoft Entra ID, the groups that a user is assigned to is not included in the claims received when logging in. To activate this, you need to edit the manifest for the application.

Open the application in the Microsoft Entra ID. Click on the Manifest tab.

Edit the manifest that pops up and set the "groupMembershipClaims" to "All" or "SecurityGroup" (SecurityGroup will not include distribution lists).

"groupMembershipClaims": "SecurityGroup",

Save the file by clicking the Save link in the tabs toolbar.

Note

App role claims requires no configuration, it will be included automatically.

Alternate group token configuration

From v5.25

You can also configure the Microsoft Entra ID application to send group claims using other than default token values. In order to map the emitted claims in the token with the tokens supplied by the lookup service you also need to configure the GroupClaimValue. The following combinations are allowed

Group claim token value GroupClaimValue
Group Id id
sAMAccountName name
NetBIOSDomain\sAMAccountName NetBIOSDomain\name
DNSDomain\sAMAccountName DNSDomain\name
On Premises Group Security Identifier securityIdentifier
Note

Emit groups as role claims are not supported

ImageVault UI

To activate Microsoft Entra ID authentication the following changes must be done in web.config.

Authentication

When using Microsoft Entra ID authentication, the authentication mode must be set to None.

<system.web>
    <authentication mode="None"/>

ConnectionStrings

To use Microsoft Entra ID with ImageVault add/modify the connection string named ImageVaultSecurityManager.

<connectionStrings>
    <add name="ImageVaultSecurityManager"
         providerName="ImageVault.Adal.Providers.AdalSecurityManager,ImageVault.Adal.Providers"
         connectionString="Tenant=mydemo.onmicrosoft.com;ClientId=9ae0db67-4d7b-5d45-8ef2-965679509e6c;AppKey=ZoLTp7Koz5SdGxIH+9fiPcEpyDVKFdWRPbiK5pKo2jQ="/>
</connectionStrings>

name

Must be ImageVaultSecurityManager for the UI to detect which connection string that should be used for the SecurityManager

providerName

Tells ImageVault.UI which SecurityManager it will use (See the ISecurityManager for more information)

For Microsoft Entra ID, use the following providerName: ImageVault.Adal.Providers.AdalSecurityManager,ImageVault.Adal.Providers

connectionString

This is a key value string where key and value are separated by equals (=) and each pair is terminated with a semicolon (;)

Here comes a list of the possible keys (keys are case-insensitive)

Tenant

This is the name of the domain that your Microsoft Entra ID is connected to. This can be a custom domain or a default domain that Azure has assigned the directory when creating it (like mydirectory.onmicrosoft.com).

You can also use the GUID found in the application endpoint list as the tenant.

ClientId

This is the Application ID for the application. You find it as a GUID when opening the applications tab.

AppKey

This is the key value that you generated for the application.

Optional connectionString keys

The following configuration options all have default values and only needs to be adjusted if you need to change the default behavior.

Wtrealm

This is the URL to the application that you entered as App ID URI. In later versions of Microsoft Entra ID uses the format spn:clientId. The default value is spn:clientId

AADInstance

The URL to the Microsoft Entra ID instance. The default is "https://login.windows.net".

LogoutUrl

The local URL that is used for logout. Will be remapped to a federated logout. The default is "/account/logout".

LoggedoutUrl

The landing URL to use after a federated logout. The default is "${Wtrealm}/account/loggedout"

Metadata

From v5.15

The url to the federated metadata document. The default is "${AADInstance}/${Tenant}/federationmetadata/2007-06/federationmetadata.xml"

EnableGetGroupsFromAd

If true, the group assignment will be requested from the ad after a login and added to the user. A better approach is to include the group/role claims in the ticket from the beginning, using the automap feature described above. The default is false.

CacheTimeout

The timeout in minutes for data retrieved from the ad to be cached. The default is 10.

IdentityPrefix

If multiple UI are using the same core but with different user directories, this prefix can be used to guarantee uniqueness between different ad:s. The identity prefix is appended to each claim value

GroupClaimValue

From v5.25

When mapping group claims using the lookup service, the type is always http://schemas.microsoft.com/ws/2008/06/identity/claims/groups but the value to use can be configured using this option. This should be the same token that is configured as group token in the Microsoft Entra ID application.

GroupClaimValue Description
id (default) Will use the group id
name Will use the group name (using the OnPremisesSamAccountName or DisplayName if missing)
NetBIOSDomain\name Will use the netbios domain name as prefix to the name above
DNSDomain\name Will use the dns domain name as prefix to the name above
securityIdentifier Will use the security identifier from the on premises system (when active sync is used)
Note

Be sure to configure the group tokens in the Microsoft Entra ID accordingly or else the assigned rights will not be correctly assigned. See alternate group token configuration

UserClaimValue

From v5.25

When mapping user claims using the lookup service, the type is always http://schemas.microsoft.com/identity/claims/objectidentifier but the value to use can be configured using this option. This should be the same token that is used to create the ticket in the Microsoft Entra ID application.

UserClaimValue Description
id (default) Will use the user id
name Will use the user principal name, often the email address of the Microsoft Entra ID user

AppRoleClaimValue

From v5.25

When mapping app role claims using the lookup service, the type is always http://schemas.microsoft.com/ws/2008/06/identity/claims/role but the value to use can be configured using this option.

AppRoleClaimValue Description
id (default) Will use the app role value
name Will use the app role display name

ForceHttpsWReply

From v5.29

When using Microsoft Entra ID, the wreply uri must be https. If you are using http in your site (perhaps by offloading the SSL tunnel on a load balancer), you can set this option to true to force the wreply uri to be https. Default value is false.

ForceLoggedOutUrlAsWReply

From v5.29

Forces the wreply to always use the value entered as LoggedoutUrl url. The default is false.

Known issues