16. Security with OpenId Connect

Using Claims-Based Security

Claims-based security uses a token to represent the user, and this token is a collection of claims about the user. Claims represent statements about the user; for example, one claim could be that the user’s first name is Peter. In real life, we also have tokens; for example, your passport is a nice example of a token, containing claims such as your nationality, name, date of birth, etc. If this was all there about a token, they would be worthless because anyone could create a token. Why does the airport security trust your passport? Because it was issued by a trusted party, also known as an identity provider . In my case, the airport security trusts the claims on my passport because it was issued by the Belgian government. Passports use all kinds of nifty protections such as holograms to make it hard to create a passable fake passport. Tokens used by computers work in the same manner; they are issued by a trusted party, which uses a digital signature so that the relying party (the application) can verify to see if the token was issued by a trusted party known to the application. Of course, the identity provider will need a way to verify who the user actually is. They can use any means they want, a user and password combination, or some smart card you need to insert in a card reader. This whole process is illustrated in Figure 16-1.

One more aspect about tokens is that once a user has received a token, the user can use it again and again without the need to go back to the identity provider. Of course, there needs to be a limit to this, and that is why tokens have a valid period, and after this period, the user will need to get a new token. My passport was issued to me a couple of years ago, but I can still use it until it expires. Then I will have to go back to city hall and get a new one. Of course, software tokens will not last that long, because it is easy to get a new one over the network.

Understanding Token Serialization

How are tokens serialized over a network? Modern applications using REST use the JSON Web Token (JWT) open standard. This allows us to transmit tokens in a secure way in the form of a JSON object.

The issuer claim (iss) states that this token was issued by my development identity provider with URL https://localhost:5000, and the not before claim (nbf) together with the expiry claim (exp) gives this token a validity period. The audience claim (aud) states that this token is intended for the application called Blazor. Finally, the subject claim (sub) contains a unique identifier for the current user. There are a lot of other official claims you can find in a token, and you can find their meaning on the IANA JSON Web Token Registry’s site at www.iana.org/assignments/jwt/jwt.xhtml.

The payload of the token is not encrypted, so never include sensitive information in here!

The signature allows our software to check if the token has been modified, and again you should ignore this (but not our software!).

Representing Claims in .NET

So how are claims represented in .NET? From the start, Microsoft has provided us with two interfaces to represent the user, IPrincipal and IIdentity.

Understanding OpenId Connect Hybrid Flow

In Blazor Server, we will use the Hybrid flow , so let us review how this flow works as illustrated in Figure 16-2. Figure 16-2 shows the identity provider, our Blazor Server application, and the user using a browser. When we look at Blazor WebAssembly, we will review Authorization Code flow.

When the not yet authenticated user visits a protected resource (Step 1), the Blazor Server will return an HTTP redirect result (Step 2) which will make the browser visit the identity provider, also known as an authorization server (AS). The URL contains credential information about the client (the ClientId and ClientSecret) together with a redirect URI. The identity provider identifies the client application through its ClientId and verifies if the redirect URI matches its list of registered client redirect URIs. The identity provider will then present the user with some kind of login UI (Step 3), for example, to enter the username and password. The identity provider is free how this login process works, and after a successful login, the identity provider will return an HTTP redirect to the browser (Step 4) so the browser will visit the redirect URI (the Blazor Server application) with the request containing a code and identity token. The redirect URI is then processed by the Blazor application, the identity token is turned into a ClaimsPrincipal, and the user has been authenticated. The Blazor application is also responsible for storing the ClaimsPrincipal, and with Blazor Server, this is done by storing the ClaimsPrincipal in a cookie, so the next request containing that cookie can deserialize it again. For the moment, we don’t need the code, but we will use it later.

A couple of remarks: an identity provider will only send tokens to known redirect URIs, so these have to be registered with the identity provider. This prevents unknown parties (hackers!) from hijacking requests. When you deploy your application, you should not forget to register the new redirect URI in the identity provider. There can be several registered redirect URIs, so you can keep developing locally and run the application in production using the same identity provider.

Implementing the Identity Provider with IdentityServer4

Let us start by creating the project that we will use as our identity provider, using IdentityServer4. Create a new AspNet .NET Core Web App project and name it IdentityProvider.

IdentityServer4 can be configured using a database or an in-memory configuration. We will use the latter because it is easier for learning and experimentation. Add a new class called Config to the project next to Program.cs. This Config class will contain the configuration for IdentityServer4.

Adding the Login UI to Our Identity Provider

When our users want to log in to the identity provider, the identity provider will present a login screen to the user. IdentityServer4 comes with a built-in UI, so here we will add this to the IdentityProvider project.

Getting everything installed is pretty easy with dotnet CLI.

This will install two new folders called QuickStart and Views and will also install some CSS and scripts in the wwwroot folder.

Running the application will show the UI similar to Figure 16-3.

Click the second link (see the claims); you will be asked to log in (with one of our users from Listing 16-7), after which it will display the claims just like Figure 16-4.

Adding OpenId Connect to Blazor Server

Add the Microsoft.AspNetCore.Authentication.OpenIdConnect package to the Blazor.Server.OpenIdConnect project.

Implementing Authorization in Blazor Server

Before running the application, we should also protect one of our resources; otherwise, there is no need to authenticate using the identity provider. But first we need to understand how authentication works in Blazor using the AuthenticationState and AuthenticationStateProvider classes . The AuthenticationState class allows access to the current user’s claims with the User property of type ClaimsPrincipal, and the AuthenticationStateProvider abstracts away how we retrieve the current AuthenticationState, because the process is different in Blazor Server and Blazor WebAssembly. So you should always use the AuthenticationStateProvider in your Blazor components if you want these to work in both Blazor Server and Blazor WebAssembly. Listing 16-16 contains a nice example of how you do this.

