Why Authentication Matters: The Passport Every .NET API Needs

The passport analogy

What is authentication and why do we need it?

A good analogy is to think about the concept of authentication as a passport. If you want to get into a country, you have to show them your passport.

It proves who you are.

How does it prove who you are?

Somebody who knows who you are (the government of your home country) gave it to you and that certifies that you actually are you.

Well how do they know who you are?

At some point you had to give your government some documents, like your birth certificate, a letter from your electricity provider with your address, etc. to prove who you are. They were satisfied with those documents and issued you a passport.

The passport isn't valid for ever. It has a date of expiry and to continue to get back into your country, you'll have to apply for a new passport with another future expiry date.

If actually you do some criminal activity, your government can even cancel your passport early and might never give you another one.

Lastly, there are different kinds of passports. If you're just a normal citizen, you have to wait in line at border checkpoints, you have to pay for your own food. But if you're a diplomat, you're a special government employee and you don't wait at border checkpoints; you fly business class, you have access to special lounges at the airport and you get given a champagne lunch before boarding the plane.

The governments of other countries might have an agreement with your country and if you present your passport to them, they'll trust you and allow you access.

However, when you go through a border checkpoint, they're not going to accept your birth certificate and proof of address. You have to show them your passport or you can't enter.

Linking passports to code

So, now that I've described what authentication (and authorisation) are from the perspective of a passport, let's link this to software development.

The birth certificate, the proof of address, etc. represent your credentials (usually a username and password) which you send to a trusted authority, which will be a login endpoint or an identity server.

The trusted authority checks your credentials, usually against a database entry or an identity provider like Entra ID, then sends you an authentication token, which correlates to your passport.

This token can come in many forms, but in modern web API's it's most common to use JWT (JSON Web Tokens). A JWT is digitally signed so when you give it to the authority to try to access their system, they can quickly check the signature to confirm that they actually signed it and therefore that it is a valid token.

You can use it multiple times to access the system that you're authenticated for until it expires, then you can refresh it and continue to access the system with a new token.

This saves you from having to send usernames and passwords every time you try to access a system, which besides being inconvenient, is also a security risk and requires a database call every time, which slows down the whole process.

Authentication vs. Authorisation

The type of passport you hold corresponds to the difference between authentication (AuthN) and authorisation (AuthZ).

Authentication is just your ability to prove who you are.

Authorisation says what privileges you have. When an authority gives you a JWT, it not only gives you permission to access their system, it also says what level of access you can have. All of that data is stored as claims in the token and can be verified by checking them against the token's signature.

Why modern APIs use JWT

Of course there are other ways to authenticate, for example many websites use cookies, which are still a totally valid way to authenticate a user.

When I worked at UBS (a Swiss bank), they were using SAML2.0 (XML) and certificate authentication. That's fine for highly regulated environments like banks, but for most modern applications, JWT is a simpler, more flexible choice.

The whole topic can be a little confusing.

Here is the RFC if you want to look for yourself: https://www.rfc-editor.org/rfc/rfc7519

It gets even more complicated when it comes to coordinating between identity providers, following standards like OAuth 2.0 and OpenID Connect, combining different authentication methods, revocation of tokens, refreshing tokens and concepts like federation.

I'm still learning all this stuff myself. But that's why I'm writing this blog, so you can join me on this journey to understand JWT authentication and we can understand it together.

Join the journey

Join me next week where I will explain the basics of what a JWT is (with code). Subscribe now (for free) to get the next post on JWT basics straight to your inbox, plus code samples you can copy and paste!