Authenticating API Callers

Authentication answers one question: who is calling? Authorisation answers a different one: may they do this? This lesson covers only the first, and the next lesson covers the second. Keeping them separate is not pedantry — most of the serious mistakes in this area come from an endpoint that answered the first question and assumed it had answered both.

The common mechanism for an API is a bearer token. The caller obtains a token from an identity provider, sends it on every request in the Authorization header, and your API decides whether to believe it. "Bearer" means possession is enough: whoever holds the token can use it, which is why tokens are short-lived and why they never belong in a URL or a log.

The most important sentence in this lesson: decoding a token is not validating it. A JWT is three base64url-encoded parts joined by dots. Base64url is an encoding, not encryption, so anyone holding the token can read every claim inside it with a text editor. Decoding tells you what the token says. It tells you nothing about whether the token is genuine.

Validation is the separate step that checks the signature against a key you trust, confirms the issuer and audience are ones you accept, and confirms the token is within its lifetime. Only after that do the claims mean anything. A handler that reads a user id out of an unvalidated token is reading a value the caller could have typed.

Two consequences follow. Never put anything confidential in a token, because its contents are readable by anyone who has it. And never take claims from a token your framework has not validated — which in practice means letting the authentication middleware do the work rather than parsing the header yourself.

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        // Placeholders — real values come from configuration, never from source
        options.Authority = builder.Configuration["Auth:Authority"];
        options.Audience = builder.Configuration["Auth:Audience"];
        options.RequireHttpsMetadata = true;

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            ValidateIssuer = true,
            ValidIssuer = builder.Configuration["Auth:Authority"],
            ValidateAudience = true,
            ValidAudience = builder.Configuration["Auth:Audience"],
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30)
        };
    });

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

• Authority is the identity provider's address. From it the framework discovers the provider's public signing keys, fetches them, caches them and refreshes them when the provider rotates them, so no key material lives in your application.
• ValidateIssuerSigningKey with ValidateIssuer is the pair that makes the token trustworthy: the signature checks out, and it was produced by the issuer you named.
• ValidateAudience matters more than it looks. Without it, a valid token issued for a different API in the same organisation is accepted by yours — the signature is genuine, and it was never meant for you.
• ClockSkew allows for clocks that disagree slightly between the issuer and your server. The default allowance is five minutes, which extends the life of an expired token by that much; thirty seconds is a common tightening.
• UseAuthentication must come before UseAuthorization. The first establishes who the caller is; the second decides what they may do, and it has nothing to work with if the order is reversed.
• RequireHttpsMetadata keeps key discovery on HTTPS. It is the default outside development, and it is worth stating so nobody turns it off by copying a development snippet.