How to add Microsoft Identity to startup in v3?

[adamfisher]

In v2 we did something like this:

services.AddRazorPages(options =>
{
	options.Conventions.AuthorizeFolder("/");
	options.Conventions.AllowAnonymousToFolder("/endpoints");
}).AddMicrosoftIdentityUI();

But curious how this would be configured or done in the v3 code below? The UseAdminUserProvider() call would obviously go away but wondering what options I need to setup for it to use Azure AD based authentication like we did in v2 above? ☝️

// Default Identity features for authentication/authorization.
elsa.UseIdentity(identity =>
{
	identity.TokenOptions = options => options.SigningKey = "sufficiently-large-secret-signing-key"; // This key needs to be at least 256 bits long.
	identity.UseAdminUserProvider();
});

[adamfisher]

I added a Stack Overflow question to hopefully spur a little more conversation around this since not having much luck here:
https://stackoverflow.com/questions/77861951/connect-elsa-v3-to-azure-ad

[adamfisher]

Related to #2681. @sfmskywalker has there been any update on supporting Azure Identity in Elsa v3? You mentioned last May a customer was working on an implementation so curious what that looks like if it's available?

[adamfisher]

Even if you just have broad strokes I am willing to implement with a bit of guidance. I posted a detailed approach I was pursuing in that StackOverflow link above.

[sfmskywalker]

No update on that customer's situation; they're still using the built-in authentication method. However, if you're considering adding Azure AD authentication, the process might look something like this (though I haven't implemented this myself, so there could be some gaps in my understanding):

1. Remove the UseIdentity() Call: You should be able to remove the UseIdentity() call and possibly even the entire reference to the Elsa.Identity package.

2. Leverage Built-in Authorization in Elsa API Endpoints: Since these endpoints are implemented using FastEndpoints, you'd configure your ASP.NET Core app that employs Elsa with Azure AD in the same way you would with any traditional ASP.NET Core application.

3. Handle the Permissions Claim: An important aspect is that FastEndpoint classes expect a permissions claim. This claim might be hardcoded when establishing the ClaimsPrincipal. Alternatively, and perhaps more elegantly, you could potentially provision this claim directly from the Azure AD management UI. This is a bit of speculation on my part, but it seems like a feature a standard identity provider service would offer.

4. Adjusting the ClaimsPrincipal: Look into ways to hook into the process of establishing a ClaimsPrincipal to supply additional claims.

5. Customize the Elsa Studio Login: The Elsa Studio login includes a Login module that you'll need to replace or modify. This entails redirecting users to the Azure AD login page and ensuring they return with an access token, and ideally, a refresh token.

This outline skips over many finer details and potential complexities, particularly regarding extensibility points that may need to be added or re-engineered.

I was hoping to have personally navigated through this process by now, but alas, it remains on my to-do list. It seems you've jumped ahead in this adventure - kudos to you for taking the leap! 😄

[adamfisher]

I tried removing Elsa identity package but it complains that a signing key is needed upon startup so I guess I needed UseIdentity() still,

It looks like the only permission today is everything * as defined here.

So this is what I have so far (I'll clean it up later - just trying to get it working). However a redirect doesn't happen. In v2 redirection happened with that AddRazorPages() section present. 🤔

services
	.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
	.AddJwtBearer(options =>
	{
		options.Authority = $"https://login.microsoftonline.com/{configuration.GetValue<string>("AzureAd:TenantId")}";
		options.Audience = configuration.GetValue<string>("AzureAd:ClientId");
		options.Events = new JwtBearerEvents
		{
			OnTokenValidated = context =>
			{
				var claimsIdentity = context.Principal.Identity as ClaimsIdentity;
				claimsIdentity.AddClaim(new Claim("permissions", "*"));
				return Task.CompletedTask;
			}
		};
	})

services.AddRazorPages(options =>
{
	options.Conventions.AuthorizeFolder("/");
	options.Conventions.AllowAnonymousToFolder("/endpoints");
}).AddMicrosoftIdentityUI();

[sfmskywalker]

I opened an issue requesting documentation which includes walkthroughs and reference implementations. Unfortunately, this doesn't help you for now of course.

[zuntio]

Here is my approach. Using separate services with Elsa Web and Elsa Studio Server with .NET8. WASM not supported with these libraries and helpers.

---

1. Microsoft Entra Setup

Create separate app registrations for Studio and Backend. Create group for authenticated users, for example ElsaAdmins and add yourself initially into it.

1.1. Backend App Registration setup

Expose API for FrontEnd by opening App Registration and under Manage -> Expose an API. Add Scope and name it for example ApiAccess. Let both Admins and users consent and fill rest of the fields freely. Set state as "Enabled" and click "Add scope".

Define a role for Backend from App Roles under the Manage section, for example with value Elsa.Core.Admin. Set Allowed member types as Users/Groups.

1.2. Studio App Registration setup

Open "Api Permissions" from the Manage section and hit "Add a permission". From there search exposed from "APIs my organization uses" or "My APIs", whatever convenient. After selecting Backends app registration, set "Delegated permissions" active if not already and tick the created permission and finally, "Add permissions".

Define a role for Backend from App Roles under the Manage section, for example with value Elsa.UI.Admin. Set Allowed member types as Users/Groups.

From "Certificates and secrets" under the Manage section, generate new Client secret and store client secret for later use.

From "Authentication" under the Manage section, add new platform configuration. Select "Web" and enter https://yourhost/signin-oidc as Redirect URI of the application and hit "Configure". From "Select the tokens you would like to be issued by the authorization endpoint:" tick both Access tokens and ID tokens.

1.3. Role mapping

From the starting page of Microsoft Entra ID, open Enterprise Applications from the Manage section and do the same for both applications. Open the corresponding application and yet again from the Manage section open "Users and groups". Add previously created security group and assign it to corresponding Role, in my example Elsa.Core.Admin in Backend and Elsa.UI.Admin in Studio. This concludes the Azure and Entra.

2. Elsa Web Backend

2.1. appsettings.json

Remove all Elsa.Identity related invocations from Program.cs and references too. Configure appsettings.json with values from the Backends App Registration:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "your-backend-appregistration-clientid",
    "TenantId": "your-backend-appregistration-tenantid"
  }
}