In Blazor Server, the user’s ClaimsPrincipal is stored in the HttpContext.User property so AuthenticationStateProvider retrieves it there.

Let us walk through the authentication process step by step. First, start the IdentityProvider project; next, start the Blazor.Server.OpenIdConnect project.

On the Browser tab for the localhost:5001 URL, open the browser debugger on the Network tab and navigate to https://localhost:5001 again to get a fresh network log. You should see Figure 16-6. This shows that visiting the Index page (first line) will redirect to the login page (second line), which will then cause the middleware to redirect to the identity provider (third line), which will show its login page (fourth line). Should your browser immediately show the Index component, you need to clear your cookies and try again.

After completing the login process, you will be redirected to the Blazor Server’s signin-oidc URL which will be handled by the OpenId Connect middleware. This middleware will convert the identity token into a ClaimsPrincipal and redirect to the original URI that initiated the login process. The Cookie middleware will serialize the ClaimsPrincipal into a cookie (actually, it might use multiple cookies because of the limited length of cookies). The browser then will process the original URI and convert the cookie into the ClaimsPrincipal and because now the user is authenticated will give access to the Index component.

Select the signin-oidc URL in the browser’s debugger and scroll down. You will see that this will return the code and the identity token as in Figure 16-7.

You can inspect the id token by copying its value, open another browser tab on https://jwt.io, and paste the value as shown in Figure 16-8.

Congratulations. You have just added authentication to your Blazor Server application!

Using AuthorizeView

Run the application, and log in. Then click the Logout link which will take you to the identity server logout page as shown in Figure 16-9.

When this property is set, IdentityServer will add a hyperlink in its logout page as shown in Figure 16-10. Clicking this link will take us back to the Blazor Server site.

Adding and Removing Claims

However, we will not find the address claim in the Index component. Why? Because we need to explicitly map this additional claim using ClaimActions.

Running the application and logging in again (!) will show the address claim.

Enabling Role-Based Security

Currently, we have claims that allow us to identify the user. We have the user’s name and address. But what if we would like to protect certain parts of our application so only certain users can access it? Should we check a long list of user names? No, in this case, we will define a number of roles, assign these roles to some of our users, and only allow access when the user has a specific role. This is known as role-based access control (RBAC).

Run the application, and log in again; the user’s role should be shown.

Run and log in with a user who has the admin role; you should see the Counter link in the navigation bar, and it should appear when you click it. Do the same for a user without the admin role; now there should be no Counter link in the navigation bar, and even manually modifying the browser’s URL to /counter will show a not authorized screen.

Using an Access Token

Access tokens are just ordinary tokens, but they don’t contain information about the user; they contain information about the client application and what the current user can do with the API. Because the API is yet another application, both should use the same identity provider. The client application (Blazor) can then use an OpenId Connect flow to request an access token from the identity provider and use it to access the API. Let us look at this process using the OpenId Connect Hybrid flow as shown in Figure 16-11.

Steps 1–4 are the same as before, and our Blazor Server application receives an identity token and a code (which we ignored until now). This code can then be used together with the Blazor Server application’s identifying information to retrieve an access token (Step 5) from the identity provider. The identity provider will then use the code to verify which claims it should give to the Blazor Server application (Step 6). Once our application has an access token, it can send it along with the API request (Step 7) using a header to the API application, which can then use the claims in the access token to determine how is should behave.

Run the API project. By default, it will open the browser and show the Swagger UI as in Figure 16-12. This will allow you to test the API (which is currently unprotected).

Click the GET button, then click Try It Out, and then Execute. You should see some forecasts.

Registering the API Project with the Identity Provider

Adding JWT Bearer Token Middleware

A client application will send the access token using an HTTP Authorization Bearer header, and we need our API project to look for this header and install the ClaimsPrincipal from the access token. Use NuGet to install the Microsoft.AspNetCore.Authentication.JwtBearer package in the WeatherServices project.

That’s all for the moment for our API.

Enabling the Bearer Token in the Client

Our client application should now use the received code to request an access token from the identity provider and use it in its API requests.

We also need to configure dependency injection in the Blazor Server project to give us an instance of the IHttpClientFactory. The IHttpClientFactory will give us an HttpClient that will be configured for us to include the access token and which will send it as a Bearer token to the API.

Start the IdentityProvider project, next the WeatherServices project, and finally the Blazor.Server.OpenIdConnect project. Log out (if you’re still logged in) and log in again. This will refresh our tokens.

Now we can use the debugger to inspect the ClaimsPrincipal in the WeatherServices project. Put a breakpoint on the GetForecastAsync method and now use the client to fetch the forecasts. The debugger should stop, and now we can use the watch window to inspect the this.User property as in Figure 16-13.

If the results view is empty, you will need to review your code because you forgot something. You should see the scope: u2uApi claim.

Run everything again; you should be able to retrieve the weather forecasts, but when you use the Swagger UI, you will get a 401 Undocumented as in Figure 16-14.

Using Policy-Based Access Control

What if we want to use one or more claims to determine if the user can access a certain resource? For example, we might only want to allow authenticated users that live in Belgium to access the forecasts. In that case, we can use policy-based access control (PBAC).

Running the application and logging in as student@u2u.be will not show the link because this user is from France, while logging in as peter@u2u.be will show the link since the FromBelgium policy passed. This completes the client.

We want to use this policy with the API project as well, so we could copy this code. Let us do the proper thing and move the policy into a library project so we can use the same policy in our Blazor and API projects.

Run all three projects, and log in with the peter@u2u.be user; the Fetch data link should be shown, and when you click the link, you should get a list of forecasts.

Congratulations. You just completed authentication and authorization for Blazor Server applications! Now let us look at Blazor WebAssembly in the next chapter.