Writing Plugins for the Authorization Server

You can write custom plugins for the Authorization Server to:

• decide how users are verified via username + password: IUserLogin
• handle custom credential flows aka custom grant types: ICustomGrantSignIn
• add custom role discovery for a non-integrated identity provider: IRoleDiscovery
• to modify claims given by an external identity provider: IExternalIdpClaimsMapper
• to add custom services that your plugins might need (with reservations - if you remove required or add conflicting services, things can break)

A nuget package is provided, called AuthorizationService.Interface. If it was not part of the delivered product, contact your vendor.

Conventions

A plugin is written to adjust or define users claims, or to let the know all available roles.

The following claims are required:

• sub: each identity must have a subject claim that has the type name 'sub'
• username: the username of the user, having the claim type 'username'
• name claim: the ClaimsIdentity must have a name claim of the type of the identity's name claim type
• role claims: roles of the ClaimsIdentity are only taken into account if they have the type of the identity's role claim type

Sample implementations are made available in the AuthorizationService.PluginSample project.

• JsonFileUserLogin shows how to implement the IUserLogin and which claims are expected
• CustomEntraIDClaimMapper shows how claims coming from an IDP can be adjusted. Of course, Entra ID is supported implicitly so that a plugin for that is not required.
• CustomRoleDiscovery shows in a crude example how roles are collected via a web request. Usually, authenticated requests are required for that. Doing so, is the responsibility of the implementer.

Implementation

To write a plugin, create a new .net project and reference the AuthorizationService.Interface.dll distributed with the Authorization Server. Implement a class with a parameterless constructor for the interface IAuthorizationServerPlugin. Ensure that there exists exactly one implementation of this interface. Plugin DLLs providing multiple or zero implementations result in service failure.

There are code samples in the AuthorizationService.PluginSample project

By default, the Authorization Server provides services for IUserLogin and IExternalIdpClaimsMapper. The default user login works with Windows Active Directory only. Default services also exist for IRoleDiscovery aimed at Active Directory, Entra ID and Keycloak (at least version 19, 20, 21). An additional services automatically scrapes new roles from each authenticated user. There is no default for ICustomGrantSignIn.

public class ExampleAuthorizationServerPlugin : IAuthorizationServerPlugin
{
    /// <summary>
    /// The method configures authorization server to use custom classes.
    /// Useful methods are for example:<br/>
    /// <see cref="IUserLogin"/>, <see cref="ICustomGrantSignIn"/> as singletons.<br/>
    /// When using an external IDP (like Entra ID or Keycloak), you can plug into adjusting claims as well as providing role discovery via<br/>
    /// <see cref="IExternalIdpClaimsMapper"/> and <see cref="IRoleDiscovery"/> as transient services.<br/>
    /// </summary>
    /// <remarks>
    /// Be careful about adding additional services - you might be replacing or breaking required functionality.
    /// </remarks>
    public void SetupServices(IServiceCollection services, IConfiguration configuration)
    {
      // replaces the usual windows login
      services.TryAddSingleton<IUserLogin, CustomUserLogin>();
      services.TryAddSingleton<ICustomGrantSignIn, OurCustomGrant>();
      // adds another role discovery service
      services.AddTransient<IRoleDiscovery, CustomRoleDiscovery>();
      // adds another claims mapper
      services.AddTransient<IExternalIdpClaimsMapper, CustomClaimsMapper>(); 
    }
}

• IUserLogin: Verifies password credentials and implements support for custom grant flows.
• ICustomGrantSignIn: Receives custom request data that is transformed into a ClaimsPrincipal.
• IExternalIdpClaimsMapper: Allows to define explicitly how claims of an external IDP have to be mapped onto the authenticated ClaimsPrincipial.
• IRoleDiscovery: periodically executed and returns a list of all available roles that users may get. Only of interest if the identity provider is not supported implicitly.

Tip While developing a custom plugin it may be hard to determine the claims the authenticated principal receives. The setting Service->ShowClaimsOnHome enables displaying claims of the principal. It shows 2 sets: the claims that the user has on Authorization Server and the claims that the user has assigned to issued the access token. The IExternalIdpClaimsMapper adjusts the claims of the user for Authorization Server.

To configure the Authorization Server to use a plugin DLL, adjust manually or via a custom scripting task the appsettings.production.json found in the directory of the Authorization Server. If the file does not yet exist, you can safely create it and add the required settings. When using the platform installer, this section in the settings is not overwritten.

{
  "Service": {
    "PluginAssemblyPath": "c:\\path\\to\\your\\plugin.dll"
  }
}