2.2. Packages

Reference package Microsoft.Identity.Web.

2.3. Services

Add Authentication:

services
   .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
   .AddMicrosoftIdentityWebApi(configuration);

Implement IClaimsTransformation and add it to servicecollection:

public class ElsaPermissionTransformation : IClaimsTransformation
{
    /// <inheritdoc />
    public Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        if (principal.Identity is not ClaimsIdentity claimsIdentity)
            return Task.FromResult(principal);
        
        if (principal.IsInRole("Elsa.Core.Admin"))
            claimsIdentity.AddClaim(new("permissions", "*"));

        return Task.FromResult(principal);
    }
}

Later if you need to specify permissions in more detailed manner, you add more security groups in Entra and assign them to the corresponding roles and in this implementation you do some more iffing.

services.AddTransient<IClaimsTransformation, ElsaPermissionTransformation>();

3. Elsa Studio

I'm not really frontend oriented so I hope at least this will provide you some good laughs :)

Firstly, remove reference to Login module and all related invocations from Program.cs

3.1. appsettings.json

{
  "Backend": {
    "Url": "https://yourhost/elsa/api"
  },
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-frontend-appregistration-tenantid",
    "ClientId": "your-frontend-appregistration-clientid",
    "ClientSecret": "your-frontend-appregistration-clientsecret",
    "CallbackPath": "/signin-oidc"
  },
  "ElsaBackend": {
    "Scopes": ["api://application-id-uri-from-backend-appreg-api-exposing/ApiAccess"],
    "BaseUrl": "api://application-id-uri-from-backend-appreg-api-exposing"
  }
}

3.2. Packages

Import packages Microsoft.Identity.Web, Microsoft.Identity.Web.UI and Microsoft.Identity.Web.DownstreamApi to the project

3.3. Helper services

3.3.1 AuthenticationStateProvider

public class AdAuthenticationStateProvider : AuthenticationStateProvider
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    private static readonly AuthenticationState EmptyAuthState = new(new());

    public AdAuthenticationStateProvider(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    /// <inheritdoc />
    public override async Task<AuthenticationState> GetAuthenticationStateAsync()
    {
        var user = _httpContextAccessor.HttpContext?.User;

        if (user is null)
            return EmptyAuthState;
        
        return user.Identity?.IsAuthenticated ?? false 
            ? new(user) 
            : EmptyAuthState;
    }
    
    /// <summary>
    /// Notifies the authentication state has changed.
    /// </summary>
    public void NotifyAuthenticationStateChanged()
    {
        NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
    }
}

3.3.2. JWT Handler

Maybe should snip few minutes out from the expires on so last second expirations don't result in 401/403.

Yes, tokens are cached also in ITokenCache behin ITokenAcquisition but could not really figure out how to use it in delegating handler and reasonably handle possible consents.

public interface IBackendJwtHandler
{
    ValueTask TrySaveTokenAsync();
    bool TryGetToken(out string? token);
}

public class ElsaBackendJwtHandler : IBackendJwtHandler
{
    private readonly ITokenAcquisition _tokenAcquisition;
    private readonly IHttpContextAccessor _httpContextAccessor;
    private readonly IMemoryCache _memoryCache;
    private readonly IConfiguration _configuration;
    private const string ScopesKey = "ElsaBackend:Scopes";

