Table of Contents

Troubleshooting

This page lists the errors met with the Arc4u server authentication, from the most frequent to the rarest, with their cause and fix. Several come from past GitHub issues, linked for context. The last section lists the known issues of develop/9.0.0. Start with the overview if the scenario itself is new to you, and see Concepts for the vocabulary.

Tip

Most errors are logged by the Arc4u events and middlewares with the Technical category. Enable the logs of the Arc4u and Microsoft.AspNetCore.Authentication categories at Debug level while you investigate (see Diagnostics).

Startup errors

The registration methods validate the configuration and throw when the application starts.

Message Cause and fix
No section exists with name Authentication in the configuration providers ... The Authentication section is missing, or you use another name: pass it as authenticationSectionName.
DefaultAuthority must be filled! Add Authentication:DefaultAuthority:Url.
We need a cookie name defined specifically for your services. OpenID Connect and hybrid: add Authentication:CookieName.
Audiences field is not defined. Add the audience of the tokens to OAuth2.Settings:Audiences (JWT bearer, hybrid) or OpenId.Settings:Audiences (OpenID Connect), or set ValidateAudience to false in that section. In hybrid mode, the OAuth2.Settings section is required.
ClientId field is not defined. or Scopes field is not defined. Complete Authentication:OpenId.Settings.
TokenCacheOptions.CacheName is not defined in the configuration file. The Authentication:TokenCache section exists without CacheName: add the name of one of your caches. With JWT bearer, you can also remove the section.
No certificate found for the given criteria. The data protection certificate of Authentication:DataProtection:EncryptionCertificate:Store is not in the store (or the process cannot read it). Check Name, FindType, Location and StoreName, or use the File form.
Public key file doesn't exist. or Private key file doesn't exist. A path of the File form of a certificate is wrong.
A section with name Authentication:DataProtection:CacheStore doesn't exist. Add CacheKey and CacheName for the data protection keys.
The AuthenticationMethod should be either FormPost or RedirectGet. Authentication:AuthenticationMethod has another value.
Unable to find the required services. Please add all the required services by calling 'IServiceCollection.AddAuthorization' ... Call builder.Services.AddAuthorization(): the Arc4u methods only register the authorization core services.

The exception type depends on the method and the section (ConfigurationException, MissingFieldException, InvalidOperationException, and KeyNotFoundException or FileNotFoundException for the certificates): search for the message.

Note

Arc4u 8.3.0 threw an ArgumentNullException on MetaDataAddress when the metadata address was not configured (#153). Since 8.3.1 the address defaults to <Url>/.well-known/openid-configuration.

API calls

Every call returns 401

Check, in this order:

  1. The aud claim of the token is in OAuth2.Settings:Audiences. When it is not, the response detail says that the audience is invalid (the explicit message was requested in #35).
  2. The token is not expired: the response has an x-token-expired header when it is.
  3. The server can download DefaultAuthority:MetaDataAddress. Behind a private certificate authority, see Custom root CA.
  4. The token is signed by the keys of that metadata: a token of another identity provider or environment fails.
  5. The iss claim is DefaultAuthority:Issuer, or the issuer of the metadata when it is not set. When it is not, the response detail says that the issuer is invalid. Set DefaultAuthority:Issuer to the issuer of your tokens, see What is validated.

401: The token has no claim identifying the user

The log says The token has no claim identifying the user (...) (event id 9150): the claims filler is enabled and none of the Authentication:ClaimsIdentifier claim types is in the token. With the OpenID Connect cookie, the request fails with a 500 NullReferenceException: No distinguish key found for the identity .... The default claim types (http://schemas.microsoft.com/identity/claims/objectidentifier, oid) are Microsoft identity platform claims; other providers usually identify the user with sub. Set it to a claim of your tokens, for example "ClaimsIdentifier": [ "sub" ]. See Identity providers.

500: Bad Arc4u usage

InvalidOperationException: Bad Arc4u usage. comes from the Arc4u logging extensions: ILogger<T> is not the Arc4u logger. Call builder.Services.AddApplicationContext() (or AddILogger(), namespace Arc4u.Dependency, package Arc4u.Diagnostics), see Code.

403 with [Authorize(Roles = ...)] although the token has the role

AppPrincipal.IsInRole checks the roles of the Arc4u authorization, not the role claims of the token. See Roles and IsInRole.

Operation policies always fail

The principal has no authorization: implement a claims filler that returns the Arc4u authorization claim, see Load the user's rights.

Requests fail with "An entry of the authorization operations (or roles) has no scope"

The authorization returned by your claims filler has an entry of operations or roles without scope, and the principal cannot be created (ConfigurationException). Give every entry a scope; use the empty string ("scope": "") for the default scope, the one checked by the methods without a scope parameter.

Caches are not initialized

The memory, Redis and SQL Server caches need an IObjectSerialization registration (JsonSerialization of Arc4u.Serializer.JSon), and the data protection key store resolves it too. Without it, the cache logs that it is not initialized. A missing registration used to fail silently in token handlers (#81).

Browser sign-in

"There was an issue during the request: Invalid audience." or "... Invalid authority."

The access token returned at sign-in has an audience that is not in OpenId.Settings:Audiences, or an issuer different from DefaultAuthority:Issuer (or the issuer of the metadata when it is not set). See Token checks.

"You are not authenticated." with a 500

The sign-in threw an exception, logged by StandardOpenIdConnectEvents. With OpenId.Settings:ValidateAudience: false, older versions failed with a KeyNotFoundException for the key Audiences (#220): upgrade, or see Disable the audience check.

The identity provider rejects the redirect URI

Behind a proxy that ends TLS, the application sees http. Arc4u forces https in the redirect URI except for http://localhost (#131); forward the original host with the forwarded headers middleware if the proxy changes it. See Run behind a TLS-terminating proxy.

Users are signed out after the lifetime of the access token

No refresh token was issued: request offline_access (or your provider's equivalent) in OpenId.Settings:Scopes. See Session and refresh.

Users lose their session when the application restarts or scales out

The data protection keys or the tickets are in a memory cache. Use a cache shared by the instances for Authentication:DataProtection:CacheStore and the ticket store.

Browser requests get a 401 in hybrid mode

The default challenge scheme is JWT bearer. See Hybrid.

The first sign-in of a Blazor WebAssembly application fails

This is a client-side issue (#155), see Client authentication.

Known issues

The following behaviors of develop/9.0.0 are known. They are described where they matter, with a workaround when there is one.

Area Issue Workaround
OpenID Connect, hybrid Security: the audience check of the access token is a substring search in the space-separated list of OpenId.Settings:Audiences, so an aud that is part of a configured audience (api://my for api://my-api) is accepted. Use audiences that no other audience of your provider is a part of, or register the exact check of Token checks.
Custom root CA When the standard certificate validation fails, ConfigureLocalCaCertificate (and ConfigureLocalCaCertificateForGrpc) only check the chain: a certificate of the custom authority for another host name is accepted. Issue certificates of the private authority only to trusted services.

See also

Edit this page