{"id":7939,"date":"2026-06-26T14:35:04","date_gmt":"2026-06-26T12:35:04","guid":{"rendered":"https:\/\/blog.redbaronofazure.com\/?p=7939"},"modified":"2026-06-26T14:45:37","modified_gmt":"2026-06-26T12:45:37","slug":"offline-api-authentication","status":"publish","type":"post","link":"https:\/\/blog.redbaronofazure.com\/?p=7939","title":{"rendered":"Offline API Authentication"},"content":{"rendered":"\n

If you have locally deployed REST APIs that authenticate with Entra ID and<\/em> where the APIs need to be running 24×7, you have a problem when your site looses internet connectivity. Sure, the access tokens are valid for some more minutes, but soon you need to refresh them or do token exchange in OBO-flows<\/a> and that is when your system breaks down. It doesn’t happen often that Entra ID is unreachable, but that your site is disconnected from the internet is a real possibility. If your system needs to keep huming along offline, you need an architecture that isn’t 100% dependent on Entra ID.<\/p>\n\n\n\n

What kind of “site” are we talking about here? It can be a manufacturing site or a site supporting complex machines not connected to the public internet. Why would you involve Entra ID in such a case? Well, the management plane for you or your customers may use management APIs that are publicly available for a cloud based web frontend, but the sites operation may be local.<\/p>\n\n\n\n

In such a scenario you need an architecture where the publicly available management APIs use Entra ID for authentication, but the sites internal APIs uses something else.<\/p>\n\n\n\n

Github repo with sample code is available here<\/a>.<\/p>\n\n\n\n

Local site authentication architecture<\/h2>\n\n\n\n
\"\"<\/figure>\n\n\n\n

The local site’s internal APIs should use some authentication in addition to Entra ID that isn’t dependant on internet connectivity. Two options are certificate based authentication or a local Identity Provider deployed on the site, only to be used within the site to authenticate. In this example Keycloak will play the role of the local IDP as it can easily be deployed in a docker container. <\/p>\n\n\n\n

In this architecture, you are required to come with an Entra ID access token to be authenticated by the Management API. When the Management API is talking to any of the Local Services (or Local Services are talking to the Management API – yes, that’s a possibility!) it needs to authenticate either with a certificate or with an access token from the local IDP (Keycloak). If internet connectivity is lost, no incoming calls will be received by the Management APIs, but the Local Services can still talk to each other in an authenticated way.<\/p>\n\n\n\n

Wiring up the startup code in the APIs<\/h2>\n\n\n\n

If you have programmed authentication in aspnet REST APIs, you have had the pleasure of trying to get it right in Program.cs. Usually, its just standard code pointing to a section in appsettings.json. If you try adding Entra ID, Keycloak and certificate based authentication support, it becomes much more complicated.<\/p>\n\n\n\n

With a small extension, the authentication bootstrap code is a simple as below. Method AddCertificateBasedAuthentication does some initial setup and loads the trusted certificates while AddCertificateAuthenticationOptions handle the validation of a client supplied certificate in an API call. As Keycloak uses JWT tokens, adding support for it is doen via a simple AddJwtBearer call.<\/p>\n\n\n\n

builder.AddCertificateBasedAuthentication();\n\nbuilder.Services.AddAuthentication()\n    .AddJwtBearer(\"Entra\", options => {\n        options.Authority = builder.Configuration[\"Authentication:Entra:Authority\"]!.ToString();\n        options.Audience = builder.Configuration[\"Authentication:Entra:Audience\"]!.ToString();\n    })\n    .AddJwtBearer(\"Keycloak\", options => {\n        options.Authority = builder.Configuration[\"Authentication:Keycloak:Authority\"]!.ToString();\n        options.Audience = builder.Configuration[\"Authentication:Keycloak:Audience\"]!.ToString();\n        options.RequireHttpsMetadata = builder.Configuration.GetValue<bool>(\"Authentication:Keycloak:RequireHttpsMetadata\");\n    })\n    .AddCertificate(\"Cert\", options => {\n        options.AddCertificateAuthenticationOptions();\n    });\n<\/code><\/pre>\n\n\n\n
The code for AddCertificateBasedAuthentication <\/strong>is a bit long, but the idea is to remove as much as possible from Program.cs to avoid cluttering it. Also, putting it in a separate file makes it easy to reuse between local services. <\/p>\n\n\n\n
It first tells the Kestral engine to accept certificates that are self-signed. It then also honors the HTTP header X-Client-Cert in which reverse proxies like nginx, ngrok, etc, passes the real certificate. Then it continues loads all certificates that the service should accept. It can be multiple as you may be in a phase of swapping out old certificates. For outgoing calls that uses certificate based authentication, we need to load the PFX file as we need the passphrase. Finally we setup a HttpHandler for making outgoing certificate based authentication calls.<\/p>\n\n\n\n
    public static WebApplicationBuilder AddCertificateBasedAuthentication(this WebApplicationBuilder builder) {\r\n        \/\/ to have Kestrel accept certificates + self-signed\r\n        builder.WebHost.ConfigureKestrel(options => {\r\n            options.ConfigureHttpsDefaults(httpsOptions => {\r\n                httpsOptions.ClientCertificateMode = Microsoft.AspNetCore.Server.Kestrel.Https.ClientCertificateMode.AllowCertificate;\r\n                httpsOptions.ClientCertificateValidation = (certificate, chain, sslPolicyErrors) => { return true; };\r\n            });\r\n        });\r\n\r\n        \/\/ to handle if you're behind a reverse proxy, like nginx, ngrok, etc\r\n        builder.Services.AddCertificateForwarding(options => {\r\n            options.CertificateHeader = \"X-Client-Cert\";\r\n            options.HeaderConverter = (headerValue) => {\r\n                return X509CertificateLoader.LoadCertificate(Convert.FromBase64String(headerValue));\r\n            };\r\n        });\r\n\r\n        using var serviceProvider = builder.Services.BuildServiceProvider();\r\n        _log = serviceProvider.GetRequiredService<ILogger<Program>>();\r\n\r\n        \/\/ load all trusted\/valid certificates that clients can use\r\n        try {\r\n            \/\/ certs we accept from incoming calls (we don't need to know the cert passphrase and therefor we use the .cer file(s)\r\n            string[] validCerts = builder.Configuration.GetSection(\"Authentication:Certificate:ValidCertsPaths\").Get<string[]>() ?? [];\r\n            TrustedCertificateStore.store = LoadValidCertificates( validCerts, builder.Environment.ContentRootPath);\r\n            \/\/ cert we use when making outgoing API calls. Here we need to know the passprase and therefor we use a .pfx file\r\n            string certPath = builder.Configuration[\"Authentication:Certificate:CertPath\"]!.ToString();\r\n            string certPassphrase = builder.Configuration[\"Authentication:Certificate:CertPassphrase\"]!.ToString();\r\n            SecureString secureString = new SecureString();\r\n            certPassphrase.ToCharArray().ToList().ForEach(p => secureString.AppendChar(p));\r\n            TrustedCertificateStore.clientCert = new X509Certificate2(certPath, secureString);\r\n        } catch (Exception ex) {\r\n            _log.LogError($\"Failed to load certificates. Do not use the pfx file that is password protected. {ex.Message}\");\r\n        }\r\n\r\n        builder.Services.AddHttpClient(\"CertBasedAuthClient\")\r\n            .ConfigurePrimaryHttpMessageHandler(() => {\r\n                var handler = new SocketsHttpHandler();\r\n                handler.SslOptions.ClientCertificates = new X509Certificate2Collection();\r\n                handler.SslOptions.ClientCertificates.Add(TrustedCertificateStore.clientCert);\r\n                handler.SslOptions.RemoteCertificateValidationCallback = (sender, c, ch, e) => true;\r\n                return handler;\r\n            });\r\n\r\n        return builder;\r\n    }\r\n<\/code><\/pre>\n\n\n\n
The code for AddCertificateAuthenticationOptions <\/strong>sets up the certificate authentication options and the code for actually validating the supplied client certificate against the list of trusted certificates. The code behind ValidateClientCertificate merely matches the client subject and thumbprint against the list of trusted certificates.<\/p>\n\n\n\n
public static CertificateAuthenticationOptions AddCertificateAuthenticationOptions(this CertificateAuthenticationOptions options) {\n        options.AllowedCertificateTypes = CertificateTypes.All;                 \/\/ both chained and self-signed\n        options.ChainTrustValidationMode = X509ChainTrustMode.CustomRootTrust;  \/\/ we have our own cert store\n        options.CustomTrustStore = TrustedCertificateStore.store!;              \/\/ our cert store\n        options.RevocationMode = X509RevocationMode.NoCheck;                    \/\/ we don't check for revocation due to self-signed\n        options.ValidateCertificateUse = false;                                 \/\/ due to self-signed\n        options.Events = new CertificateAuthenticationEvents {\n            OnCertificateValidated = context => {\n                bool valid = ValidateClientCertificate(context);\n                string msg = \"Certificate is \" + (valid ? \"\" : \"not \") + $\"trusted. Subject: {context.ClientCertificate.Subject}, Thumbprint: {context.ClientCertificate.Thumbprint}\";\n                _log.LogInformation(msg);\n                return Task.CompletedTask;\n            },\n            OnAuthenticationFailed = context => {\n                string errmsg = $\"Authentication failed during certificate evaluation. {context.Exception.Message}\";\n                _log.LogInformation(errmsg);\n                context.Fail(errmsg);\n                return Task.CompletedTask;\n            }\n        };\n        return options;\n    }<\/code><\/pre>\n\n\n\n
<\/p>\n\n\n\n
Finally, Program.cs sets up some policies that an aspnet MVC controller can use to do fine grain authorization depending if it is Entra, Keycloak or certificate based authentication that is being used. A policy named “RequireCertOrKeycloak” is created so that Local Services can do authorization for internal APIs, ie the ones that require that you can provide a certificate or a Keycloak access token and not an Entra ID access token.<\/p>\n\n\n\n
builder.Services.AddAuthorization(options => {\n    options.DefaultPolicy = new AuthorizationPolicyBuilder( \"Entra\", \"Keycloak\", \"Cert\" ).RequireAuthenticatedUser().Build();\n\n    options.AddPolicy(\"RequireCertOrKeycloak\", policy => {\n        policy.AddAuthenticationSchemes(\"Keycloak\", \"Cert\");\n        policy.RequireAssertion(context => {\n            bool isKeycloakUser = context.User.HasClaim(c => c.Type == System.Security.Claims.ClaimTypes.Role && c.Value == \"uma_protection\");\n            bool isCertUser = context.User.HasClaim(c => c.Type == System.Security.Claims.ClaimTypes.Role && c.Value == \"ApiCert\");\n            return isKeycloakUser || isCertUser;\n        });\n    });\n});\n<\/code><\/pre>\n\n\n\n
Handling the API endpoint implementations<\/h2>\n\n\n\n
In the sample we have two API endpoints<\/p>\n\n\n\n