    public ElsaBackendJwtHandler(ITokenAcquisition tokenAcquisition,
        IHttpContextAccessor httpContextAccessor,
        IMemoryCache memoryCache,
        IConfiguration configuration)
    {
        _tokenAcquisition = tokenAcquisition;
        _httpContextAccessor = httpContextAccessor;
        _memoryCache = memoryCache;
        _configuration = configuration;
    }

    /// <inheritdoc />
    public async ValueTask TrySaveTokenAsync()
    {
        if (_httpContextAccessor.HttpContext?.User is not {Identity.IsAuthenticated: true} user)
            return;
        var key = GetKey(user);
        var scopes = _configuration.GetSection(ScopesKey).Get<string[]>()!;
        var result = await _tokenAcquisition.GetAuthenticationResultForUserAsync(scopes);

        _memoryCache.Set(key, result.AccessToken, result.ExpiresOn);
    }

    /// <inheritdoc />
    public bool TryGetToken(out string? token)
    {
        token = null;
        if (_httpContextAccessor.HttpContext?.User is not {Identity.IsAuthenticated: true} user)
            return false;
        var key = GetKey(user);
        return _memoryCache.TryGetValue(key, out token);
    }

    private string GetKey(ClaimsPrincipal user) =>
        $"{user.GetLoginHint()}-{user.GetObjectId()}-{user.GetHomeTenantId()}";
}

3.3.3. DelegatingHandler for Elsa Client

public class ElsaBackendAuthenticationHandler : DelegatingHandler
{
    private readonly IBackendJwtHandler _backendJwtHandler;

    public ElsaBackendAuthenticationHandler (IBackendJwtHandler backendJwtHandler)
    {
        _backendJwtHandler = backendJwtHandler;
    }


    /// <inheritdoc />
    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (!_backendJwtHandler.TryGetToken(out var token))
            return await base.SendAsync(request, cancellationToken);
        
        const string schema = "Bearer";
        var sanitizedToken = token!.StartsWith(schema) ? token[(schema.Length + 1)..] : token;
        request.Headers.Authorization = new(schema, sanitizedToken);

        return await base.SendAsync(request, cancellationToken);
    }
}

3.3.4 Feature

By registering this executing assembly is included in Routers AdditionalAssemblies

public class Feature : FeatureBase 
{
}

3.4 Components

3.4.1 RedirectToAzureAdLogin

public class RedirectToAzureAdLogin : ComponentBase
{
    /// <summary>
    /// Gets or sets the <see cref="NavigationManager"/>.
    /// </summary>
    [Inject] protected NavigationManager NavigationManager { get; set; } = default!;

    /// <inheritdoc />
    protected override Task OnAfterRenderAsync(bool firstRender)
    {
        NavigationManager.NavigateTo("ad-login", true);
        return Task.CompletedTask;
    }
}

3.4.2 ExtendedApp

This new root element basically takes care of keeping up-to-date Access token for backend in cache and if consent is required, it will be handled. Breaks DownstreamApi pattern a bit, but basically same stuff under the hood. Had to ditch idea of using Blazored LocalStorage since getting exceptions on accessing jsInterop on Prerendered + OnInitializedAsync combination everywhere.

public class ExtendedApp : App
{
    /// <summary>
    /// Gets or sets the <see cref="NavigationManager"/>.
    /// </summary>
    [Inject] protected NavigationManager NavigationManager { get; set; } = default!;

    [Inject] protected MicrosoftIdentityConsentAndConditionalAccessHandler ConsentHandler { get; set; } = default!;
    [Inject] protected IBackendJwtHandler BackendJwtHandler { get; set; } = default!;

    /// <inheritdoc />
    protected override async Task OnInitializedAsync()
    {
        var httpContext = BlazorServiceAccessor.Services.GetRequiredService<IHttpContextAccessor>().HttpContext;
        // Early exit if we are already redirected
        if (NavigationManager.Uri.Contains("/MicrosoftIdentity/Account/Challenge"))
            await base.OnInitializedAsync();
        
        try
        {
            await BackendJwtHandler.TrySaveTokenAsync();
        }
        catch (Exception ex)
        {
            ConsentHandler.HandleException(ex);
        }

        await base.OnInitializedAsync();
    }
}

3.4.3. IUnauthorizedComponentProvider implementation

public class RedirectToAzureAdLoginComponentProvider : IUnauthorizedComponentProvider
{
    /// <inheritdoc />
    public RenderFragment GetUnauthorizedComponent()
    {
        return builder => builder.CreateComponent<RedirectToAzureAdLogin>();
    }
}

3.5 Pages

3.5.1 AdLogin.razor

@page "/ad-login"
@using MudBlazor
@using Elsa.Studio.Components
@using Elsa.Studio.Layouts
@inherits StudioComponentBase
@layout BasicLayout

<div class="d-flex justify-end flex-grow-1">
    <MudIconButton Icon="@Icons.Material.Outlined.Book" Color="Color.Inherit" Link="https://v3.elsaworkflows.io/" Target="_blank" Title="Documentation"/>
    <MudIconButton Icon="@Icons.Custom.Brands.GitHub" Color="Color.Inherit" Link="https://github.com/elsa-workflows/elsa-core" Target="_blank" Title="Source code"/>
</div>

<MudContainer MaxWidth="MaxWidth.Small">
    <MudStack Spacing="10">
        <MudPaper Elevation="1">
            <MudGrid Spacing="0" Justify="Justify.Center">
                <MudItem md="9" xs="7" Class="pa-4 mx-auto my-4">
                    <MudStack Spacing="1">
                        <MudText Typo="Typo.h5">Login</MudText>
                        <MudButton OnClick="AdLoginAsync">AD Login</MudButton>
                    </MudStack>
                </MudItem>
            </MudGrid>
        </MudPaper>
    </MudStack>
</MudContainer>

3.5.2. AdLogin.razor.cs

[AllowAnonymous]
public partial class AdLogin
{
    [Inject] private NavigationManager NavigationManager { get; set; } = default!;
    [Inject] private AuthenticationStateProvider AuthenticationStateProvider { get; set; } = default!;

    private async Task AdLoginAsync()
    {
        var returnUri = NavigationManager.ToBaseRelativePath(NavigationManager.BaseUri) + "/post-login";
        NavigationManager.NavigateTo($"/MicrosoftIdentity/Account/SignIn?redirectUri={returnUri}", true);
    }
}

3.5.3. PostLogin.razor

Empty page after login to enforce AuthenticationStateChange

@page "/post-login"
@using Microsoft.AspNetCore.Components.Authorization
@inject NavigationManager NavigationManager
@inject AuthenticationStateProvider AuthenticationStateProvider; 
<h3>PostLogin</h3>

@code {
    /// <inheritdoc />
    protected override Task OnInitializedAsync()
    {
        ((AdAuthenticationStateProvider)AuthenticationStateProvider).NotifyAuthenticationStateChanged();
        NavigationManager.NavigateTo("", true);
        return base.OnInitializedAsync();
    }
}

3.6. Code configuration

3.6.1. Add our custom stuff

        services
            .AddAuthenticationCore()
            .AddOptions()
            .AddHttpContextAccessor()
            .AddScoped<ElsaBackendAuthenticationHandler>()
            .AddScoped<AuthenticationStateProvider, AdAuthenticationStateProvider>()
            .AddScoped<IUnauthorizedComponentProvider, RedirectToAzureAdLoginComponentProvider>()
            .AddSingleton<IBackendJwtHandler, ElsaBackendJwtHandler>()
            .AddMemoryCache()
        ;

3.6.2. Add Azure AD

        services
            .AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
            .AddMicrosoftIdentityWebApp(configuration)
            .EnableTokenAcquisitionToCallDownstreamApi()
            .AddDownstreamApi("ElsaBackEnd", configuration.GetSection("ElsaBackEnd"))
            .AddInMemoryTokenCaches();

        services.AddAuthorization(options => options.FallbackPolicy = options.DefaultPolicy);

3.6.3. Add MS Identity UI and Consent Handler

        services
            .AddRazorPages()
            .AddMicrosoftIdentityUI();
        services
            .AddRazorComponents()
            .AddInteractiveServerComponents(
                circuitOptions => circuitOptions.RootComponents.RegisterCustomElsaStudioElements())
            .AddMicrosoftIdentityConsentHandler();

3.6.4. Assign correct delegating handler

        services.AddRemoteBackend(
            elsaClient => elsaClient.AuthenticationHandler = typeof(ElsaBackendAuthenticationHandler),
            options => configuration.GetSection("Backend").Bind(options));

3.6.5. Add Feature

services.AddScoped<IFeature, Feature>();

3.6.6. MapControllers

This on is crucial for Identity controllers to be available

app.MapControllers();

3.6.7. Modify _Host.cshtml

Change <component type="typeof(App)" render-mode="ServerPrerendered"/> to <component type="typeof(ExtendedApp)" render-mode="ServerPrerendered"/>

---

Phew. I hope I succeeded to include everything. Feedback is highly appreciated and improvements also. Thank you for the amazing Workflow engine!

[LinQiaoPorco]

Thanks for a detailed guidance! I have one question: Why the Elsa Studio WASM can not use this?