Forem: Okta

Pushed Authorization Requests in .NET 9: Why and How to Use Them

Andrea Chiarelli — Wed, 15 Jan 2025 09:30:49 +0000

You may have heard that .NET 9.0 brings Pushed Authorization Requests (PAR) support in ASP.NET Core. If you are wondering what the heck Pushed Authorization Requests are, why you should use this feature, and how to use it in your .NET applications, well, this article is for you.

PAR enhances the security posture of your ASP.NET Core application that uses OpenID Connect and OAuth 2.0. You should care about this security improvement, especially if you build applications for the financial, healthcare, insurance, and other data-sensitive sectors, where it is a requirement.

Before you start, you need some basic knowledge about OpenID Connect and OAuth 2.0. You don’t need to be an expert; just a high-level knowledge of these protocols is enough to understand why and how PAR works.

The Basic OpenID Connect Flow

Let’s start by recalling how a basic OpenID Connect (OIDC) flow works. By basic flow, I mean a flow involving a classic server-rendered web application, i.e., in the context of .NET, a classic ASP.NET Core MVC application, a Razor Pages application, or a Blazor Server application. In the scenario involving this type of application, the flow we use is the Authorization Code flow, which we are going to describe using this diagram:

In the scenario illustrated by the diagram, we have:

A browser, which is the tool used by the user to access our web application.
The web application, called client application in the diagram because it’s a client of the authorization server in the OAuth 2.0 and OIDC context.
The authorization server, which is responsible for authenticating the user and authorizing the application.
The API server, which is the protected server our web application wants to access using an access token.

Following the numbered arrows, we can describe the flow as follows:

The user uses their browser to access the web application. The application finds that the user is not authenticated and builds an authorization request for the browser; then, it redirects the browser with this authorization request to the authorization server for authentication.
The browser sends the authorization request to the authorization endpoint of the authorization server, and the user authenticates. As a result of the authentication, the browser receives an authorization code from the authorization server.
The browser provides the authorization code to the web application.
The web application calls the token endpoint of the authorization server and provides the authorization code. As a response, the authorization server returns an ID and access tokens.
The web application uses the ID token to get information about the user and the access token to call the protected API.

This is a simplified description of the OIDC flow for authenticating the user and authorizing the web application to access the protected API server.

Using OIDC in ASP.NET Core

As you can see from the previous section, there are many moving parts behind the user authentication and application authorization with OIDC. In .NET, you don’t need to take care of all these details. What you usually need to do is to correctly configure the OpenID Connect middleware. In practice, the following code in your Program.cs file works the magic in the basic scenario:

builder.services.AddAuthentication(options =>  
  {  
 options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;  
 options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;  
  })  
 .AddCookie()  
 .AddOpenIdConnect("Auth0", options =>  
  {  
 options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";

 options.ClientId = builder.Configuration["Auth0:ClientId"];  
 options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];  
 options.ResponseType = "code";  
});

The code snippet gets the configuration parameters of the authorization server — Auth0 in the example — from the appsettings.json file, or even better, from environment variables. You don’t need to do anything else to enable your web application to get the ID and access token. Everything happens behind the scenes!

Some Potential Issues

You probably already knew all this, but maybe you never wondered what problems can arise with this well-proven flow. There are two points in the OIDC flow that can have potential security and privacy issues, as highlighted in the following diagram:

The first point is when the web application redirects the browser to the authorization server to authenticate the user. The second point is when the browser calls the authorization endpoint of the authorization server. Both points are related to the authorization request prepared by the web application and sent by the browser to the authorization server.

The main issues that can affect the authorization request are:

The authorization request could be altered. Usually, the web application builds the authorization request on behalf of the browser and then redirects the browser to the authorization server. A malicious actor, such as a browser extension or malware, can modify, add, or remove one or more parameters of this request before sending it to the authorization server.
No guarantee of the request's provenance. As we said, the web application builds the authorization request on behalf of the browser. However, there is no guarantee that an authorization request was built by the web application. Anyone can build it once they know some basic data, such as the client ID and the redirect URI.
No guarantee of confidentiality. Although the browser sends the authorization request to the authorization server via HTTPS, the request parameters can be intercepted by third-party applications, such as proxies, load balancers, or even browser plugins. A malicious network component of this type can inject or change the request parameters, not to mention that the request itself can be logged.
Browser limitations. Finally, a very complex query string in the authorization request may incur possible browser limitations on URL length.

Entering Pushed Authorization Requests (PAR)

While the issues pointed out above may appear as non-crucial issues in ordinary authentication contexts, they become significant in contexts where privacy and data protection are paramount.

Here comes PAR, an extension of OAuth 2.0 (and then of OIDC) that enhances the protocol’s security level to solve those issues and protect the authorization request’s exposure.

We will not dive deep into the details of this extension. Read this article to learn more about how Pushed Authorization Requests work. Anyway, to have a high-level idea, let’s follow this new flow in this diagram:

As usual, the user accesses the web application with their browser.
The web application builds an authorization request, but this time, it sends the request to the authorization server using the new PAR endpoint instead of sending it to the browser. The web application uses the PAR endpoint to register the authorization request and get an identifier for this request (the request URI).
Instead of the typical authorization request, the browser will get a URL with the request identifier as a parameter. No risk of sensitive detail exposure or modification this time; just an identifier saying nothing to a potential attacker.
When the authorization server receives the request with the request URI from the browser, it retrieves the previously registered authorization request and processes it as if the browser sent it.
From now on, the usual flow continues.

PAR guarantees more security and confidentiality when managing authorization requests. It’s part of a set of specifications that fall under the umbrella of FAPI, an OpenID initiative that aims to strengthen the protocols to make them compatible with the more restrictive needs typical of financial, insurance, healthcare, and governmental contexts, among other contexts.

How to Use PAR in .NET 9

Now that we have an idea of what PAR is and how it works let's see how to use it in .NET 9.

To add PAR support to your ASP.NET Core application, your OIDC configuration in Program.cs should look like the following:

builder.services.AddAuthentication(options =>  
  {  
 options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;  
 options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;  
  })  
 .AddCookie()  
 .AddOpenIdConnect("Auth0", options =>  
  {  
 options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";

 options.ClientId = builder.Configuration["Auth0:ClientId"];  
 options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];  
 options.ResponseType = "code";  
});

Can you see the difference with the code shown earlier? No? Can't you see it?

Actually there is no difference! .NET supports PAR by default, with a fallback to the traditional flow in case the authorization server does not support PAR. That’s amazing, don’t you? You get more security with no additional code.

You may say, “If I don’t need to add code, why should I care about PAR and how it works?” Actually, you should be aware of what happens under the hood. When things go wrong, having an idea of what is happening at a lower level can be helpful for debugging and detecting the cause of an issue.

Assume you are used to checking the traditional OIDC flow when a problem with authentication arises. You migrate your application to .NET 9 without any need to change code and everything works fine. One day you have a problem with user authentication and analyze the HTTP traffic to try understanding what’s going on, and you don’t find the classic authorization request. I bet you'll have a hard time figuring out what happened, since you didn't change your code.

If you were already prepared, you wouldn't have been surprised by this new flow.

Controlling PAR Configuration

We said that PAR is supported by default in .NET 9. But what if you don’t want to use it? How can you tell your application to just use the classic OIDC flow? You can do it as follows:

options.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Disable;

The PushedAuthorizationBehavior option allows you to configure PAR behavior. In the previous example, you disable it, forcing your application to fall back to the classic OIDC flow. You can also force your application to use PAR with the following settings:

options.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Require;

In this case, your application will use the PAR flow. If the authorization server does not support PAR, your application will not fall back to the classic OIDC flow but will throw an exception.

Finally, you can handle a new event, onPushAuthorization, to customize the authorization request before it is sent to the authorization server. The following example shows how you can create a handler for this event:

options.Events = new OpenIdConnectEvents  
{  
  OnPushAuthorization = async ctx =>  
  {  
    ...
  }  
};

Summary

We started by analyzing the basic OIDC flow and discovered a few possible security and privacy issues with authorization requests. Then, we introduced PAR and learned how it works. We also learned that .NET 9 introduces PAR support for ASP.NET Core applications by default without requiring us to write code. However, we can configure and customize PAR behavior programmatically by using a couple of options.

I hope you now have a clearer understanding of what PAR is, why using it, and how to use it in ASP.NET Core starting with .NET 9.0.

Add Step-up Authentication Using Angular and NestJS

Alisa — Thu, 28 Mar 2024 15:25:16 +0000

The applications you work on expect good authentication as a secure foundation. In the past, we treated authentication as binary. You are either authenticated or not. You had to set the same authentication mechanism for access to your application without a standard way to change authentication mechanisms conditionally. Consider the case where sensitive actions warrant verification, such as making a large financial transaction or modifying top-secret data. Those actions require extra scrutiny!

Use Step Up Authentication Challenge to protect resources

Enter the OAuth 2.0 Step Up Authentication Challenge Protocol. This standard, built upon OAuth 2.0, outlines a method to elevate authentication requirements within your application. The standard defines methods to identify authentication rules, including authentication mechanisms and authentication recency. We'll cover more details about this much-needed standard as we go along. If you want to read more about it before jumping into the hands-on coding project, check out Step-up Authentication in Modern Applications.

In this post, you'll add step-up authentication challenge standard to an Angular frontend and NestJS backend. If you want to jump to the completed project, you can find it in the completed branch of okta-angular-nestjs-stepup-auth-example GitHub repository. Warm up your computer; here we go!

Note

This post is best for developers familiar with web development basics and Angular. If you are an Angular newbie, start by building your first Angular app using the tutorial created by the Angular team.

Prerequisites

For this tutorial, you need the following tools:

Node.js v18 or greater
A web browser with good debugging capabilities
Your favorite IDE. Still searching? I like VS Code and WebStorm because they have integrated terminal windows.
Terminal window (if you aren't using an IDE with a built-in terminal)
Git and an optional GitHub account if you want to track your changes using a source control manager

Table of Contents

Use Step Up Authentication Challenge to protect resources
Prepare the Angular and NestJS web application
Set up the Identity Provider to use OAuth 2.0 and OpenID Connect
Step-up authentication mechanics at a glance
Set up authenticators
Guard a route with step-up authentication
Protect API resources with step-up authentication challenge
- Check the access token’s ACR claim in a NestJS middleware
- Use an Angular interceptor to catch step-up HTTP error responses
- Handle step-up errors when making HTTP calls in Angular
Ensure authentication recency in step-up authentication
Step-up authentication in Angular and NestJS applications

Prepare the Angular and NestJS web application

You'll start by getting a local copy of the project. I opted to use a starter project instead of building it out within the tutorial because many steps and command line operations detract from the coolness of adding step-up authentication. Open a terminal window and run the following commands to get a local copy of the project in a directory called okta-stepup-auth-project and install dependencies. Feel free to fork the repo so you can track your changes.

git clone https://github.com/oktadev/okta-angular-nestjs-stepup-auth-example.git okta-stepup-auth-project
cd okta-stepup-auth-project
npm ci

oktadev / okta-angular-nestjs-stepup-auth-example

Example project demonstrating step-up auth implementation in Angular and NestJS

Add Step-up Authentication Using Angular and NestJS Example

This repository contains a working example of adding step-up authentication to protect an Angular route using the Okta Angular SDK. It also contains example code of protecting an API route in NestJS and Angular code required to handle step-up authentication challenge error response. Please read Add Step-up Authentication Using Angular and NestJS for a detailed guide through.

Prerequisites

Node 18 or greater
Okta CLI
Your favorite IDE
A web browser with good debugging capabilities
Terminal window
Git

Okta has Authentication and User Management APIs that reduce development time with instant-on, scalable user infrastructure. Okta's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

Getting Started

To run this example, run the following commands:

git clone https://github.com/oktadev/okta-angular-nestjs-stepup-auth-example.git stepup-auth
cd stepup-auth
npm ci

Create an OIDC Application

…

View on GitHub

Open the project up in your favorite IDE. Let's take a quick look at the project organization. The project has an Angular frontend and NestJS API backend housed in a Lerna monorepo. If you are curious about how to recreate the project, check out the repo's README file. I'll include all the npx commands, CLI commands, and the manual steps used to create the project.

You need to set up an authentication configuration to serve the project. Let's do so now.

Set up the Identity Provider to use OAuth 2.0 and OpenID Connect

You'll use Okta to handle authentication and authorization in this project securely.

Before you begin, you’ll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login. Then, run okta apps create. Select the default app name, or change it as you see fit. Choose Single-Page App and press Enter.

Use http://localhost:4200/login/callback for the Redirect URI and set the Logout Redirect URI to http://localhost:4200.

What does the Okta CLI do?
The Okta CLI will create an OIDC Single-Page App in your Okta Org. It will add the redirect URIs you specified and grant access to the Everyone group. It will also add a trusted origin for http://localhost:4200. You will see output like the following when it’s finished:

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create an Angular App for more information.

Note the Issuer and the Client ID. You'll need those values for your authentication configuration, which is coming soon.

There's one manual change to make in the Okta Admin Console. Add the Refresh Token grant type to your Okta Application. Open a browser tab to sign in to your Okta developer account. Navigate to Applications > Applications and find the Okta Application you created. Select the name to edit the application. Find the General Settings section and press the Edit button to add a Grant type. Activate the Refresh Token checkbox and press Save.

I already added Okta Angular and Okta Auth JS libraries to connect our Angular application with Okta authentication. On the API side, I added the Okta JWT Verifier library that you'll use for access token verification later in the post.

In your IDE, open packages/frontend-angular/src/app/app.config.ts and find the OktaAuthModule.forRoot() configuration. Replace {yourOktaDomain} and {yourClientId} with the values from the Okta CLI.

Start the app by running:

npm start

The command starts both the frontend app and the API. Navigate to localhost:4200 in your browser. What a beautiful app!

Sign in and notice the "profile" route shows your profile information with a warm, friendly greeting using your name, and the "messages" route displays messages from an HTTP call the component makes to your API. Sign out of the application.

We now have a web app with basic authentication capabilities. Let's kick up authentication levels by adding step-up authentication!

Step-up authentication mechanics at a glance

Before we jump into Step Up Authentication, let's take a step back and cover how authentication works in an application. In most circumstances, you'd require authentication before allowing the user to navigate anywhere within the app. You can prevent them from entering a URL:

The Step Up Authentication Challenge idea builds upon the foundation of OAuth 2.0 and OpenID Connect (OIDC). Your app enforces authentication assurances from the user for different actions. Authentication and identity assurance determine the certainty that the user is who they say they are. The specification supports defining authentication strength and recency and responds with a standard error insufficient_user_authentication. Let's say the authenticated user now wants to make a new transaction. Creating a new transaction is a sensitive action and requires elevated authentication assurances:

Your app needs to verify you have the correct authentication assurances for your requested action. Your frontend app's OIDC library evaluates your ID token for authenticated state and the value of a specific claim called Authentication Context Class Reference (ACR). The acr claim value contains the client's authentication assurance level. If the ACR claim value doesn't meet the required assurance profile, the client requests the correct level using the acr_values parameter when communicating with Okta. Let's take another look at the previous diagram, this time incorporating acr and acr_values properties:

ACR values can be a standard or use a custom registry. You'll see values such as phr for phishing-resistant factors, which include FIDO2 + WebAuthn authenticators. You'll also see custom values such as one Okta supports for two-factor authentication, such as urn:okta:loa:2fa:any. Read more about supported ACR values in Okta's Step Up Authentication documentation.

This is a high-level overview of OAuth 2.0, OpenID Connect, and the Step Up Authentication Challenge spec, and it only covers what we need to know for this tutorial. I'll add links to resources at the end of this post so you can dive deeper into this topic.

It's clearer to see authentication strengths rather than calculate the recency of authentication, so we'll walk through the steps required for authentication strengths in the tutorial. Right now, you only have password authentication. You'll need another authenticator for your app!

Set up authenticators

You'll change the Okta Admin Console to support a different authentication mechanism. We'll change the email authenticator so it's both a recovery and an authentication factor. Sign in to your Okta Developer Edition Account.

Navigate to Security > Authenticators. Find Email, press on the Actions menu, and select Edit. Select the Authentication and recovery radio button under the Used for section.

Your Okta application should allow you to authenticate with a password or email. Sign out of the Okta Admin Console so we can see the entire step-up authentication flow from end-to-end.

Note

You must use the email OTP verification number when authenticating using email. This post doesn't include the steps required to set up email magic link handling. Let me know in the comments below if you want to see a post about this.

Guard a route with step-up authentication

Back to coding! The Okta Angular SDK supports step-up authentication and has a built-in feature so that you can define the required acr_values for routes right in your route definition. We'll require two-factor authentication for your profile. In your IDE, open packages/frontend-angular/src/app/app.routes.ts and find the route for "profile." Add route data to route using the okta object and a property named acrValues. The property's value is urn:okta:loa:2fa:any. Your "profile" route definition should look like this:

{ 
  path: 'profile',
  component: ProfileComponent,
  canActivate: [OktaAuthGuard], 
  data: {
    okta: { acrValues: 'urn:okta:loa:2fa:any' }
  }
}

Test this route out. Start the application by running npm start if it isn't still running. Open the application in the browser, and feel free to open network debugging capabilities so you can see the acr_values request. Sign in using one factor, such as a password. Then, navigate to the "profile" route. You'll be redirected to Okta to authenticate using your email. Sign in with your email by entering a verification number. Success!

Sign out of the application.

The Okta Angular SDK helps us out, so we don't have to write custom code. Under the covers, the SDK has an Angular guard that:

Gets the acr claim value from the ID token
If the value matches the acrValues route data definition, it returns true to allow navigation
Otherwise, it redirects the user to authenticate using the value in the acrValues, saves the current route, and returns false to prevent navigation

The code would look something like this:

const stepupGuard: CanActivateFn = async (route, state, oktaAuth = inject(OKTA_AUTH)) => {
  const acrValues = route.data['okta']?.['acrValues'];
  const acrClaim = return decodeToken(oktaAuth.getIdToken()).payload.acr;
  if (acrClaim === acrValues) return true;
  oktaAuth.setOriginalUri(state.url);
  await oktaAuth.signInWithRedirect({acrValues})
  return false;
};

This helps protect application routes, but what else can we do?

Protect API resources with step-up authentication challenge

You can also protect resources by adding step-up authentication handling to the resource server or the API serving resources to your app. You may have API endpoints that require elevated authentication assurances. Also, consider a user making a large financial transaction where some transaction threshold warrants extra scrutiny. Checking the transaction amount requires inspecting the payload before triggering step-up authentication. Both scenarios work with the step-up authentication challenge protocol.

You may wonder why checking the acr claim in your API is necessary when you have already done so in the web app. Good web application security practices must enforce authentication, identity, and access control in the SPA client and APIs. Someone can bypass the SPA and make direct API calls – always guard all entries into your application system.

The flow works like this:

If the acr claim value doesn't meet the requirements, the API responds with a standard error:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="A different authentication level is required",
  acr_values="elevated"

We'll use this error structure in the API response in NestJS, and when handling the step-up authentication error in the Angular app.

Check the access token's ACR claim in a NestJS middleware

You'll make changes to the API first. I added Okta's jwt-verifier library to do the heavy lifting on verifying the access token and decoding the payload to get the acr claim.

The project contains an empty step-up authentication middleware. Open packages/api/src/stepup.middleware.ts.

In this file, you will:

Initialize the JWT Verifier instance
Ensure the Authorization header contains the access token
Verify the token
Get the acr claim value and compare it to the required value
Respond with the resource or return 401 HTTP response with the standard header

Let's start by initializing the Okta JWT Verifier instance and changing the use() method to async. Add the following code and replace {yourOktaDomain} with the Okta domain you got from the Okta CLI in a previous step.

import { HttpStatus, Injectable, NestMiddleware } from '@nestjs/common';
import OktaJwtVerifier from '@okta/jwt-verifier';

@Injectable()
export class StepupMiddleware implements NestMiddleware {
  private jwtVerifier = new OktaJwtVerifier({issuer: 'https://{yourOktaDomain}.okta.com/oauth2/default'});

  async use (req: any, res: any, next: () => void) {
    next();
  }
}

Next, you can use the jwtVerifier instance to verify the access token... if there is one. 🙀

No need to be dramatic; we can check. Update the use() method to get the access token from the Authorization header. Verifying the token using the JWT Verifier library returns the decoded token, so let's save the output in a variable. Update your code to look like this:

async use (req: any, res: any, next: () => void) {
  const authHeader = req.headers.authorization || '';
  const match:string[]|undefined = authHeader.match(/Bearer (.+)/);

  if (!match && match.length >=1 && match[1]) {
    return res.status(HttpStatus.UNAUTHORIZED).send();
  }

  let accessToken:OktaJwtVerifier.Jwt;
  try {
    accessToken = await this.jwtVerifier.verifyAccessToken(match[1], 'api://default');
  } catch (err) { 
    console.error(err)
    return res.status(HttpStatus.UNAUTHORIZED).send(err.message);
  }

  // add the ACR check

  next();
}

Now we can get to the step-up authentication specific code where you'll check the acr claim and return the standard error. In this example, you'll hardcode the required ACR value in this middleware, but you can define different ACR values per route. After the comment to "add the ACR check" but before the next(); method call, add the following code:

const acr_values = 'urn:okta:loa:2fa:any';
const acr = accessToken.claims['acr'] ?? '';

if (acr === '' || acr !== acr_values) {
  res.setHeader('WWW-Authenticate', `Bearer error="insufficient_user_authentication",error_description="A different authentication level is required",acr_values="${acr_values}"`)
  return res.status(HttpStatus.UNAUTHORIZED).send();
}

With the middleware implemented, you need to register it in the module. Open packages/api/src/app.module.ts. Edit the AppModule to add the StepupMiddleware to the "messages" route as shown:

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(StepupMiddleware).forRoutes('messages');
  }
}

💡 Idea 💡

We hardcoded the required acr_values in the middleware and applied the middleware to all calls to the "messages" route for this demonstration, but NestJS does provide better mechanisms for scaling to larger projects and defining granular assurance requirements. One option might be to create a NestJS guard to define which HTTP methods of an endpoint require step-up authentication. Furthermore, you can create a custom decorator for step-up authentication and pass in the required acr_values for the HTTP method. That way, a generic guard scales across your API, and you can define a GET call that requires two-factor authentication and a POST call requires phishing-resistant authentication assurance, for example.

Let me know in the comments below if you want to see a tutorial about this! 📝

The resource server now handles step-up authentication for the "messages" route. It returns the standard error when user authentication is insufficient, but the Angular frontend needs to respond to this error.

Use an Angular interceptor to catch step-up HTTP error responses

In Angular, we'll first identify the step-up authentication error response, then manipulate the HTTP error response by extracting the information needed for further handling. It starts in an interceptor.

Open packages/frontend-angular/src/app/stepup.interceptor.ts, an unmodified interceptor file scaffolded by Angular CLI.

import { HttpInterceptorFn } from '@angular/common/http';

export const stepupInterceptor: HttpInterceptorFn = (req, next) => {
  return next(req);
};

Intercepting and handling HTTP error responses means we'll catch the error and provide an error handler function. Change your code as shown:

import { HttpErrorResponse, HttpInterceptorFn } from '@angular/common/http';
import { catchError, throwError } from 'rxjs';

const handleError = (httpError: HttpErrorResponse) => {
  return throwError(() => httpError);
};

export const stepupInterceptor: HttpInterceptorFn = (req, next) => {
  return next(req).pipe(catchError(handleError));
};

The error handler needs first to verify this is an error we want to handle. Is this HTTP error a step-up error from our resource server? We can check for this! In the handleError method, add the following code and change the return value:

const handleError = (httpError: HttpErrorResponse) => {
  const allowedOrigins = ['/api'];
  if (httpError.status !== HttpStatusCode.Unauthorized || !allowedOrigins.find(origin => httpError.url?.includes(origin))) {
    return throwError(() => httpError);
  }

  let returnError: HttpErrorResponse| {error: string, acr_values: string} = httpError;
  const authResponse = httpError.headers.get('WWW-Authenticate') ?? '';
  if (!authResponse) {
    return throwError(() => returnError);
  }

  // add code to extract error details and format new error type

  return throwError(() => returnError)
};

Now we're at the stage where we know this is most likely an error we should handle, and we'll know for sure by extracting the insuffcient_user_authentication string from the WWW-Authenticate header. While parsing the header string, we'll look for the acr_values. Add the code to support this by replacing the // add code to extract error details and format new error type with:

const {error, acr_values} = Object.fromEntries((authResponse.replace('Bearer ', '').split(',') ?? []).map(el => el.replaceAll('"', '').split('=')));

if (error === 'insufficient_user_authentication') {
  returnError = {error, acr_values};
}

Lastly, add the interceptor to the ApplicationConfig. Open packages/frontend-angular/src/app/app.config.ts. Add the stepupInterceptor to the providers array.

provideHttpClient(withInterceptors([
  authInterceptor,
  stepupInterceptor
])

You can't redirect the user to authentication from an interceptor. You need to handle this new error format elsewhere, where you initiate redirecting the user to authentication with the required acr_values before re-requesting the resource.

Handle step-up errors when making HTTP calls in Angular

You can handle catching the error, redirecting the user to authenticate, and re-request the resource within the call to the API, usually within an Angular service. I cheated a bit and wrote the API call directly in the component in this demonstration. Open packages/frontend-angular/src/app/messages/messages.component.ts.

You need the Angular Router and OKTA_AUTH instances so you can save the existing URL then redirect the user to authenticate. Create properties and inject both types within the class.

  private oktaAuth = inject(OKTA_AUTH);
  private router = inject(Router);

Change messages$ to add a catchError operator. Within the catchError function, you'll ensure the error type is insufficient_user_authentication, set the redirect URI to navigate the user back to this component which will re-request the resource, and finally redirect the user to authenticate using the acr_values:

public messages$ = this.http.get<Message[]>('/api/messages').pipe(
    map(res => res || []),
    catchError(error => {
      if (error['error'] === 'insufficient_user_authentication') {
        const acrValues = error['acr_values'];
        const redirectTo = this.router.routerState.snapshot.url;

        this.oktaAuth.setOriginalUri(redirectTo);
        this.oktaAuth.signInWithRedirect({acrValues});
      }
      return throwError(() => error);
    })
  );

This code sure looks similar to the operations in the step-up auth Angular guard!

Try out your work. Ensure you sign out of the application first. Sign in with one factor, then navigate to the "messages" route. You'll redirect to sign in with a second factor. Success!

Ensure authentication recency in step-up authentication

We covered the authentication levels in this post because they are visually visible within the Okta-hosted sign-in page. The step-up authentication challenge protocol also supports authentication recency. The good news is the code and process we covered in the post still apply, but you'll use different claims and properties. In the redirect request, you'll define the required business rules for authentication recency using the max_age property instead of acr_values. Calculate authentication recency using the auth_time claim when evaluating whether a token meets the max_age requirement. Cool stuff indeed!

Step-up authentication in Angular and NestJS applications

In this post, you walked through adding a step-up authentication challenge to protect resources. You added step-up authentication to protect Angular routes using the Okta Angular SDK, then added step-up authentication to protect resources from the NestJS API and within the Angular app.

There's a lot more we can do, and in a demo, we can't get into all the production-level polish we'd like, but I hope this sparks your imagination about how you can protect resources within your application. You can check out the completed application in the completed branch of the okta-angular-nestjs-stepup-auth-example GitHub repository. The repository's README also includes instructions on scaffolding the starting project.

Ready to read other interesting posts? Check out the following links.

Don't forget to follow us on Twitter and subscribe to our YouTube channel for more exciting content. We also want to hear about the tutorials you want to see. Leave us a comment below!

Flexible Authentication Configurations in Angular Applications Using Okta

Alisa — Tue, 12 Mar 2024 16:17:17 +0000

Are you ready to hear about the ultimate flexibility in configuring authentication properties in the Okta Angular SDK? You'll want to check out this excellent new feature and walk through the steps of adding authentication using Okta to Angular applications.

Configuring authentication properties using Okta in Angular applications

There are three main ways you can add configuration information to Angular applications:

Define the value within the app - The easiest, most straightforward route is directly defining the configuration within the AppModule or app.config.ts. Sure, it's direct, but it can be limiting since the value can always stay the same.
Add it into env files - You can take the configuration definitions out of the application and pull the values during build time. But this means you'll need to build separate applications for each environment requiring unique configs.
Populate configuration at runtime - In this pattern, you'd retrieve the configuration in an HTTP call from an API when the app starts and populate the configuration values upon receiving the HTTP response. Runtime configuration means you can change the config values without building and redeploying the Angular application! It's the ultimate flexibility and the awesome new feature I hinted at in the Okta Angular SDK!

💡 You can read more about these three ways, along with examples, in Three Ways to Configure Modules in Your Angular App.

The best way to experiment with loading authentication configuration at runtime is to try it out yourself. Pull out your machine and warm up your fingers! If you want to jump to the completed project, you can find it in the okta-angular-standalone-config-example GitHub repository.

Otherwise, let's get coding!

Note

This post is best for developers familiar with Angular. If you are an Angular newbie, start by building your first Angular app using the tutorial created by the Angular team.

Prerequisites

For this tutorial, you will need the following tools:

Node.js v18 or greater
Angular CLI
A web browser with good debugging capabilities
Your favorite IDE. Still on the hunt? I like VS Code and WebStorm because they have integrated terminal windows.
Terminal window (if you aren't using an IDE with a built-in terminal)

Table of Contents

Configuring authentication properties using Okta in Angular applications
Scaffold an Angular standalone application
Create an Okta OAuth 2.0 and OpenID Connect SPA client
Use the Okta Angular SDK for authentication
Display OpenID Connect claims
Intercept HTTP requests to add the Authorization header with a functional interceptor
Add runtime authentication configuration to an Okta Angular app
Use OAuth 2.0, OpenID Connect, and the Okta Angular SDK for secure authentication

Scaffold an Angular standalone application

Angular introduced standalone components as a developer preview in v14. Since then, the Angular team continued building support for the architecture. It's now the default when using the Angular CLI in v17, so we'll use standalone components, functional interceptors, and control flow in this sample.

In the terminal, run the following commands to generate the app and add the components:

npx @angular/cli@17 new okta-angular-example --routing --style scss --defaults
cd okta-angular-example
ng generate component profile --inline-template --inline-style
ng generate component protected --inline-template --inline-style

Open the okta-angular-example project in your IDE. You'll first define all the routes for the project. Open the protected folder and add routes.ts. We will treat this component as an entrance to a lazy-loaded route. Add the following code to the routes.ts:

import { Route } from '@angular/router';
import { ProtectedComponent } from './protected.component';

export const PROTECTED_FEATURE_ROUTES: Route[] = [
    { path: '', component: ProtectedComponent }
];

Open app.routes.ts. Add the following routes:

import { Routes } from '@angular/router';
import { ProfileComponent } from './profile/profile.component';

export const routes: Routes = [
  { path: 'profile', component: ProfileComponent },
  { path: 'protected', loadChildren: () => import('./protected/routes').then(m => m.PROTECTED_FEATURE_ROUTES)},
];

There's more to do here, but we'll add it after you add Okta to the project.

Create an Okta OAuth 2.0 and OpenID Connect SPA client

You'll use Okta to securely handle authentication and authorization for your Angular application.

Use http://localhost:4200/login/callback for the Redirect URI and set the Logout Redirect URI to http://localhost:4200.

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create an Angular App for more information.

Note the Issuer and the Client ID. You'll need those values for your authentication configuration coming up soon.

There's one manual change to make in the Okta Admin Console. Add the Refresh Token grant type to your Okta Application. Open a browser tab to sign in to your Okta developer account. Navigate to Applications > Applications and find the Okta Application you created. For Okta Applications using the default name, find the Application named "My SPA." Otherwise find the Application with your custom name. Select the name to edit the application. Find General Settings section and press the Edit button to add a Grant type. Activate the Refresh Token checkbox and press Save.

We'll use the Okta Angular and Okta Auth JS libraries to connect our Angular application with Okta authentication. Add them to your project by running the following command:

npm install @okta/okta-angular@6.3 @okta/okta-auth-js@7.5

Use the Okta Angular SDK for authentication

You'll start by directly adding the Okta configuration to the application, which is the first and most straightforward method of adding configuration to Angular applications. Open app.config.ts, and make the following modifications to import the OktaAuthModule and define the configuration:

import { OktaAuthModule } from '@okta/okta-angular';
import { OktaAuth } from '@okta/okta-auth-js';

export const appConfig: ApplicationConfig = {
  providers: [
    importProvidersFrom(
      OktaAuthModule.forRoot({
        oktaAuth: new OktaAuth({
          issuer: 'https://{yourOktaDomain}/oauth2/default',
          clientId: '{yourClientId}',
          redirectUri: `${window.location.origin}/login/callback`,
          scopes: ['openid', 'offline_access', 'profile']
        })
      })
    ),
    provideRouter(routes)
  ]
};

Don't forget to replace {yourOktaDomain} and {yourClientId} with the values you got from the Okta CLI!

With Okta added to the project, let's return to the route definitions. You can define the sign-in redirect route and add guards to those routes. Open app.routes.ts and make the changes so that your route definitions look like this:

import { Routes } from '@angular/router';
import { OktaAuthGuard, OktaCallbackComponent } from '@okta/okta-angular';
import { ProfileComponent } from './profile/profile.component';

export const routes: Routes = [
  { path: 'profile', component: ProfileComponent, canActivate: [OktaAuthGuard] },
  { path: 'protected', loadChildren: () => import('./protected/routes').then(m => m.PROTECTED_FEATURE_ROUTES), canActivate: [OktaAuthGuard] },
  { path: 'login/callback', component: OktaCallbackComponent }
];

You'll add the code for the components using the Okta SDK to sign in, sign out, and display user claims. We'll keep the components and their styles minimal so we can focus on the authentication pieces.

Open app.component.html. Copy the following code into the file.

<div class="toolbar">
  @if (isAuthenticated$ | async) {
  <div>
    <nav class="routes">
      <a routerLink="/">Home</a>
      <a routerLink="/profile">Profile</a>
      <a routerLink="/protected">Protected</a>
    </nav>
  </div>
  <a class="auth" (click)="signOut()">Sign out</a>
  } @else {
  <a class="auth" (click)="signIn()">Sign in</a>
  }
</div>

<p>Learn more about Okta at <a href="https://developer.okta.com">developer.okta.com</a></p>

<router-outlet></router-outlet>

In the app.component.scss, copy the following code and paste it into the file. No frills here! We are keeping this focused on function, not form. 😅

:host {
  font-family: sans-serif;
}

a,
a:visited,
a:hover {
  color: #095661;
}

.toolbar {
  display: flex;
  justify-content: flex-end;
  align-items: baseline;
}

.routes,
.routes > a + a {
  margin-left: 1rem;
}

.auth {
  border: 1px solid #999;
  border-radius: 4px;
  padding: 4px 8px;

  &:hover {
  background-color: #2d8c9e;
  color: #fff;
  }
}

p {
  margin: 6rem;
  text-align: center;
  font-size: large;
}

Finally, we can get to the interesting authentication components. Open app.component.ts. Since this is a standalone component, you must import the classes it relies on, AsyncPipe, RouterOutlet, and RouterLink.

You'll use two classes and libraries from Okta, so inject the OktaAuthStateService and OKTA_AUTH injection tokens. The OktaAuthStateService.authState$ observable stream emits an authenticated state. You can use this to watch for whether you show the sign-in or sign-out buttons and add the functionality to sign in and sign out using Okta:

import { AsyncPipe } from '@angular/common';
import { Component, inject } from '@angular/core';
import { RouterLink, RouterOutlet } from '@angular/router';
import { OktaAuthStateService, OKTA_AUTH } from '@okta/okta-angular';
import { AuthState } from '@okta/okta-auth-js';
import { filter, map } from 'rxjs';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AsyncPipe, RouterOutlet, RouterLink],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  private oktaStateService = inject(OktaAuthStateService);
  private oktaAuth = inject(OKTA_AUTH);

  public isAuthenticated$ = this.oktaStateService.authState$.pipe(
    filter((s: AuthState) => !!s),
    map((s: AuthState) => s.isAuthenticated ?? false)
  );

  public async signIn(): Promise<void> {
    await this.oktaAuth.signInWithRedirect();
  }

  public async signOut(): Promise<void> {
    await this.oktaAuth.signOut();
  }
}

This code gets you authenticated using Okta. Feel free to start the application and verify you can sign in and out. Serve the application by running the following command in your terminal:

npm start

Note

If you have app initialization errors, double-check your Okta configuration and replace the placeholders.

You should see something like this when you start the application:

The links for the profile and protected routes display after you sign in.

I made no claims about building a beautiful app.

The profile and protected routes display the default text from Angular CLI. It's time to add something a little more interesting!

Display OpenID Connect claims

The profile should display something about the profile! So, let's add the code to read one of your standard ID claims and display a warm, friendly greeting to the signed-in user. Open profile.component.ts. This component uses an inline template and styles.

You'll add the AsyncPipe to the imports array and the following template code, replacing the existing template:

<p>You're logged in!
  @if(name$ | async; as name) {
    <span>Welcome, {{name}} </span>
  }
</p>

Time to pretty up the template. Check out the styles, and add this stylistic marvel into the component declaration for the inline styles. Feel free to add some extra flair if you'd like and make this project your own. 🎉

p {
  text-align: center;
}

To display the claim value, you'll use the OktaAuthStateService, which holds your ID token and already decodes the payload for you. That's pretty handy! You'll pipe the authState$ observable stream to filter out unauthenticated state and then use the name claim property. Your component code will look like this:

export class ProfileComponent {
  private oktaAuthStateService = inject(OktaAuthStateService);
  public name$ = this.oktaAuthStateService.authState$.pipe(
    filter((authState: AuthState) => !!authState && !!authState.isAuthenticated),
    map((authState: AuthState) => authState.idToken?.claims.name ?? '')
  );
}

When you sign in and navigate to the profile route, you'll see something like this.

With this, you should now have a working app that allows you to sign in, navigate to protected to see there's nothing there, navigate to profile and feel welcomed, and lastly sign out. Most applications with authentication need an interceptor to add the Authorization header. Even though we aren't calling an API, let's put it in to walk through the steps.

Intercept HTTP requests to add the Authorization header with a functional interceptor

Interceptors manipulate outgoing and incoming HTTP requests, and it's a fantastic way to automatically add the Authorization header along with the access token to outgoing calls!

In a new terminal, use Angular CLI to scaffold an interceptor using the following command:

ng generate interceptor auth

Open the auth.interceptor.ts file to make the required changes. You'll see Angular CLI created the interceptor function. The Authorization header contains highly sensitive information, the access token!

⚠️	Heads up! The access token grants the caller permission to access resources, perform actions, and potentially make devastating changes in the name of the user to whom the access token belongs. You don't want the token to fall into the wrong hands!

In other words, we must protect the token by sending the token to allowed origins. Change the interceptor code to look like this:

import { HttpInterceptorFn } from '@angular/common/http';
import { inject } from '@angular/core';
import { OKTA_AUTH } from '@okta/okta-angular';

export const authInterceptor: HttpInterceptorFn = (req, next, oktaAuth = inject(OKTA_AUTH)) => {
  let request = req;
  const allowedOrigins = ['/api'];
  const accessToken = oktaAuth.getAccessToken();
  if(accessToken && !!allowedOrigins.find(origin => req.url.includes(origin))) {
    request = req.clone({ setHeaders: { 'Authorization': `Bearer ${accessToken}` } });
  }

  return next(request);
};

You've completed the interceptor code, but you have to register the interceptor in the application and bring in the HTTP libraries. Open app.config.ts and add the following code to the providers array after the provideRouter(routes) line:

provideHttpClient(withInterceptors([
  authInterceptor
]))

When you make HTTP calls to allowed origins, you'll now see the access token in the header. Feel free to try this out on your own by calling an API such as this sample Express API from Okta, which verifies the access token, too.

We've done a lot, but the application still contains the hard-coded Okta configuration. What if you want to load the configuration at runtime from an external source? We can emulate this process!

Add runtime authentication configuration to an Okta Angular app

Stop the application by typing ctrl+c in the command line. You'll change the angular.json file, which requires a restart of the application.

Emulate the response from calling an external API by creating a folder called api inside the existing src folder. Then, create a file called config.json within the api folder. Your project file structure will look like this:

okta-angular-example
├── src
│   ├── api
│   │   └── config.json
│   ├── app
│   │   └── all the components
│   └── assets, remaining files
└── remaining files

Open config.json and add the following JSON properties. We'll use this format for the configuration response you get from calling an external API:

{
    "issuer": "https://{yourOktaDomain}.okta.com/oauth2/default",
    "clientId": "{yourClientId}"
}

Hey! Those properties and variables look familiar, right? Replace the variables to match what you got from the Okta CLI and what you have in the app.config.ts file.

The Angular project doesn't recognize this API path and config file, so if you try serving the application right now, the ng serve process won't serve the config.json file with the app. We must also configure the serve process to include the api folder. Open angular.json and find the projects.okta-angular-example.architect.build section. Add src/api to the list of assets in the build option:

{
  "assets": [
    "src/favicon.ico",
    "src/assets",
    "src/api"
  ]
}

You can now access the config.json file at runtime. Feel free to start the application again using npm start in the terminal. In the browser, navigate to http://localhost:4200/api/config.json. This route is accessible by your application, and we'll mimic an HTTP call to read the configuration at runtime.

Open app.config.ts. Add a function before the export const appConfig to call the config endpoint for the configuration as shown:

function configInitializer(httpBackend: HttpBackend, configService: OktaAuthConfigService): () => void {
  return () =>
  new HttpClient(httpBackend)
  .get('api/config.json')
  .pipe(
    tap((authConfig: any) => configService.setConfig({
      oktaAuth: new OktaAuth({
        ...authConfig,
        redirectUri: `${window.location.origin}/login/callback`,
        scopes: ['openid', 'offline_access', 'profile']
      })
    })),
    take(1)
  );
}

Let's talk through the code. The function takes two parameters - the HttpBackend class and the OktaAuthConfigService classes. You first create a new HttpClient. Notice we're not using the HttpClient we can get from Angular dependency injection. We want our auth interceptor to skip this HTTP call. Once you get the config.json response, you set the OktaAuthConfigService with those properties.

Next, you can change the ApplicationConfig, by removing the configuration from the OktaAuthModule by deleting the .forRoot method call. You also need this function to run when the application starts. The APP_INITIALIZER injection token exists precisely for this need. Provide the APP_INITIALIZER injection token with the configInitializer function and the necessary dependencies, and add it to the providers array. The appConfig now looks like this:

export const appConfig: ApplicationConfig = {
  providers: [
    importProvidersFrom(
      OktaAuthModule
    ),
    provideRouter(routes),
    provideHttpClient(withInterceptors([
      authInterceptor
    ])),
    { provide: APP_INITIALIZER, useFactory: configInitializer, deps: [HttpBackend, OktaAuthConfigService], multi: true },
  ]
};

Check it out to verify you can sign in, greet yourself at the profile route, and sign out. Success!

What if you use NgModules architecture?

While this sample demonstrates how to add runtime configuration loading in a standalone application, you can use the same steps in an Angular application with NgModule architecture. Instead, you'll provide the APP_INITIALIZER in the AppModule providers array.

Use OAuth 2.0, OpenID Connect, and the Okta Angular SDK for secure authentication

In this post, you added runtime Okta configuration in an Angular app using standalone components. Whew! That was a lot of work, but I hope you found it fun and exciting. You can check out the completed application in the okta-angular-standalone-runtime-config-example GitHub repository.

oktadev / okta-angular-standalone-runtime-config-example

Use Okta Angular SDK for runtime configuration loading in standalone Angular applications

Angular Standalone Runtime Configuration Example

This repository contains a working example of adding Okta Angular SDK to a standalone Angular project and how to load the Okta authentication configuration at runtime. Please read Flexible Authentication Configurations in Angular Applications Using Okta for a detailed guide through.

Prerequisites

Node 18 or greater
Okta CLI
Angular CLI
Your favorite IDE
A web browser with good debugging capabilities
Terminal window

Okta has Authentication and User Management APIs that reduce development time with instant-on, scalable user infrastructure. Okta's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

Getting Started

To run this example, run the following commands:

git clone https://github.com/oktadev/okta-angular-standalone-runtime-config-example.git
cd okta-angular-standalone-runtime-config-example
npm ci

Create an OIDC Application in Okta

Create a free developer account with the following command using the Okta CLI:

okta register

If…

View on GitHub

Complete code projects include testing. I didn't walk through the steps of adding unit tests in this post, but you can inspect the completed code project to view and run the tests, too.

Ready to read other interesting posts? Check out the following links.

Don't forget to follow us on Twitter and subscribe to our YouTube channel for more exciting content. We also want to hear about what tutorials you want to see. Leave us a comment below!

A Passwordless Future: Passkeys for Developers

Deepu K Sasidharan — Fri, 16 Feb 2024 15:53:42 +0000

Originally published at auth0.com

So, first things first, why do we even need to go passwordless? After all, passwords have been around for over 1000 years, right? And we were all happily sharing our Netflix passwords.

The Password Problem

The most important reason to go passwordless would be the password problem. According to Verizon's 2023 Data Breach Investigations Report, stolen credentials and phishing account for over 65% of all data breaches.

Most of the password problems are human problems in my opinion. Because passwords rely on us humans to remember them and to not share them and do a bunch of other stuff. History has repeatedly, a quadrillion times, shown us that we are not good at doing these things. So it is an us problem rather than the technology itself.

These are the main problems with passwords:

Knowledge-based:
- People can be socially engineered, quite easily, to divulge passwords, or other information that can be used to get to the password.
- In this day and age there are just too many passwords to remember. If passwords are easy to remember they are also easy to guess. Complex passwords are not easy to remember, so we end up reusing passwords.
Phishing: Phishing websites can easily harvest passwords from even the most tech-savvy.
Remote Replay: Accounts can be accessed remotely using harvested passwords.
Data Breach: Applications become a target for data breaches when they store passwords.
Share and Reuse: Sharing and reusing passwords makes them even more vulnerable.
Password management: Passwords are not just a hassle for the end users, they are a hassle on the server side as well. Because
- We need to build password recovery and reset flows.
- We need multi-factor authentication flows to secure them further.
- They need to be reset regularly in some use cases.

Did you know it could cost around 70$ to reset a password?

Of course, password managers help with some aspects of this and everyone should use one. But they are still an overhead and not very convenient for everyone, especially non-tech folks.

What is Passwordless?

The obvious solution for the password problem is to go passwordless. So what exactly is passwordless?

If you can verify a user's identity with something other than a password as the first factor of authentication, it is passwordless. We are doing this every day to unlock our phones and laptops using our fingerprints, faces, and so on.

There are a few passwordless methods that you might have seen here and there. Like:

Biometric authentication
Magic links
SMS/Email One-Time Password (OTP)
Push notifications

But most of these methods are not secure enough to replace a password + Multi-Factor Authentication (MFA) combination.

Passkeys

Passkeys are a password replacement that provide faster, easier, and more secure sign-ins to websites and apps across a user’s devices. Unlike passwords, passkeys are resistant to phishing, are always strong, and are designed so that there are no shared secrets.

— FIDO Alliance

This is where passkeys come into the picture. A secure passwordless future is the one offered by passkeys in my opinion. You probably already encountered passkeys since Google and GitHub have been rolling it out to all users recently. If you haven't set them up yet, you should!

A passkey is a unique cryptographic key pair that allows you to access online services without using passwords. It is based on asymmetric public-key cryptography.

Before we dive deep into passkeys let's look at some of the underlying technologies that make passkeys possible.

Public-key cryptography

Asymmetric public key cryptography involves a pair of mathematically linked keys: a public key, which is shared openly, and a private key, kept secret by the owner.

This key pair can be used for encryption. When a message is encrypted with the public key, only the corresponding private key can decrypt it, ensuring confidentiality.

The same key pair can also be used for digital signatures. A message signed with a private key can be verified with the public key, authenticating the sender's identity.

Passkeys use the signature verification mechanism. These keys are generated using a cryptographic algorithm, such as RSA or ECC.

Authenticator

An authenticator is a hardware or software entity that can create and store public-private key pairs which can be used for user registration and authentication. There are two types of authenticators:

Platform authenticators: An authenticator built into a user's device. For example, TouchID and FaceID from Apple, smartphone authenticators, Windows Hello, and so on.
Roaming authenticators: A removable authenticator usable with any device the user is trying to sign in from. They are attached using USB, NFC, and/or Bluetooth. For example, security keys like YubiKey, Google Titan and smartphones.

FIDO

FIDO stands for Fast IDentity Online. FIDO is a global authentication standard based on public key cryptography developed by the FIDO Alliance. It aims to solve all our password problems. FIDO Credentials are cryptographic key pairs that can be used for authentication.

Passkeys are made possible by the FIDO2 standard which is made up of Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP).

Web Authentication

Web Authentication is a W3C recommendation that lets a webpage use a set of JavaScript APIs to talk to authenticators.

The WebAuthn architecture consists of three main entities:

Authenticator: Platform or roaming authenticators that let a user authenticate by confirming their presence.
Relying Party: A server (custom implementation or an Identity Provider like Auth0) that requires authentication. It issues challenges and stores public keys.
Client: A client consists of the user's browser. The client relays information between an authenticator and a relying party.

Client to Authenticator Protocol

The FIDO Client to Authenticator Protocol is used for communications with authenticators over a variety of transports like USB, NFC, and Bluetooth. It is used to send requests from WebAuthn to authenticators.

Passkeys are passwordless FIDO credentials implemented using WebAuthn.

Passkeys were originally called FIDO Multi-Device Credentials implemented with the WebAuthn. But recently that definition has evolved to mean any passwordless FIDO credentials that are discoverable by the browser. Passkeys are still evolving and hence this could change as well. But for simplicity let's stick to passkeys as that is the term used by the FIDO Alliance.

Types of passkeys

Passkeys have two variants. Synced passkeys (sometimes referred to as multi-device passkeys) and device-bound passkeys (sometimes referred to as hardware-bound passkeys).

Synced passkeys

Synced passkeys have a better user experience since the private keys are end-to-end encrypted and synced to the cloud. For example, on the Apple ecosystem, the private key is synced on your iCloud Keychain and you can register on one device and log in to any synced Apple device. The same goes for the Google ecosystem using the Chrome browser and Google Password Manager. Or you can use a password manager like BitWarden or 1Password to store your passkeys.
This kind of passkeys can be restored on new devices. But they are less secure than single device-bound passkeys since your private key is on the cloud and theoretically can be breached.

Device-bound passkeys

In the device-bound passkeys, the private key stays on the device itself and you need to authenticate using the same authenticator used for registration. It is slightly less convenient but more secure than synced passkeys. The relying party must support registering multiple credentials for a user so that backup keys can be registered, which is a best practice for device-bound passkeys.

For example, I use a YubiKey with a fingerprint reader since I'm on Linux, and my passkeys are device-bound to that YubiKey. I don't get any roaming or backup benefits like in the Apple or Google ecosystem. But it's not a big deal, in my opinion, since I can register multiple YubiKeys as backup and use them on any device, and it's more secure and way more convenient than password + MFA.

How does it work?

Let's see how user registration and authentication work with passkeys.

User registration

First, let's see how the registration flow works.

The user begins the registration flow. The relying party provides a randomly generated challenge string.
The navigator.credentials.create() method of the WebAuthn API is invoked and the user provides approval using their authenticator.
The authenticator creates a private-public key pair which is unique for the relying party's domain and the user. The private key is used to sign the challenge.
- The private key is stored on the authenticator.
- For synced passkeys, the private key is also synced to a cloud service for backup and roaming (This is the only place where synced passkeys differ from device-bound passkeys).
- An attestation object is created which contains the public key, signed challenge, credential ID, and certificate.
The attestation object and other metadata are then passed to the relying party by the client-side implementation. The relying party verifies the signed challenge using the public key and registers the user by storing the public key and credential ID along with the user details.

User authentication

Now, let's see how the login flow works, which is quite similar except for the third step.

The user begins the login flow. The relying party provides a randomly generated challenge string.
The navigator.credentials.get() method of the WebAuthn API is invoked and the user provides approval using their authenticator.
The authenticator retrieves the private keys for the relying party's domain name.
- For synced passkeys, if the device is new, the private key is synced from a cloud service if available (This is the only place where synced passkeys differ from device-bound passkeys).
- The user selects the private key for their username. The private key is used to sign the challenge.
- An assertion object is created which contains the signed challenge and credential ID.
The assertion object and other metadata are then passed to the relying party by the client-side implementation. The relying party verifies the signed challenge using the public key stored for the user and authenticates the user.

Why Passkeys?

Let's see why we need passkeys to replace passwords.

Passkeys are superior to password + traditional OTP MFA in terms of security and usability and they are as secure and more convenient than password + FIDO MFA. Most importantly, you don’t have to remember anything (unless you are like me and forget your YubiKeys all the time).

Discoverable: Passwords are knowledge-based but passkeys are discoverable credentials and the browser can autofill them for a service making it unnecessary for you to remember even usernames. It doesn’t rely on something you know, instead, it relies on something you have or something you are which is more secure from hacking and social engineering.
Phishing resistant: Passkeys cannot be phished as they rely on public key cryptography and are bound to the domain name of the website, making it impossible to work on a spoofed website.
Remote attack resistant: Passkeys rely on physical keys, like biometric sensors of platform authenticators or roaming authenticators like YubiKey, hence cannot be remotely breached.
Breach resistant: The website only stores the public key of a user which is useless to an attacker on a data breach on the server side. This makes the server less attractive to hackers.
Not reusable and shareable*: They cannot be reused as they are unique per service and user combination and cannot be shared.
- *except for Apple which lets you share a passkey by air-dropping it 🤷🏽.
Easier management: Passkeys are scalable. Synced passkeys are backed up and replicated across your devices by services like iCloud Keychain, Google Password Manager, Bitwarden, and so on. This makes recovery part of the platform rather than the application.
Cross-device authentication: Passkeys can also perform cross-device authentication regardless of ecosystem or platform. For example, you can simply use your Android phone as an authenticator for your Apple laptop.

The security of passkeys is way better than most other combinations. When it comes to user experience, though it is subjective, I think it outperforms all other combinations.

How Does Passkeys Differ from WebAuthn Multi-Factor Authentication?

Technically they are very similar since both are implemented with WebAuthn and in the case of device-bound passkeys they are even more similar. However, some differences set them apart.

Passkeys are Discoverable Credentials and are entirely stored on the authenticator. This means for hardware keys like YubiKey, the private key is stored on the key itself and hence can only hold what its memory allows. They are client-side discoverable during authentication ceremonies and can be used in the autofill UI of the browser. WebAuthn/FIDO-based MFA implementations are Non-Discoverable Credentials or Server-side Credentials and hence are not client-side discoverable. They are stored server-side and the private key is encrypted and sent to the relying party, hence there is no storage limitation on the hardware key.
WebAuthn MFA does not have a synced option, passkeys do.
In the case of synced passkeys there are even more differences in terms of usability and security. For example, enrollment needs to be done only once and the private keys are synced to a cloud.

The most important difference is that passkeys can be used as first-factor authentication whereas WebAuthn MFA can only be used as a second-factor after user registration with a password.

Challenges

There are still some challenges when it comes to passkeys:

OS/Browser support: It is dependent on the OS and Browser to implement the specs, and we all know how that turns out right? This means the support may not be uniform and can become fragmented and we might never have the same experience everywhere.
Cloud vendor reliance: It relies on companies like Apple, Google, and Microsoft to save the private keys in their cloud securely and protect them from breaches.
Enterprise use cases: Enterprise users might want more control and flexibility which could be a problem. For example, if an enterprise doesn’t allow iCloud or Google Chrome on their computer, synced passkeys will not work there, only device-bound passkeys will work.
Reset & Recovery: There are no default recovery flows for device-bound passkeys, and applications might still need to implement recovery & reset flows to accommodate all use cases.

Browser and OS compatibility is still catching up. As of writing, Chrome has the best support and the Apple ecosystem has the most seamless experience, especially for platform authenticators. Linux does not have any support for platform authenticators. Roaming authenticators have great support on all platforms.

Conclusion

Passkeys are the future of secure authentication. They are more secure and more convenient than passwords and traditional MFA. They are also more secure and more convenient than other passwordless methods like magic links, SMS/Email OTP, and push notifications. The wider adoption of passkeys could finally solve the password problem and make the internet a safer place.

Passkeys are not just for the future, they are here now. You can start using them today. If you are a developer, you can start implementing them in your applications using Auth0. If you are a user, you can start using them on services that support them.

Resources

Check out this follow-up blog post.

A Passwordless Future: Passkeys for Java Developers

Deepu K Sasidharan for Okta ・ Jan 2

#java #spring #passkeys #webauthn

I hope that you found this article helpful. Here are some additional resources to learn more about WebAuthn and passkeys.

If you like this article, please leave a like or a comment.

You can follow me on Mastodon and LinkedIn.

How to Build a GraphQL API with Spring Boot

Jimena Garbarino — Tue, 30 Jan 2024 17:38:46 +0000

GraphQL is a query language for APIs and a runtime that allows the API consumer to get exactly the required information instead of the server exclusively controlling the contents of the response. While some REST API implementations require loading the references of a resource from multiple URLs, GraphQL APIs can follow references between related objects and return them in a single response.

This step-by-step guide demonstrates how to build a GraphQL API with Spring Boot and Spring for GraphQL for querying a sample dataset of related companies, persons, and properties seeded to a Neo4j database. It also demonstrates how to build a React client with Next.js and MUI Datagrid to consume the API. Both the client and the server are secured with Auth0 authentication using Okta Spring Boot Starter for the server and Auth0 React SDK for the client.

NOTE: If you prefer skipping the step-by-step building process and rather run this example and inspect the final code, you can follow the README instructions in the GitHub repository.

This example was created with the following tools and services:

Build a GraphQL API with Spring for GraphQL
- Add Neo4j seed data
- Run the Spring Boot API server
Build a React Client
- Create the API client
- Create a companies home page
Add Security with Auth0
- Add resource server security to the GraphQL API server
- Add Auth0 Login to the React client
- Call the API server with an access token
Update the GraphQL Query in the Client
Learn More about Spring Boot, GraphQL, and React

Build a GraphQL API with Spring for GraphQL

The resource server is a Spring Boot web application that exposes a GraphQL API with Spring for GraphQL. The API allows querying a Neo4j database containing information about companies and their related owners and properties using Spring Data Neo4j. The data was obtained from a Neo4j use case example.

Create the application with Spring Initializr and HTTPie:

https start.spring.io/starter.zip \
  bootVersion==3.2.1 \
  language==java \
  packaging==jar \
  javaVersion==17 \
  type==gradle-project \
  dependencies==data-neo4j,graphql,docker-compose,web \
  groupId==com.okta.developer \
  artifactId==spring-graphql  \
  name=="Spring Boot API" \
  description=="Demo project of a Spring Boot GraphQL API" \
  packageName==com.okta.developer.demo > spring-graphql-api.zip

Unzip the file and start editing the project. Define the GraphQL API with a schema file named schema.graphqls in the src/main/resources/graphql directory:

# src/main/resources/graphql/schema.graphqls

type Query {
    companyList(page: Int): [Company!]!
    companyCount: Int
}

type Company {
    id: ID
    SIC: String
    category: String
    companyNumber: String
    countryOfOrigin: String
    incorporationDate: String
    mortgagesOutstanding: Int
    name: String
    status: String
    controlledBy: [Person!]!
    owns: [Property!]!
}

type Person {
    id: ID
    birthMonth: String
    birthYear: String
    nationality: String
    name: String
    countryOfResidence: String
}

type Property {
    id: ID
    address: String
    county: String
    district: String
    titleNumber: String
}

As you can see, the schema defines the object types Company, Person, and Property and the query types companyList and companyCount.

Start adding classes for the domain. Create the package com.okta.developer.demo.domain under src/main/java. Add the classes Person, Property, and Company.

Here is the definition for the Person class:

// Person.java
package com.okta.developer.demo.domain;

import org.springframework.data.neo4j.core.schema.GeneratedValue;
import org.springframework.data.neo4j.core.schema.Id;
import org.springframework.data.neo4j.core.schema.Node;

@Node
public class Person {

    @Id @GeneratedValue
    private Long id;

    private String birthMonth;
    private String birthYear;
    private String countryOfResidence;

    private String name;
    private String nationality;

    public Person(String birthMonth, String birthYear, String countryOfResidence, String name, String nationality) {
        this.id = null;
        this.birthMonth = birthMonth;
        this.birthYear = birthYear;
        this.countryOfResidence = countryOfResidence;
        this.name = name;
        this.nationality = nationality;
    }

    public Person withId(Long id) {
        if (this.id.equals(id)) {
            return this;
        } else {
            Person newObject = new Person(this.birthMonth, this.birthYear, this.countryOfResidence, this.name, this.nationality);
            newObject.id = id;
            return newObject;
        }
    }

    public String getBirthMonth() {
        return birthMonth;
    }

    public void setBirthMonth(String birthMonth) {
        this.birthMonth = birthMonth;
    }

    public String getBirthYear() {
        return birthYear;
    }

    public void setBirthYear(String birthYear) {
        this.birthYear = birthYear;
    }

    public String getCountryOfResidence() {
        return countryOfResidence;
    }

    public void setCountryOfResidence(String countryOfResidence) {
        this.countryOfResidence = countryOfResidence;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getNationality() {
        return nationality;
    }

    public void setNationality(String nationality) {
        this.nationality = nationality;
    }

    public Long getId() {
        return this.id;
    }
}

The following is the definition for the Property class:

// Property.java
package com.okta.developer.demo.domain;

import org.springframework.data.neo4j.core.schema.GeneratedValue;
import org.springframework.data.neo4j.core.schema.Id;
import org.springframework.data.neo4j.core.schema.Node;

@Node
public class Property {

    @Id
    @GeneratedValue  private Long id;
    private String address;
    private String county;
    private String district;
    private String titleNumber;

    public Property(String address, String county, String district, String titleNumber) {
        this.id = null;
        this.address = address;
        this.county = county;
        this.district = district;
        this.titleNumber = titleNumber;
    }

    public Property withId(Long id) {
        if (this.id.equals(id)) {
            return this;
        } else {
            Property newObject = new Property(this.address, this.county, this.district, this.titleNumber);
            newObject.id = id;
            return newObject;
        }
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    public String getCounty() {
        return county;
    }

    public void setCounty(String county) {
        this.county = county;
    }

    public String getDistrict() {
        return district;
    }

    public void setDistrict(String district) {
        this.district = district;
    }

    public String getTitleNumber() {
        return titleNumber;
    }

    public void setTitleNumber(String titleNumber) {
        this.titleNumber = titleNumber;
    }
}

And this is the code for the Company class:

// Company.java
package com.okta.developer.demo.domain;

import org.springframework.data.neo4j.core.schema.GeneratedValue;
import org.springframework.data.neo4j.core.schema.Id;
import org.springframework.data.neo4j.core.schema.Node;
import org.springframework.data.neo4j.core.schema.Relationship;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;

@Node
public class Company {
    @Id
    @GeneratedValue
    private Long id;
    private String SIC;
    private String category;
    private String companyNumber;
    private String countryOfOrigin;
    private LocalDate incorporationDate;
    private Integer mortgagesOutstanding;
    private String name;
    private String status;

    // Mapped automatically
    private List<Property> owns = new ArrayList<>();

    @Relationship(type = "HAS_CONTROL", direction = Relationship.Direction.INCOMING)
    private List<Person> controlledBy = new ArrayList<>();

    public Company(String SIC, String category, String companyNumber, String countryOfOrigin, LocalDate incorporationDate, Integer mortgagesOutstanding, String name, String status) {
        this.id = null;
        this.SIC = SIC;
        this.category = category;
        this.companyNumber = companyNumber;
        this.countryOfOrigin = countryOfOrigin;
        this.incorporationDate = incorporationDate;
        this.mortgagesOutstanding = mortgagesOutstanding;
        this.name = name;
        this.status = status;
    }

    public Company withId(Long id) {
        if (this.id.equals(id)) {
            return this;
        } else {
            Company newObject = new Company(this.SIC, this.category, this.companyNumber, this.countryOfOrigin, this.incorporationDate, this.mortgagesOutstanding, this.name, this.status);
            newObject.id = id;
            return newObject;
        }
    }

    public String getSIC() {
        return SIC;
    }

    public void setSIC(String SIC) {
        this.SIC = SIC;
    }

    public String getCategory() {
        return category;
    }

    public void setCategory(String category) {
        this.category = category;
    }

    public String getCompanyNumber() {
        return companyNumber;
    }

    public void setCompanyNumber(String companyNumber) {
        this.companyNumber = companyNumber;
    }

    public String getCountryOfOrigin() {
        return countryOfOrigin;
    }

    public void setCountryOfOrigin(String countryOfOrigin) {
        this.countryOfOrigin = countryOfOrigin;
    }

    public LocalDate getIncorporationDate() {
        return incorporationDate;
    }

    public void setIncorporationDate(LocalDate incorporationDate) {
        this.incorporationDate = incorporationDate;
    }

    public Integer getMortgagesOutstanding() {
        return mortgagesOutstanding;
    }

    public void setMortgagesOutstanding(Integer mortgagesOutstanding) {
        this.mortgagesOutstanding = mortgagesOutstanding;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }
}

Create the package com.okta.developer.demo.repository and the class CompanyRepository:

// CompanyRepository.java
package com.okta.developer.demo.repository;

import com.okta.developer.demo.domain.Company;
import org.springframework.data.neo4j.repository.ReactiveNeo4jRepository;

public interface CompanyRepository extends ReactiveNeo4jRepository<Company, Long> {

}

Create the configuration class GraphQLConfig under the root package:

// GraphQLConfig.java
package com.okta.developer.demo;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.autoconfigure.graphql.GraphQlSourceBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
class GraphQLConfig {

    private static Logger logger = LoggerFactory.getLogger("graphql");

    @Bean
    public GraphQlSourceBuilderCustomizer sourceBuilderCustomizer() {
        return (builder) ->
                builder.inspectSchemaMappings(report -> {
                    logger.debug(report.toString());
                });
    }
}

Create a configuration class named SpringBootApiConfig in the root package as well, defining a reactive transaction manager required for reactive Neo4j:

// SpringBootApiConfig.java
package com.okta.developer.demo;

import org.neo4j.driver.Driver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.neo4j.core.ReactiveDatabaseSelectionProvider;
import org.springframework.data.neo4j.core.transaction.ReactiveNeo4jTransactionManager;
import org.springframework.data.neo4j.repository.config.ReactiveNeo4jRepositoryConfigurationExtension;
import org.springframework.transaction.ReactiveTransactionManager;

@Configuration
public class SpringBootApiConfig {

    @Bean(ReactiveNeo4jRepositoryConfigurationExtension.DEFAULT_TRANSACTION_MANAGER_BEAN_NAME) //Required for neo4j
    public ReactiveTransactionManager reactiveTransactionManager(
            Driver driver,
            ReactiveDatabaseSelectionProvider databaseNameProvider) {
        return new ReactiveNeo4jTransactionManager(driver, databaseNameProvider);
    }
}

Create the package com.okta.developer.demo.controller and the class CompanyController implementing the query endpoints matching the queries defined in the GraphQL schema:

// CompanyController.java
package com.okta.developer.demo.controller;

import com.okta.developer.demo.domain.Company;
import com.okta.developer.demo.repository.CompanyRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@Controller
public class CompanyController {

    @Autowired
    private CompanyRepository companyRepository;

    @QueryMapping
    public Flux<Company> companyList(@Argument Long page) {
        return companyRepository.findAll().skip(page * 10).take(10);
    }

    @QueryMapping
    public Mono<Long> companyCount() {
        return companyRepository.count();
    }
}

Create a CompanyControllerTests for the web layer in the directory src/main/test/java under the package com.okta.developer.demo.controller:

// src/main/test/java/CompanyControllerTests.java
package com.okta.developer.demo.controller;

import com.okta.developer.demo.domain.Company;
import com.okta.developer.demo.repository.CompanyRepository;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.graphql.GraphQlTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.graphql.test.tester.GraphQlTester;
import reactor.core.publisher.Flux;

import java.time.LocalDate;

import static org.mockito.Mockito.when;

@GraphQlTest(CompanyController.class)
public class CompanyControllerTests {

    @Autowired
    private GraphQlTester graphQlTester;

    @MockBean
    private CompanyRepository companyRepository;

    @Test
    void shouldGetCompanies() {

        when(this.companyRepository.findAll())
                .thenReturn(Flux.just(new Company(
                        "1234",
                        "private",
                        "12345678",
                        "UK",
                        LocalDate.of(2020, 1, 1),
                        0,
                        "Test Company",
                        "active")));

        this.graphQlTester
                .documentName("companyList")
                .variable("page", 0)
                .execute()
                .path("companyList")
                .matchesJson("""
                    [{
                        "id": null,
                        "SIC": "1234",
                        "name": "Test Company",
                        "status": "active",
                        "category": "private",
                        "companyNumber": "12345678",
                        "countryOfOrigin": "UK"
                    }]
                """);
    }
}

Create the document file companyList.graphql containing the query definition for the test, in the directory src/main/test/resources/graphql-test:

# src/main/test/resources/graphql-test/companyList.graphql
query companyList($page: Int) {
    companyList(page: $page) {
        id
        SIC
        name
        status
        category
        companyNumber
        countryOfOrigin
    }
}

Update the test configuration in build.gradle file, so passed tests are logged:

// build.gradle
tasks.named('test') {
    useJUnitPlatform()

    testLogging {
        // set options for log level LIFECYCLE
        events "failed", "passed"
    }
}

Run the test with:

./gradlew test

You should see logs for the successful tests:

...
SpringBootApiApplicationTests > contextLoads() PASSED

CompanyControllerTests > shouldGetCompanies() PASSED
...

Add Neo4j seed data

Let's add Neo4j migrations dependency for the seed data insertion. Edit the build.gradle file and add:

// build.gradle
dependencies {
    ...
    implementation 'eu.michael-simons.neo4j:neo4j-migrations-spring-boot-starter:2.8.2'
    ...
}

Create the directory src/main/resources/neo4j/migrations and the following migration files:

// src/main/resources/neo4j/migrations/V001_Constraint.cypher

CREATE CONSTRAINT FOR (c:Company) REQUIRE c.companyNumber IS UNIQUE;
//Constraint for a node key is a Neo4j Enterprise feature only - run on an instance with enterprise
//CREATE CONSTRAINT ON (p:Person) ASSERT (p.birthMonth, p.birthYear, p.name) IS NODE KEY
CREATE CONSTRAINT FOR (p:Person) REQUIRE (p.birthMonth, p.birthYear, p.name) IS UNIQUE;
CREATE CONSTRAINT FOR (p:Property) REQUIRE p.titleNumber IS UNIQUE;

// src/main/resources/neo4j/migrations/V002_Company.cypher

LOAD CSV WITH HEADERS FROM "file:///PSCAmericans.csv" AS row
MERGE (c:Company {companyNumber: row.company_number})
RETURN COUNT(*);

// src/main/resources/neo4j/migrations/V003_Person.cypher

LOAD CSV WITH HEADERS FROM "file:///PSCAmericans.csv" AS row
MERGE (p:Person {name: row.`data.name`, birthYear: row.`data.date_of_birth.year`, birthMonth: row.`data.date_of_birth.month`})
  ON CREATE SET p.nationality = row.`data.nationality`,
  p.countryOfResidence = row.`data.country_of_residence`
RETURN COUNT(*);

// src/main/resources/neo4j/migrations/V004_PersonCompany.cypher

LOAD CSV WITH HEADERS FROM "file:///PSCAmericans.csv" AS row
MATCH (c:Company {companyNumber: row.company_number})
MATCH (p:Person {name: row.`data.name`, birthYear: row.`data.date_of_birth.year`, birthMonth: row.`data.date_of_birth.month`})
MERGE (p)-[r:HAS_CONTROL]->(c)
SET r.nature = split(replace(replace(replace(row.`data.natures_of_control`, "[",""),"]",""),  '"', ""), ",")
RETURN COUNT(*);

// src/main/resources/neo4j/migrations/V005_CompanyData.cypher

LOAD CSV WITH HEADERS FROM "file:///CompanyDataAmericans.csv" AS row
MATCH (c:Company {companyNumber: row.` CompanyNumber`})
SET c.name = row.CompanyName,
c.mortgagesOutstanding = toInteger(row.`Mortgages.NumMortOutstanding`),
c.incorporationDate = Date(Datetime({epochSeconds: apoc.date.parse(row.IncorporationDate,'s','dd/MM/yyyy')})),
c.SIC = row.`SICCode.SicText_1`,
c.countryOfOrigin = row.CountryOfOrigin,
c.status = row.CompanyStatus,
c.category = row.CompanyCategory;

// src/main/resources/neo4j/migrations/V006_Land.cypher

LOAD CSV WITH HEADERS FROM "file:///LandOwnershipAmericans.csv" AS row
MATCH (c:Company {companyNumber: row.`Company Registration No. (1)`})
MERGE (p:Property {titleNumber: row.`Title Number`})
SET p.address = row.`Property Address`,
p.county  = row.County,
p.price   = toInteger(row.`Price Paid`),
p.district = row.District
MERGE (c)-[r:OWNS]->(p)
WITH row, c,r,p WHERE row.`Date Proprietor Added` IS NOT NULL
SET r.date = Date(Datetime({epochSeconds: apoc.date.parse(row.`Date Proprietor Added`,'s','dd-MM-yyyy')}));
CREATE INDEX FOR (c:Company) ON c.incorporationDate;

Update application.properties and add the following properties:

# src/main/resources/application.properties
spring.graphql.graphiql.enabled=true
spring.graphql.schema.introspection.enabled=true
org.neo4j.migrations.transaction-mode=PER_STATEMENT

spring.graphql.cors.allowed-origins=http://localhost:3000

The property spring.graphql.cors.allowed-origins will eventually enable CORS for the client application.

Create a .env file in the server root to store the Neo4j credentials:

# .env
export NEO4J_PASSWORD=verysecret

If using git, don't forget to add the .env file to the ignored files.

Download the following seed files to an empty directory, as it will be mounted to the Neo4j container:

Spring Boot's Docker Compose integration now supports Neo4j. Edit the compose.yaml file and add a service for the Neo4j database.

# compose.yaml
services:
  neo4j:
    image: neo4j:5
    volumes:
      - <csv-dir>:/var/lib/neo4j/import
    environment:
      - NEO4J_AUTH=neo4j/${NEO4J_PASSWORD}
      - NEO4JLABS_PLUGINS=["apoc"]
    # If you want to expose these ports outside your dev PC,
    # remove the "127.0.0.1:" prefix
    ports:
      - '127.0.0.1:7474:7474'
      - '127.0.0.1:7687:7687'
    healthcheck:
      test: ['CMD', 'wget', 'http://localhost:7474/', '-O', '-']
      interval: 5s
      timeout: 5s
      retries: 10

As you can see the compose file will mount <csv-dir> to a /var/lib/neo4j/import volume, making the content accessible from the running Neo4j container.
Replace <csv-dir> with the path to the CSV files downloaded before.

Run the Spring Boot API server

Go to the project root directory and start the application with:

./gradlew bootRun

Wait for the logs to inform the seed data migrations have run:

2023-09-13T11:52:08.041-03:00  ... Applied migration 001 ("Constraint").
2023-09-13T11:52:12.121-03:00  ... Applied migration 002 ("Company").
2023-09-13T11:52:16.508-03:00  ... Applied migration 003 ("Person").
2023-09-13T11:52:22.635-03:00  ... Applied migration 004 ("PersonCompany").
2023-09-13T11:52:25.979-03:00  ... Applied migration 005 ("CompanyData").
2023-09-13T11:52:27.703-03:00  ... Applied migration 006 ("Land").

Test the API with GraphiQL at http://localhost:8080/graphiql. In the query box on the left, paste the following query:

{
    companyList(page: 20) {
        id
        SIC
        name
        status
        category
        companyNumber
        countryOfOrigin
    }
}

You should see the query output in the box on the right:

NOTE: If you see a warning message in the server logs, that reads The query used a deprecated function: id, you can ignore it. Spring Data Neo4j still behaves correctly.

Build a React Client

Now let's create a Single Page Application (SPA) to consume the GraphQL API with React and Next.js. The list of companies will be displayed in a MUI Data Grid component. The application will use Next.js' App Router. The src/app directory will only contain routing files, and the UI components and application code will be in other directories.

Install Node, and in a terminal, run the create-next-app command at the parent directory of the Spring Boot application. It will create a project directory for the client application at the same level as the server application directory:

npx create-next-app

Answer the questions as follows:

✔ What is your project named? ... react-graphql
✔ Would you like to use TypeScript? ... Yes
✔ Would you like to use ESLint? ... Yes
✔ Would you like to use Tailwind CSS? ... No
✔ Would you like to use `src/` directory? ... Yes
✔ Would you like to use App Router? (recommended) ... Yes
✔ Would you like to customize the default import alias? ... No

Then add the MUI Datagrid dependencies, custom hooks from Vercel, and Axios:

cd react-graphql && \
  npm install @mui/x-data-grid && \
  npm install @mui/material@5.14.5 @emotion/react @emotion/styled && \
  npm install react-use-custom-hooks && \
  npm install axios

Run the application with:

npm run dev

Navigate to http://localhost:3000, and you should see the default Next.js page:

Create the API client

Create the directory src/services and add the file base.tsx with the following code:

// src/services/base.tsx
import axios from 'axios';

export const backendAPI = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_SERVER_URL
});

export default backendAPI;

Add the file src/services/companies.tsx with the following content:

// src/services/companies.tsx
import { AxiosError } from 'axios';
import { backendAPI } from './base';

export type CompaniesQuery = {
  page: number;
};

export type CompanyDTO = {
  name: string;
  SIC: string;
  id: string;
  companyNumber: string;
  category: string;
};

export const CompanyApi = {

  getCompanyCount: async () => {
    try {
      const response = await backendAPI.post('/graphql', {
        query: `{
        companyCount
      }`,
      });
      return response.data.data.companyCount as number;
    } catch (error) {
      console.log('handle get company count error', error);
      if (error instanceof AxiosError) {
        let axiosError = error as AxiosError;
        if (axiosError.response?.data) {
          throw new Error(axiosError.response?.data as string);
        }
      }
      throw new Error('Unknown error, please contact the administrator');
    }
  },

  getCompanyList: async (params?: CompaniesQuery) => {
    try {
      const response = await backendAPI.post('/graphql', {
        query: `{
        companyList(page: ${params?.page || 0}) {
          name,
          SIC,
          id,
          companyNumber,
          category
        }}`,
      });
      return response.data.data.companyList as CompanyDTO[];
    } catch (error) {
      console.log('handle get companies error', error);
      if (error instanceof AxiosError) {
        let axiosError = error as AxiosError;
        if (axiosError.response?.data) {
          throw new Error(axiosError.response?.data as string);
        }
      }
      throw new Error('Unknown error, please contact the administrator');
    }
  },

};

Add a file .env.example and .env.local in the root directory, both with the following content:

NEXT_PUBLIC_API_SERVER_URL=http://localhost:8080

NOTE: The .env.local is ignored in the repository, and the .env.example is pushed as a reference on what environment variables are required for running the application.

Create a companies home page

Create the directory src/components/company and add the file CompanyTable.tsx with the following content:

// src/components/company/CompanyTable.tsx
import { DataGrid, GridColDef, GridEventListener, GridPaginationModel } from '@mui/x-data-grid';

export interface CompanyData {
  id: string,
  name: string,
  category: string,
  companyNumber: string,
  SIC: string
}

export interface CompanyTableProps {
  rowCount: number,
  rows: CompanyData[],
  columns: GridColDef[],
  pagination: GridPaginationModel,
  onRowClick?: GridEventListener<'rowClick'>
  onPageChange?: (pagination: GridPaginationModel) => void,

}

const CompanyTable = (props: CompanyTableProps) => {

  return (
    <>
      <DataGrid
        rowCount={props.rowCount}
        rows={props.rows}
        columns={props.columns}
        pageSizeOptions={[props.pagination.pageSize ]}
        initialState={{
          pagination: {
            paginationModel: { page: props.pagination.page, pageSize: props.pagination.pageSize },
          },
        }}
        density='compact'
        disableColumnMenu={true}
        disableRowSelectionOnClick={true}
        disableColumnFilter={true}
        disableDensitySelector={true}
        paginationMode='server'
        onRowClick={props.onRowClick}
        onPaginationModelChange={props.onPageChange}
      />
    </>
  );
};

export default CompanyTable;

Create a Loader.tsx component in the directory src/components/loader with the following code:

// src/components/loader/Loader.tsx
import { Box, CircularProgress, Skeleton } from '@mui/material';

const Loader = () => {
  return (
    <Box sx={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: 200 }}>
      <CircularProgress />
    </Box>
  );
}

export default Loader;

Add the file src/components/company/CompanyTableContainer.tsx with the following content:

// src/components/company/CompanyTableContainer.tsx
import { GridColDef, GridPaginationModel } from '@mui/x-data-grid';
import CompanyTable from './CompanyTable';
import { usePathname, useRouter, useSearchParams } from 'next/navigation';
import { CompanyApi } from '@/services/companies';
import Loader from '../loader/Loader';
import { useAsync } from 'react-use-custom-hooks';

interface CompanyTableProperties {
  page?: number;
}

const columns: GridColDef[] = [
  { field: 'id', headerName: 'ID', width: 70 },
  {
    field: 'companyNumber',
    headerName: 'Company #',
    width: 100,
    sortable: false,
  },
  { field: 'name', headerName: 'Company Name', width: 350, sortable: false },
  { field: 'category', headerName: 'Category', width: 200, sortable: false },
  { field: 'SIC', headerName: 'SIC', width: 400, sortable: false },
];

const CompanyTableContainer = (props: CompanyTableProperties) => {
  const router = useRouter();
  const searchParams = useSearchParams()!;
  const pathName = usePathname();
  const page = props.page ? props.page : 1;

  const [dataList, loadingList, errorList] = useAsync(
    () => CompanyApi.getCompanyList({ page: page - 1 }),
    {},
    [page]
  );
  const [dataCount] = useAsync(() => CompanyApi.getCompanyCount(), {}, []);

  const onPageChange = (pagination: GridPaginationModel) => {
    const params = new URLSearchParams(searchParams.toString());
    const page = pagination.page + 1;
    params.set('page', page.toString());
    router.push(pathName + '?' + params.toString());
  };

  return (
    <>
      {loadingList && <Loader />}
      {errorList && <div>Error</div>}

      {!loadingList && dataList && (
        <CompanyTable
          pagination={{ page: page - 1, pageSize: 10 }}
          rowCount={dataCount}
          rows={dataList}
          columns={columns}
          onPageChange={onPageChange}
        ></CompanyTable>
      )}
    </>
  );
};

export default CompanyTableContainer;

Add the following src/app/HomePage.tsx file for the homepage:

// src/app/HomePage.tsx
'use client';

import CompanyTableContainer from '@/components/company/CompanyTableContainer';
import { Box, Typography } from '@mui/material';
import { useSearchParams } from 'next/navigation';

const HomePage = () => {
  const searchParams = useSearchParams();
  const page = searchParams.get('page')
    ? parseInt(searchParams.get('page') as string)
    : 1;

  return (
    <>
      <Box>
        <Typography variant='h4' component='h1'>
          Companies
        </Typography>
      </Box>
      <Box mt={2}>
        <CompanyTableContainer page={page}></CompanyTableContainer>
      </Box>
    </>
  );
};

export default HomePage;

Replace the contents of src/app/page.tsx and change it to render the HomePage component:

// src/app/page.tsx
import HomePage from './HomePage';

const Page = () => {
  return (
    <HomePage/>
  );
}

export default Page;

Add a component defining the page width, for using it in the root layout. Create src/layout/WideLayout.tsx with the following content:

// src/layout/WideLayout.tsx
'use client';

import { Container, ThemeProvider, createTheme } from '@mui/material';

const theme = createTheme({
  typography: {
    fontFamily: 'inherit',
  },
});

const WideLayout = (props: { children: React.ReactNode }) => {
  return (
    <ThemeProvider theme={theme}>
      <Container maxWidth='lg' sx={{ mt: 4 }}>
        {props.children}
      </Container>
    </ThemeProvider>
  );
};

export default WideLayout;

With the implementation above, the page content will be wrapped in a ThemeProvider component, so MUI child components inherit the font family from the root layout.
Update the contents of src/app/layout.tsx to be:

// src/app/layout.tsx
import WideLayout from '@/layout/WideLayout';
import { Ubuntu} from 'next/font/google';

const font = Ubuntu({
  subsets: ['latin'],
  weight: ['300','400','500','700'],
});

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang='en'>
      <body className={font.className}>
        <WideLayout>{children}</WideLayout>
      </body>
    </html>
  );
}

Also, remove src/app/globals.css and src/app/page.module.css. Then run the client application with:

npm run dev

Navigate to http://localhost:3000 and you should see the companies list:

Add Security with Auth0

For securing both the server and client, the Auth0 platform provides the best customer experience, and with a few simple configuration steps, you can add authentication to your applications. Sign up at Auth0 and install the Auth0 CLI that will help you create the tenant and the client applications.

Add resource server security to the GraphQL API server

In the command line, log in to Auth0 with the CLI:

auth0 login

The command output will display a device confirmation code and open a browser session to activate the device.

NOTE: In case your browser does not open automatically, activate the device by manually opening the URL https://auth0.auth0.com/activate?user_code={deviceCode}.

On successful login, you will see the tenant, which you will use as the token issuer later.

The next step is to create a client app, which you can do in one command:

auth0 apps create \
  --name "GraphQL Server" \
  --description "Spring Boot GraphQL Resource Server" \
  --type regular \
  --callbacks http://localhost:8080/login/oauth2/code/okta \
  --logout-urls http://localhost:8080 \
  --reveal-secrets

Once the app is created, you will see the OIDC app's configuration:

=== dev-avup2laz.us.auth0.com application created

  CLIENT ID            ***
  NAME                 GraphQL Server
  DESCRIPTION          Spring Boot GraphQL Resource Server
  TYPE                 Regular Web Application
  CLIENT SECRET        ***
  CALLBACKS            http://localhost:8080/login/oauth2/code/okta
  ALLOWED LOGOUT URLS  http://localhost:8080
  ALLOWED ORIGINS
  ALLOWED WEB ORIGINS
  TOKEN ENDPOINT AUTH
  GRANTS               implicit, authorization_code, refresh_token, client_credentials

 ▸    Quickstarts: https://auth0.com/docs/quickstart/webapp
 ▸    Hint: Emulate this app's login flow by running `auth0 test login ***`
 ▸    Hint: Consider running `auth0 quickstarts download ***`

Add the okta-spring-boot-starter dependency to the build.gradle file in the spring-graphql-api project:

// build.gradle
dependencies {
    ...
    implementation 'com.okta.spring:okta-spring-boot-starter:3.0.6'
    ...
}

Set the client ID, issuer, and audience for OAuth 2.0 in the application.properties file:

# src/main/resources/application.properties
okta.oauth2.issuer=https://<your-auth0-domain>/
okta.oauth2.client-id=<client-id>
okta.oauth2.audience=${okta.oauth2.issuer}api/v2/

Add the client secret to the .env file:

# .env
export OKTA_OAUTH2_CLIENT_SECRET=<client-secret>

Add the following factory method to the class SpringBootApiConfig, for requiring a bearer token for all requests:

// SpringBootApiConfig.java
    ...
    @Bean
    public SecurityFilterChain configure(HttpSecurity http) throws Exception {
        http.oauth2ResourceServer(oauth2ResourceServer -> oauth2ResourceServer.jwt(withDefaults()));
        return http.build();
    }
    ...

NOTE: The Okta Spring Boot starter provides the security auto-configuration out of the box, and the resource server configuration should not be necessary. For some reason, the Spring for GraphQL CORS allowed origins configuration does not take effect without the customization above.

Again, in the root directory, run the API server with:

./gradlew bootRun

Get an access token using the Auth0 CLI with the auth0 test token command:

auth0 test token -a https://<your-auth0-domain>/api/v2/ -s openid

Select the CLI Login Testing app or any available client when prompted. You will also be prompted to open a browser window and log in with a user credential.

With HTTPie, send a request to the API server using a bearer access token:

ACCESS_TOKEN=<auth0-access-token>

echo -E '{"query":"{\n    companyList(page: 20) {\n        id\n        SIC\n        name\n        status\n        category\n        companyNumber\n        countryOfOrigin\n    }\n}"}' | \
  http -A bearer -a $ACCESS_TOKEN POST http://localhost:8080/graphql

NOTE: You can also follow these instructions for creating a test access token.

Add Auth0 Login to the React client

When using Auth0 as the identity provider, you can configure the Universal Login page for a quick integration without having to build the login forms. First, register a SPA application using the Auth0 CLI:

auth0 apps create \
  --name "React client for GraphQL" \
  --description "SPA React client for a Spring GraphQL API" \
  --type spa \
  --callbacks http://localhost:3000/callback \
  --logout-urls http://localhost:3000 \
  --origins http://localhost:3000 \
  --web-origins http://localhost:3000

Copy the Auth0 domain and the client ID, and update the .env.local adding the following properties:

# .env.local
NEXT_PUBLIC_AUTH0_DOMAIN=<your-auth0-domain>
NEXT_PUBLIC_AUTH0_CLIENT_ID=<client-id>
NEXT_PUBLIC_AUTH0_CALLBACK_URL=http://localhost:3000/callback
NEXT_PUBLIC_AUTH0_AUDIENCE=https://$NEXT_PUBLIC_AUTH0_DOMAIN/api/v2/

Add the new variables to the file .env.example too, but not the values, for documenting the required configuration.

For handling the Auth0 post-login behavior, you need to add the page src/app/callback/page.tsx with the following content:

// src/app/callback/page.tsx
import Loader from '@/components/loader/Loader';

const Page = () => {
  return <Loader/>
};

export default Page;

For this example, the callback page will render empty.

Add the @auth0/auth0-react dependency to the project:

npm install @auth0/auth0-react

NOTE: You might wonder why I'm using the Auth0 React SDK instead of the Auth0 Next.js SDK. I'm only using the front-end features of Next.js. If this example used a Next.js backend, the Auth0 Next.js SDK would make more sense.

Create the component Auth0ProviderWithNavigate in the directory src/components/authentication with the following content:

// src/components/authentication/Auth0ProviderWithNavigate.tsx
import { AppState, Auth0Provider } from '@auth0/auth0-react';
import { useRouter } from 'next/navigation';
import React from 'react';

const Auth0ProviderWithNavigate = (props: { children: React.ReactNode }) => {
  const router = useRouter();

  const domain = process.env.NEXT_PUBLIC_AUTH0_DOMAIN || '';
  const clientId = process.env.NEXT_PUBLIC_AUTH0_CLIENT_ID || ''
  const redirectUri = process.env.NEXT_PUBLIC_AUTH0_CALLBACK_URL || '';
  const audience = process.env.NEXT_PUBLIC_AUTH0_AUDIENCE || '';

  const onRedirectCallback = (appState?: AppState) => {
    router.push(appState?.returnTo || window.location.pathname);
  };

  if (!(domain && clientId && redirectUri)) {
    return null;
  }

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{
        audience: audience,
        redirect_uri: redirectUri,
      }}
      useRefreshTokens={true}
      onRedirectCallback={onRedirectCallback}
    >
      <>{props.children}</>
    </Auth0Provider>
  );
};

export default Auth0ProviderWithNavigate;

The component Auth0ProviderWithNavigate wraps the children component with Auth0Provider, the provider of the Auth0 context, remembering the requested URL for redirection after login.
Use the component in the WideLayout component. The final code must look like this:

// WideLayout.tsx
'use client';

import Auth0ProviderWithNavigate from '@/components/authentication/Auth0ProviderWithNavigate';
import { Container, ThemeProvider, createTheme } from '@mui/material';

const theme = createTheme({
  typography: {
    fontFamily: 'inherit',
  },
});

const WideLayout = (props: { children: React.ReactNode }) => {
  return (
    <ThemeProvider theme={theme}>
      <Auth0ProviderWithNavigate>
        <Container maxWidth='lg' sx={{ mt: 4 }}>
          {props.children}
        </Container>
      </Auth0ProviderWithNavigate>
    </ThemeProvider>
  );
};

export default WideLayout;

Add the file src/components/authentication/AuthenticationGuard.tsx with the following content:

// src/components/authentication/AuthenticationGuard.tsx
'use client'

import { useAuth0 } from '@auth0/auth0-react';
import { useEffect } from 'react';
import Loader from '../loader/Loader';

const AuthenticationGuard = (props: { children: React.ReactNode }) => {
  const { isLoading, isAuthenticated, error, loginWithRedirect } = useAuth0();

  useEffect(() => {
    if (!isAuthenticated && !isLoading) {
      loginWithRedirect({
        appState: { returnTo: window.location.href },
      });
    }
  }, [isAuthenticated, isLoading, loginWithRedirect]);

  if (isLoading) {
    return <Loader />;
  }
  if (error) {
    return <div>Oops... {error.message}</div>;
  }
  return <>{isAuthenticated && props.children}</>;
};

export default AuthenticationGuard;

The AuthenticationGuard component will be used to protect pages that require authentication, redirecting to the Auth0 Universal Login. Protect the index page by wrapping its content in the AuthenticationGuard component:

// app/page.tsx
import AuthenticationGuard from '@/components/authentication/AuthenticationGuard';
import HomePage from './HomePage';

const Page = () => {
  return (
    <AuthenticationGuard>
      <HomePage/>
    </AuthenticationGuard>
  );
};

export default Page;

Call the API server with an access token

Add the file src/services/auth.tsx with the following code:

// src/services/auth.tsx
import backendAPI from './base';

let requestInterceptor: number;
let responseInterceptor: number;

export const clearInterceptors = () => {
  backendAPI.interceptors.request.eject(requestInterceptor);
  backendAPI.interceptors.response.eject(responseInterceptor);
};

export const setInterceptors = (accessToken: String) => {

  clearInterceptors();

  requestInterceptor = backendAPI.interceptors.request.use(
    // @ts-expect-error
    function (config) {
      return {
        ...config,
        headers: {
          ...config.headers,
          Authorization: `Bearer ${accessToken}`,
        },
      };
    },
    function (error) {
      console.log('request interceptor error', error);
      return Promise.reject(error);
    }
  );
};

Add the file src/hooks/useAccessToken.tsx with the following content:

// src/hooks/useAccessToken.tsx
import { setInterceptors } from '@/services/auth';
import { useAuth0 } from '@auth0/auth0-react';
import { useCallback, useState } from 'react';

export const useAccessToken = () => {
  const { isAuthenticated, getAccessTokenSilently } = useAuth0();
  const [accessToken, setAccessToken] = useState('');

  const saveAccessToken = useCallback(async () => {
    if (isAuthenticated) {
      try {
        const tokenValue = await getAccessTokenSilently();
        if (accessToken !== tokenValue) {
          setInterceptors(tokenValue);
          setAccessToken(tokenValue);
        }
      } catch (err) {
        // Inactivity timeout
        console.log('getAccessTokenSilently error', err);
      }
    }
  }, [getAccessTokenSilently, isAuthenticated, accessToken]);

  return {
    saveAccessToken,
  };
};

The hook will call Auth0's getAccessTokenSilently() and trigger a token refresh if the access token expires. Then, it will update Axios interceptors to set the updated bearer token value in the request headers.
Create the useAsyncWithToken hook:

// src/hooks/useAsyncWithToken.tsx
import { useAccessToken } from './useAccessToken';
import { useAsync } from 'react-use-custom-hooks';

export const useAsyncWithToken = <T, P, E = string>(
  asyncOperation: () => Promise<T>, deps: any[]
) => {
  const { saveAccessToken } = useAccessToken();
  const [ data, loading, error ] = useAsync(async () => {
    await saveAccessToken();
    return asyncOperation();
  }, {},  deps);

  return {
    data,
    loading,
    error
  };
};

Update the calls in the CompanyTableContainer component to use the useAsyncWithToken hook instead of useAsync:

// src/components/company/CompanyTableContainer.tsx
- import { useAsync } from 'react-use-custom-hooks';
+ import { useAsyncWithToken } from '@/hooks/useAsyncWithToken';

...
- const [dataList, loadingList, errorList] = useAsync(
-   () => CompanyApi.getCompanyList({ page: page - 1 }),
-   {},
-   [page]
-  );
- const [dataCount] = useAsync(() => CompanyApi.getCompanyCount(), {}, []);
+ const {
+   data: dataList,
+   loading: loadingList,
+   error: errorList,
+ } = useAsyncWithToken(
+   () => CompanyApi.getCompanyList({ page: page - 1}),
+   [props.page]
+ );
+
+ const { data: dataCount } = useAsyncWithToken(
+   () => CompanyApi.getCompanyCount(),
+   []
+ );
...

Run the application with:

npm run dev

Go to http://localhost:3000 and you should be redirected to the Auth0 Universal Login page. After logging in, you should see the companies list again.

Once the companies load, you can inspect the network requests and see the bearer token is sent in the request headers. It will look like the example below:

Authorization: Bearer eyJhbGciOiJSU...

Update the GraphQL Query in the Client

The GraphQL query in the React client application can be easily updated to request more data from the server. For example, add the status and information about who controls the company. First, update the API client:

// src/services/companies.tsx
...

export type PersonDTO = {
  name: string;
}

export type CompanyDTO = {
  name: string;
  SIC: string;
  id: string;
  companyNumber: string;
  category: string;
  status: string;
  controlledBy: PersonDTO[]
};

...

  getCompanyList: async (params?: CompaniesQuery) => {

    try {
      const response = await backendAPI.post('/graphql', {
        query: `{
        companyList(page: ${params?.page || 0}) {
          name,
          SIC,
          id,
          companyNumber,
          category,
          status,
          controlledBy {
            name
          }
        }}`,
      });
      return response.data.data.companyList as CompanyDTO[];
    } catch (error) {
      console.log('handle get companies error', error);
      if (error instanceof AxiosError) {
        let axiosError = error as AxiosError;
        if (axiosError.response?.data) {
          throw new Error(axiosError.response?.data as string);
        }
      }
      throw new Error('Unknown error, please contact the administrator');
    }
  },
...

Then update the CompanyData interface in the CompanyTable.tsx component:

// src/components/company/CompanyTable.tsx
export interface CompanyData {
  id: string,
  name: string,
  category: string,
  companyNumber: string,
  SIC: string
  status: string,
  owner: string
}

Finally, update the CompanyTableContainer column definitions and data formatting. The final code should look like below:

// src/components/company/CompanyTableContainer.tsx
import { GridColDef, GridPaginationModel } from '@mui/x-data-grid';
import CompanyTable from './CompanyTable';
import { usePathname, useRouter, useSearchParams } from 'next/navigation';
import { CompanyApi, CompanyDTO } from '@/services/companies';
import Loader from '../loader/Loader';
import { useAsyncWithToken } from '@/hooks/useAsyncWithToken';

interface CompanyTableProperties {
  page?: number;
}

const columns: GridColDef[] = [
  { field: 'id', headerName: 'ID', width: 70 },
  {
    field: 'companyNumber',
    headerName: 'Company #',
    width: 100,
    sortable: false,
  },
  { field: 'name', headerName: 'Company Name', width: 250, sortable: false },
  { field: 'category', headerName: 'Category', width: 200, sortable: false },
  { field: 'SIC', headerName: 'SIC', width: 200, sortable: false },
  { field: 'status', headerName: 'Status', width: 100, sortable: false },
  { field: 'owner', headerName: 'Owner', width: 200, sortable: false },
];

const CompanyTableContainer = (props: CompanyTableProperties) => {
  const router = useRouter();
  const searchParams = useSearchParams()!;
  const pathName = usePathname();
  const page = props.page ? props.page : 1;

  const {
    data: dataList,
    loading: loadingList,
    error: errorList,
  } = useAsyncWithToken(
    () => CompanyApi.getCompanyList({ page: page - 1}),
    [props.page]
  );

  const { data: dataCount } = useAsyncWithToken(
    () => CompanyApi.getCompanyCount(),
    []
  );

  const onPageChange = (pagination: GridPaginationModel) => {
    const params = new URLSearchParams(searchParams.toString());
    const page = pagination.page + 1;
    params.set('page', page.toString());
    router.push(pathName + '?' + params.toString());
  };

  const companyData = dataList?.map((company: CompanyDTO) => {
    return {
      id: company.id,
      name: company.name,
      category: company.category,
      companyNumber: company.companyNumber,
      SIC: company.SIC,
      status: company.status,
      owner: company.controlledBy.map((person) => person.name).join(', '),
    }
  });

  return (
    <>
      {loadingList && <Loader />}
      {errorList && <div>Error</div>}

      {!loadingList && dataList && (
        <CompanyTable
          pagination={{ page: page - 1, pageSize: 10 }}
          rowCount={dataCount}
          rows={companyData}
          columns={columns}
          onPageChange={onPageChange}
        ></CompanyTable>
      )}
    </>
  );
};

export default CompanyTableContainer;

Give it a try. It's pretty neat how GraphQL allows you to get more data just by changing the client!

Learn More about Spring Boot, GraphQL, and React

I hope you enjoyed this tutorial and found this example useful. As you can see, not much work would be required to consume more company data from the GraphQL server, just a query update in the client. Also, the Auth0 Universal Login and Auth0 React SDK provide an efficient way to secure your React applications, following security best practices. You can find all the code for this example in the GitHub repository.

Check out the Auth0 documentation for adding sign-up and logout to your React application. And for more fun tutorials about Spring Boot, GraphQL, and React, you can visit the following links:

Keep in touch! If you have questions about this post, please ask them in the comments below. And follow us! We're @oktadev on Twitter, @oktadev on YouTube, and we frequently post to our LinkedIn page. You can also sign up for our newsletter to stay updated on everything Identity and Security.

How I Used Docker to Spin Up SQL Server on My Mac in 3 Easy Steps

Kiah Imani 🇧🇧 — Thu, 18 Jan 2024 04:47:29 +0000

Hi friends!

So, I recently kicked off a pretty cool 90-Day MVP project and guess what? I bumped into a bit of a snag. I needed to get SQL Server up and running on my Mac. Now, if you’ve ever tried this, you know it’s not the most straightforward task. SQL Server and Macs don’t usually play nice together, right? But don’t worry, I’ve got you covered. In this blog post, I’m going to walk you through the whole process, step by step.

Step 1: Install & Configure Docker

First things first: You need to install Docker. Here’s an article to help you do it.

Alright, before we jump into installing SQL Server using Docker, here’s a quick but important step, we need to give Docker a bit more memory to work with. Here’s how you do it: First, click on that little Preferences gear icon in the top right corner of your Docker app. Once you’re there, head over to the Resources tab. You’ll see a Memory slider, it’s usually set at 2 GB by default. Let’s bump that up to 4 GB.

Just slide that little guy over to the right. Done? Great! Now hit Apply & Restart. That’s it, Docker now has more room to breathe, and we’re all set for a smoother installation.

Step 2: Install & Setup SQL Server

Ok, folks, it’s go time! We’re now ready to download, set up, and get SQL Server running on your Mac. Here’s the game plan:

First things first, let’s open Terminal.

Once your Terminal window is up, you’re going to type in this command (it’s a bit of a mouthful, but you’ve got this!):

docker pull mcr.microsoft.com/mssql/server:2022-latest

Hit Enter, and the download will kick off. Just hang tight for a bit.

After the download wraps up, it’s time to fire up your brand-new SQL Server image in Docker. Here’s the magic command you need:

docker run -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=strongestPasswordEver123%'-p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest

A quick note: by typing ACCEPT_EULA=Y , you’re giving a thumbs-up to Docker’s end user license agreement.

And voilà, SQL Server should be humming along on your machine. To double-check, click the Docker icon in your menu bar and peek at the Dashboard.

Step 3: Install Azure Data Studio & Connect to Your SQL Server Instance

Next up: You need Azure Data Studio. Think of it as the Mac’s answer to SQL Server Management Studio (SSMS). Download it, then drag and drop the Azure Data Studio icon from Downloads to Applications in Finder.

Open Azure Data Studio and hit ‘New connection’. Since SQL Server is running on your Mac, just type localhost for the server. Your username is sa (that’s short for system admin), and the password is what you used in the Terminal command. In our little example here, that’s strongestPasswordEver123% .

And there you have it! You’re all set to rock and roll with SQL Server on your Mac.

Also, just a heads up, even though we’re all about getting Microsoft SQL Server up and running on macOS in this tutorial, there’s no reason you can’t use these same tricks for Docker on Windows or Linux. It’s pretty versatile like that!

And hey, if any of you out there are wizards at cross-platform development with .NET and have some cool tips or sneaky tricks up your sleeve, I’m all ears. Sharing is caring, right? Let’s make this .NET development journey easier for everyone!

Java Microservices with Spring Boot and Spring Cloud

Matt Raible — Thu, 11 Jan 2024 20:11:00 +0000

Adopting a microservices architecture provides unique opportunities to add failover and resiliency to your systems so your components can gracefully handle load spikes and errors. Microservices make change less expensive, too. They can also be a good idea when you have a large team working on a single product. You can break up your project into components that can function independently. Once components can operate independently, they can be built, tested, and deployed separately. This gives an organization and its teams the agility to develop and deploy quickly.

Java is an excellent language with a vast open source ecosystem for developing a microservice architecture. In fact, some of the biggest names in our industry use Java and contribute to its ecosystem. Have you ever heard of Netflix, Amazon, or Google? What about eBay, Twitter, and LinkedIn? Yes, web-scale companies handling incredible traffic are doing it with Java.

Implementing a microservices architecture in Java isn't for everyone. For that matter, implementing microservices, in general, isn't often needed. Most companies do it to scale their people, not their systems. Even Martin Fowler's original blog post on Microservices recommends against it:

One reasonable argument we've heard is that you shouldn't start with a microservices architecture. Instead begin with a monolith, keep it modular, and split it into microservices once the monolith becomes a problem.

The Java ecosystem has some well-established patterns for developing microservice architectures. If you're familiar with Spring, you'll feel right at home developing with Spring Boot and Spring Cloud. Since that's one of the quickest ways to get started, I figured I'd walk you through a quick example.

This example contains a microservice with a REST API that returns a list of cool cars. It uses Netflix Eureka for service discovery, WebClient for remote communication, and Spring Cloud Gateway to route requests to the microservice. It integrates Spring Security and OAuth 2.0, so only authenticated users can access the API gateway and microservice. It also uses Resilience4j to add fault tolerance to the gateway.

Here is a diagram showing the overall infrastructure:

Create Java Microservices with Spring Boot and Spring Cloud

I like to show developers how to build everything from scratch. Today, I'm going to take a different approach. First, I'll show you how to get the completed example working. Then, I'll explain how I created everything and the trials and tribulations I encountered along the way.

You can start by cloning the @oktadev/auth0-java-microservices-examples repository.

git clone https://github.com/oktadev/auth0-java-microservices-examples

There are two directories in this repository that pertain to this tutorial:

spring-boot-gateway-webflux: a Spring Boot microservice architecture with Spring Cloud Gateway and Spring WebFlux.
spring-boot-gateway-mvc: a Spring Boot microservice architecture with Spring Cloud Gateway and Spring MVC.

Each directory contains three projects:

discovery-service: a Netflix Eureka server used for service discovery.
car-service: a simple Car Service that uses Spring Data REST to serve up a REST API of cars.
api-gateway: an API gateway with a /cool-cars endpoint that talks to the car service and filters out cars that aren't cool (in my opinion, of course).

The configuration for the WebFlux and MVC implementations is the same, so choose one and follow along.

You can also watch a demo of the WebFlux example in the screencast below.

Run a Secure Spring Boot Microservice Architecture

To run the example, you must install the Auth0 CLI and create an Auth0 account. If you don't have an Auth0 account, sign up for free. I recommend using SDKMAN! to install Java 17+ and HTTPie for making HTTP requests.

First, start the discovery service:

cd discovery-service
./gradlew bootRun

Before you can start the API gateway project, you'll need to configure the API gateway to use your Auth0 account.

Open a terminal and run auth0 login to configure the Auth0 CLI to get an API key for your tenant. Then, run auth0 apps create to register an OpenID Connect (OIDC) app with the appropriate URLs:

auth0 apps create \
  --name "Kick-Ass Cars" \
  --description "Microservices for Cool Cars" \
  --type regular \
  --callbacks http://localhost:8080/login/oauth2/code/okta \
  --logout-urls http://localhost:8080 \
  --reveal-secrets

Copy api-gateway/.env.example to .env and edit it to contain the values from the command above.

OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
OKTA_OAUTH2_CLIENT_ID=
OKTA_OAUTH2_CLIENT_SECRET=
OKTA_OAUTH2_AUDIENCE=https://<your-auth0-domain>/api/v2/

At startup, these properties will be read using spring-dotenv.

Run ./gradlew bootRun to start the API gateway, or use your IDE to run it.

Copy car-service/.env.example to .env and update its values.

OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
OKTA_OAUTH2_AUDIENCE=https://<your-auth0-domain>/api/v2/

Start it with ./gradlew bootRun and open http://localhost:8080 in your favorite browser. You'll be redirected to Auth0 to log in:

After authenticating, you'll see your name in lights! ✨

You can navigate to the following URLs in your browser for different results:

http://localhost:8080/print-token: prints access token to the terminal
http://localhost:8080/cool-cars: returns a list of cool cars
http://localhost:8080/home: proxies request to the car service and prints JWT claims in this application's terminal

You can see the access token's contents by copying/pasting it into jwt.io. You can also access the car service directly using it.

TOKEN=<access-token>
http :8090/cars Authorization:"Bearer $TOKEN"

Pretty cool, eh? 😎

My Developer Story with Spring Boot and Spring Cloud

A few years ago, I created an example similar to this one with Spring Boot 2.2. It used Feign for remote connectivity, Zuul for routing, Hystrix for failover, and Spring Security for OAuth. The September 2023 version of Spring Cloud has Spring Cloud OpenFeign for remote connectivity, Spring Cloud Gateway for routing, and Resilience4j for fault tolerance.

Okta also now has an Okta Spring Boot starter. I didn't use it in my first experiment, but I'm a big fan of it after the last few years! It dramatically simplifies configuration and makes securing your apps with OAuth 2.0 and OIDC easy. It's a thin wrapper around Spring Security's resource server, OAuth client, and OIDC features. Not only that, but it works with Okta Workforce Identity, Okta Customer Identity (aka Auth0), and even Keycloak.

I created all of these applications using start.spring.io's REST API and HTTPie.

https start.spring.io/starter.tgz bootVersion==3.2.0 \
  artifactId==discovery-service name==eureka-service \
  dependencies==cloud-eureka-server baseDir==discovery-service | tar -xzvf -

https start.spring.io/starter.tgz bootVersion==3.2.0 \
  artifactId==car-service name==car-service baseDir==car-service \
  dependencies==actuator,cloud-eureka,data-jpa,data-rest,postgresql,web,validation,devtools,docker-compose,okta | tar -xzvf -

https start.spring.io/starter.tgz bootVersion==3.2.0 \
  artifactId==api-gateway name==api-gateway baseDir==api-gateway \
  dependencies==cloud-eureka,cloud-feign,data-rest,web,okta | tar -xzvf -

You might notice the api-gateway project doesn't have cloud-gateway as a dependency. That's because I started without it and didn't add it until I needed to proxy requests by path.

In the code listings below, all package and import statements have been removed for brevity. You can find the complete source code in the auth0-java-microservices-examples repository.

Service Discovery with Netflix Eureka

The discovery-service is configured the same as you would most Eureka servers. It has an @EnableEurekaServer annotation on its main class and properties that set its port and turn off discovery.

server.port=8761
eureka.client.register-with-eureka=false
eureka.client.fetch-registry=false

The car-service and api-gateway projects are configured similarly. Both have a unique name defined, and car-service is configured to run on port 8090 so it doesn't conflict with 8080:

# car-service/src/main/resources/application.properties
server.port=8090
spring.application.name=car-service

# api-gateway/src/main/resources/application.properties
spring.application.name=api-gateway

@EnableDiscoveryClient annotates the main class in both car service and API gateway.

Build a Java Microservice with Spring Data REST

The car-service provides a REST API that lets you CRUD (Create, Read, Update, and Delete) cars. It creates a default set of cars when the application loads using an ApplicationRunner bean:

// car-service/src/main/java/com/example/carservice/CarServiceApplication.java
@EnableDiscoveryClient
@SpringBootApplication
public class CarServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(CarServiceApplication.class, args);
    }

    @Bean
    ApplicationRunner init(CarRepository repository) {
        repository.deleteAll();
        return args -> {
            Stream.of("Ferrari", "Jaguar", "Porsche", "Lamborghini", "Bugatti",
                "AMC Gremlin", "Triumph Stag", "Ford Pinto", "Yugo GV").forEach(name -> {
                repository.save(new Car(name));
            });
            repository.findAll().forEach(System.out::println);
        };
    }
}

The CarRepository interface makes persisting and fetching cars from the database easy:

// car-service/src/main/java/com/example/carservice/data/CarRepository.java
@RepositoryRestResource
public interface CarRepository extends JpaRepository<Car, Long> {
}

The Car class is a simple JPA entity with an id and name property. Spring Boot will see PostgreSQL on its classpath and autoconfigure connectivity. A compose.yaml file exists in the root directory to start a PostgreSQL instance using Docker Compose:

services:
  postgres:
    image: 'postgres:latest'
    environment:
      - 'POSTGRES_DB=mydatabase'
      - 'POSTGRES_PASSWORD=secret'
      - 'POSTGRES_USER=myuser'
    ports:
      - '5432'

Spring Boot added Docker Compose support in version 3.1. This means that if you add the following dependency to your build.gradle, it'll look for a compose.yaml (or docker-compose.yaml) file in the root directory and start it when you run ./gradlew bootRun:

developmentOnly 'org.springframework.boot:spring-boot-docker-compose'

Finally, the application.properties has a setting to create the database automatically:

spring.jpa.hibernate.ddl-auto=update

Connect to Java Microservices with Spring Cloud OpenFeign

Next, I configured OpenFeign in the api-gateway project to connect to the car service and its /cars endpoint. Then, I mapped a Car record to the JSON that's returned. I exposed it as a /cool-cars endpoint:

// api-gateway/src/main/java/com/example/apigateway/ApiGatewayApplication.java
@EnableFeignClients
@EnableDiscoveryClient
@SpringBootApplication
public class ApiGatewayApplication {

    public static void main(String[] args) {
        SpringApplication.run(ApiGatewayApplication.class, args);
    }
}

record Car(String name) {
}

@FeignClient("car-service")
interface CarClient {

    @GetMapping("/cars")
    CollectionModel<Car> readCars();
}

@RestController
class CoolCarController {

    private final CarClient carClient;

    public CoolCarController(CarClient carClient) {
        this.carClient = carClient;
    }

    @GetMapping("/cool-cars")
    public Collection<Car> coolCars() {
        return carClient.readCars()
                .getContent()
                .stream()
                .filter(this::isCool)
                .collect(Collectors.toList());
    }

    private boolean isCool(Car car) {
        return !car.name().equals("AMC Gremlin") &&
                !car.name().equals("Triumph Stag") &&
                !car.name().equals("Ford Pinto") &&
                !car.name().equals("Yugo GV");
    }
}

This worked great, but I still wanted to proxy /home to the downstream car service.

Add Routing with Spring Cloud Gateway

When I first wrote this tutorial with Spring Boot 3.1 and Spring Cloud 2022.0.4, Spring Cloud Gateway only had a WebFlux API. Since Spring Cloud 2023.0.0, it has a Spring MVC API too! This means you can use it with Spring MVC or Spring WebFlux.

Proxy Requests by Path with Spring MVC

I added spring-cloud-starter-gateway-mvc as a dependency to the api-gateway project and added the following to a new api-gateway/src/main/resources/application.yml file:

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
      mvc:
        routes:
          - id: car-service
            uri: lb://car-service
            predicates:
              - Path=/home/**

With this configuration, I could access the car service directly at http://localhost:8090/cars and through the gateway at http://localhost:8080/cool-cars.

To add failover with Spring Cloud Circuit Breaker, I added it as a dependency:

implementation 'org.springframework.cloud:spring-cloud-starter-circuitbreaker-resilience4j'

Then, I enabled it in application.properties:

spring.cloud.openfeign.circuitbreaker.enabled=true

I updated the CarClient interface in ApiGatewayApplication to have a fallback that returns an empty list of cars if the car service is unavailable.

@FeignClient(name = "car-service", fallback = Fallback.class)
interface CarClient {

    @GetMapping("/cars")
    CollectionModel<Car> readCars();

}

@Component
class Fallback implements CarClient {

    @Override
    public CollectionModel<Car> readCars() {
        return CollectionModel.empty();
    }
}

Proxy Requests by Path with WebFlux

Getting everything to work with Spring MVC and Spring Cloud Gateway didn't take long. Using Spring WebFlux required a bit more work.

I immediately discovered that adding spring-cloud-starter-gateway as a dependency caused issues. First, I had Spring MVC in my classpath, and Spring Cloud Gateway uses WebFlux. WebFlux recommends using WebClient over Feign. I decided to switch to WebClient.

I had to remove the following dependencies from my original api-gateway project:

implementation 'org.springframework.boot:spring-boot-starter-data-rest'
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.cloud:spring-cloud-starter-openfeign'

And add Spring Cloud Gateway with Resilience4j dependencies:

implementation 'org.springframework.cloud:spring-cloud-starter-circuitbreaker-reactor-resilience4j'
implementation 'org.springframework.cloud:spring-cloud-starter-gateway'

Then, I moved CoolCarController to its own class and re-implemented it with WebClient:

// api-gateway/src/main/java/com/example/apigateway/web/CoolCarController.java
@RestController
class CoolCarController {

    Logger log = LoggerFactory.getLogger(CoolCarController.class);

    private final WebClient.Builder webClientBuilder;
    private final ReactiveCircuitBreaker circuitBreaker;

    public CoolCarController(WebClient.Builder webClientBuilder,
                             ReactiveCircuitBreakerFactory circuitBreakerFactory) {
        this.webClientBuilder = webClientBuilder;
        this.circuitBreaker = circuitBreakerFactory.create("circuit-breaker");
    }

    record Car(String name) {
    }

    @GetMapping("/cool-cars")
    public Flux<Car> coolCars() {
        return circuitBreaker.run(
            webClientBuilder.build()
                .get().uri("http://car-service/cars")
                .retrieve().bodyToFlux(Car.class)
                .filter(this::isCool),
            throwable -> {
                log.warn("Error making request to car service", throwable);
                return Flux.empty();
            });
    }

    private boolean isCool(Car car) {
        return !car.name().equals("AMC Gremlin") &&
            !car.name().equals("Triumph Stag") &&
            !car.name().equals("Ford Pinto") &&
            !car.name().equals("Yugo GV");
    }
}

In order to inject the WebClient.Builder, I had to create a WebClientConfiguration class:

// api-gateway/src/main/java/com/example/apigateway/config/WebClientConfiguration.java
@Configuration
public class WebClientConfiguration {

    @Bean
    @LoadBalanced
    public WebClient.Builder webClientBuilder() {
        return WebClient.builder();
    }
}

In the car-service project, I had to switch from using Spring Data REST to handling it with a @RestController and @GetMapping annotation. I removed the @RepositoryRestResource annotation from CarRepository and added a CarController class:

// car-service/src/main/java/com/example/carservice/web/CarController.java
@RestController
class CarController {

    private final CarRepository repository;

    public CarController(CarRepository repository) {
        this.repository = repository;
    }

    @GetMapping("/cars")
    public List<Car> getCars() {
        return repository.findAll();
    }
}

NOTE: I did try to use Spring HATEOAS but ran into an issue when using it with the Okta Spring Boot starter.

To proxy /home to the downstream microservice, I added a api-gateway/src/main/resources/application.yml file to configure Spring Cloud Gateway to enable service discovery and specify routes:

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
      routes:
        - id: car-service
          uri: lb://car-service
          predicates:
            - Path=/home/**

At this point, I could access the car service directly at http://localhost:8090/cars and through the gateway at http://localhost:8080/cool-cars.

Secure Spring Boot Microservices with OAuth 2.0 and OIDC

To configure the Okta Spring Boot starter, there are a few properties in the api-gateway project's application.properties file:

okta.oauth2.issuer=${OKTA_OAUTH2_ISSUER}
okta.oauth2.client-id=${OKTA_OAUTH2_CLIENT_ID}
okta.oauth2.client-secret=${OKTA_OAUTH2_CLIENT_SECRET}
okta.oauth2.audience=${OKTA_OAUTH2_AUDIENCE}

The car-service is configured as an OAuth resource server and has the following properties in its application.properties file:

okta.oauth2.issuer=${OKTA_OAUTH2_ISSUER}
okta.oauth2.audience=${OKTA_OAUTH2_AUDIENCE}

The variables are read from the .env file in each project's root directory.

Fetch an Access Token as a JWT

When I first got things working, I was able to log in to the gateway, but when I tried to connect to the downstream microservice, it said the JWT was invalid. For this reason, I added a /print-token endpoint to the gateway that prints the access token to the console.

NOTE: The code in this section is for the WebFlux version. The MVC version is in the next section.

// api-gateway/src/main/java/com/example/apigateway/web/HomeController.java
@RestController
class HomeController {

    @GetMapping("/")
    public String howdy(@AuthenticationPrincipal OidcUser user) {
        return "Hello, " + user.getFullName();
    }

    @GetMapping("/print-token")
    public String printAccessToken(@RegisteredOAuth2AuthorizedClient("okta")
                                   OAuth2AuthorizedClient authorizedClient) {

        var accessToken = authorizedClient.getAccessToken();

        System.out.println("Access Token Value: " + accessToken.getTokenValue());
        System.out.println("Token Type: " + accessToken.getTokenType().getValue());
        System.out.println("Expires At: " + accessToken.getExpiresAt());

        return "Access token printed";
    }
}

Using jwt.io, I verified that it wasn't a valid JWT. I thought about trying to implement Spring Security's opaque token support, but discovered Auth0 doesn't have an /instropection endpoint. This makes it impossible to use opaque tokens with Auth0.

The good news is I figured out a workaround! If you pass a valid audience parameter to Auth0, you'll get a JWT for the access token. I logged an issue to improve the Okta Spring Boot starter and added a SecurityConfiguration class to solve the problem in the meantime.

// api-gateway/src/main/java/com/example/apigateway/config/SecurityConfiguration.java
@Configuration
public class SecurityConfiguration {

    @Value("${okta.oauth2.audience:}")
    private String audience;

    private final ReactiveClientRegistrationRepository clientRegistrationRepository;

    public SecurityConfiguration(ReactiveClientRegistrationRepository clientRegistrationRepository) {
        this.clientRegistrationRepository = clientRegistrationRepository;
    }

    @Bean
    public SecurityWebFilterChain filterChain(ServerHttpSecurity http) throws Exception {
        http
            .authorizeExchange(authz -> authz
                .anyExchange().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .authorizationRequestResolver(
                    authorizationRequestResolver(this.clientRegistrationRepository)
                )
            );
        return http.build();
    }

    private ServerOAuth2AuthorizationRequestResolver authorizationRequestResolver(
        ReactiveClientRegistrationRepository clientRegistrationRepository) {

        var authorizationRequestResolver =
            new DefaultServerOAuth2AuthorizationRequestResolver(clientRegistrationRepository);
        authorizationRequestResolver.setAuthorizationRequestCustomizer(
            authorizationRequestCustomizer());

        return authorizationRequestResolver;
    }

    private Consumer<OAuth2AuthorizationRequest.Builder> authorizationRequestCustomizer() {
        return customizer -> customizer
            .additionalParameters(params -> params.put("audience", audience));
    }
}

To make Spring Cloud Gateway pass the access token downstream, I added TokenRelay to its default filters in application.yml:

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
      default-filters:
        - TokenRelay
      routes: ...

I updated the WebClientConfiguration class to configure WebClient to include the access token with its requests:

// api-gateway/src/main/java/com/example/apigateway/config/WebClientConfiguration.java
@Configuration
public class WebClientConfiguration {

    @Bean
    @LoadBalanced
    public WebClient.Builder webClientBuilder(ReactiveClientRegistrationRepository clientRegistrations,
                                              ServerOAuth2AuthorizedClientRepository authorizedClients) {
        var oauth = new ServerOAuth2AuthorizedClientExchangeFilterFunction(clientRegistrations, authorizedClients);
        oauth.setDefaultClientRegistrationId("okta");
        return WebClient
            .builder()
            .filter(oauth);
    }

}

Spring Cloud Gateway MVC and OAuth 2.0

To get the Spring Cloud Gateway MVC example working with OAuth 2.0, I had to add a SecurityConfiguration class to pass an audience parameter to Auth0:

// api-gateway/src/main/java/com/example/apigateway/config/SecurityConfiguration.java
@Configuration
public class SecurityConfiguration {

    @Value("${okta.oauth2.audience:}")
    private String audience;

    private final ClientRegistrationRepository clientRegistrationRepository;

    public SecurityConfiguration(ClientRegistrationRepository clientRegistrationRepository) {
        this.clientRegistrationRepository = clientRegistrationRepository;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .authorizationEndpoint(authorization -> authorization
                    .authorizationRequestResolver(
                        authorizationRequestResolver(this.clientRegistrationRepository)
                    )
                )
            );
        return http.build();
    }

    private OAuth2AuthorizationRequestResolver authorizationRequestResolver(
        ClientRegistrationRepository clientRegistrationRepository) {

        DefaultOAuth2AuthorizationRequestResolver authorizationRequestResolver =
            new DefaultOAuth2AuthorizationRequestResolver(
                clientRegistrationRepository, "/oauth2/authorization");
        authorizationRequestResolver.setAuthorizationRequestCustomizer(
            authorizationRequestCustomizer());

        return authorizationRequestResolver;
    }

    private Consumer<OAuth2AuthorizationRequest.Builder> authorizationRequestCustomizer() {
        return customizer -> customizer
            .additionalParameters(params -> params.put("audience", audience));
    }
}

Spring Cloud Gateway MVC 2023.0.0 doesn't allow you to configure a TokenRelay filter in YAML, so I added a RouterFunction bean to add it.

// api-gateway/src/main/java/com/example/apigateway/ApiGatewayApplication.java
public class ApiGatewayApplication {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsLoadBalancer() {
        return route("car-service")
            .route(path("/home/**"), http())
            .filter(lb("car-service"))
            .filter(tokenRelay())
            .build();
    }

    public static void main(String[] args) {
        SpringApplication.run(ApiGatewayApplication.class, args);
    }
}

Thanks for the help with this code, Spencer Gibb! 🙌

The updated application.yml file looks as follows after removing its mvc configuration.

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true

The last thing I needed to configure was OAuth integration for OpenFeign. I added the following properties to application.properties:

spring.cloud.openfeign.oauth2.enabled=true
spring.cloud.openfeign.oauth2.clientRegistrationId=okta

I removed the spring.cloud.openfeign.circuitbreaker.enabled property because I could not get it to work with Spring MVC. If you know how to make it work, please let me know in the comments!

Spring Boot Microservices and Refresh Tokens

In my previous Spring Boot 2.2 example, I couldn't get refresh tokens to work. I was able to get them to work this time! I changed the default scopes in api-gateway to request a refresh token using the offline_access scope:

# .env
OKTA_OAUTH2_AUDIENCE=https://fast-expiring-api
OKTA_OAUTH2_SCOPES=openid,profile,email,offline_access

And added a property to application.properties to read it:

# src/main/resources/application.properties
okta.oauth2.scopes=${OKTA_OAUTH2_SCOPES}

Then, I created an API in Auth0 called fast-expiring-api and set it to expire in 30 seconds:

auth0 apis create --name fast-expiring --identifier https://fast-expiring-api \
  --token-lifetime 30 --offline-access --no-input

If you do the same, you can restart the API gateway and go to http://localhost:8080/print-token to see your access token. You can copy the expired time to timestamp-converter.com to see when it expires in your local timezone. Wait 30 seconds and refresh the page. You'll see a request for a new token and an updated Expires At timestamp in your terminal.

The Okta Spring Boot starter and Keycloak

If you find yourself in a situation where you don't have an internet connection, it can be handy to run Keycloak locally in a Docker container. Since the Okta Spring Boot starter is a thin wrapper around Spring Security, it works with Keycloak, too.

In my experience, Spring Security's OAuth support works with any OAuth 2.0-compliant server. The Okta Spring Boot starter does validate the issuer to ensure it's an Okta URL, so you must use Spring Security's properties instead of the okta.oauth2.* properties when using Keycloak.

An easy way to get a pre-configured Keycloak instance is to use JHipster's jhipster-sample-app-oauth2 application. It gets updated with every JHipster release. You can clone it with the following command:

git clone https://github.com/jhipster/jhipster-sample-app-oauth2.git --depth=1
cd jhipster-sample-app-oauth2

Then, start its Keycloak instance:

docker compose -f src/main/docker/keycloak.yml up -d

You can configure the api-gateway to use Keycloak by removing the okta.oauth2.* properties and using Spring Security's in application.properties:

spring.security.oauth2.client.provider.okta.issuer-uri=http://localhost:9080/realms/jhipster
spring.security.oauth2.client.registration.okta.client-id=web_app
spring.security.oauth2.client.registration.okta.client-secret=web_app
spring.security.oauth2.client.registration.okta.scope=openid,profile,email,offline_access

The car-service requires similar changes in its application.properties file:

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9080/realms/jhipster
spring.security.oauth2.resourceserver.jwt.audiences=account

Restart both apps, open http://localhost:8080, and you'll be able to log in with Keycloak:

Use admin/admin for credentials, and you can access http://localhost:8080/cool-cars as you did before:

Stay secure with Spring Boot and Spring Cloud!

I hope you liked this tour of how to build Java microservice architectures with Spring Boot and Spring Cloud. You learned how to build everything with minimal code and then configure it to be secure with Spring Security, OAuth 2.0, OIDC, and Auth0 by Okta.

You can find all the code shown in this tutorial on GitHub in the @oktadev/auth0-java-microservices-examples repository. The OpenFeign example with Spring MVC is in the spring-boot-gateway-mvc directory. The Spring Cloud Gateway with WebFlux is in spring-boot-gateway-webflux. The Keycloak example is in the keycloak branch.

If you liked this post, you might enjoy these related posts:

We've also published some new labs about securing Spring Boot in our Developer Center. They're great if you like to learn by doing!

Please follow us on Twitter @oktadev and subscribe to our YouTube channel for more Spring Boot and microservices knowledge.

You can also sign up for our developer newsletter to stay updated on everything Identity and Security.

A Passwordless Future: Passkeys for Java Developers

Deepu K Sasidharan — Tue, 02 Jan 2024 15:39:21 +0000

Originally published at auth0.com

This blog post is a continuation of my previous blog post on passkeys. In this post, you will learn how to implement passkeys using Auth0 and the WebAuthn4j library on your Java applications.

A Passwordless Future: Passkeys for Developers

Deepu K Sasidharan for Okta ・ Feb 16

#security #passkeys #webauthn

If you have not read the previous blog post, I would highly recommend you read it first to understand the basics of passkeys and WebAuthn.

Passkeys

A passkey is a unique cryptographic key pair that allows you to access online services without using passwords. It is based on asymmetric public-key cryptography.

Passkeys are passwordless FIDO credentials implemented using WebAuthn.

Why Passkeys?

Let's See Passkeys in Action with Auth0

Let's build a Spring Boot web app and secure it using passkeys with the help of Auth0 by Okta. You can find a sample app on GitHub if you just want to try passkeys.

Before you get started, you will need the following:

Java 17 or higher. You can use SDKMAN! to install Java if you don't have it already.
A free Auth0 account. Sign up if you don't have one already.
The Auth0 CLI. Install the CLI if you don't have it and log in to your Auth0 account using the auth0 login command.

Create a Spring Boot application

Create a new Spring Boot application using the Spring Initializr. You can use the web version or the curl command below. Use the default for most of the options. For the dependencies, select web, and okta. For the build tool, select Gradle.

curl -G https://start.spring.io/starter.tgz \
  -d dependencies=web,okta \
  -d baseDir=passkey-demo \
 | tar -xzvf -

The web dependency provides Spring Web MVC with basic HTTP REST functionality.
The okta dependency provides the Okta Spring Boot Starter, which provides the required dependencies and configuration to add OIDC authentication to your application.

Add a web controller

Imports are omitted for brevity so make sure to import them using your IDE.

Open the created starter application in your favorite IDE. Add a simple web controller to the application. Create a new file src/main/java/com/example/demo/HomeController.java with the following content:

@RestController
class HomeController {
    @GetMapping("/")
    public String home(@AuthenticationPrincipal OidcUser user) {
        return "Hello, " + user.getFullName() + "!";
    }
}

This controller will handle requests to the / path.

If you run the application using ./gradlew bootRun, you will see a login page from the Okta Spring Boot starter instead of your home screen. This is OK, and you will be able to configure this soon. You can comment out the okta-spring-boot-starter dependency in the build.gradle file if you want to run the application at this point.

Enable passkeys on your Auth0 tenant

Log in to your Auth0 Dashboard and navigate to Authentication > Database > Username-Password-Authentication.
1. If the second tab says Authentication Methods, your tenant supports passkeys, proceed to the next step.
2. If the second tab says Password Policy, your tenant doesn't support passkeys, Create a new tenant and proceed to the next step.
Navigate to Authentication > Authentication Profile and select Identifier First. Save your changes.
Navigate to Authentication > Database > Username-Password-Authentication and select the Authentication Methods tab and enable Passkey.

Configure OIDC Authentication with Auth0

Configure the application to use Auth0 as the Identity Provider (IdP). You can use the Auth0 CLI to create a new authorization server application. Run the following command to create a new application:

auth0 apps create \
  --name "Spring Boot Passkeys" \
  --description "Spring Boot Example" \
  --type regular \
  --callbacks http://localhost:8080/login/oauth2/code/okta \
  --logout-urls http://localhost:8080 \
  --reveal-secrets

The --type option specifies that you use a regular web application.
The --callbacks option specifies the callback URL for the application.
The --logout-urls option specifies the logout URL for the application.
The --reveal-secrets option will display the client secret in the output.

You can also use the auth0 apps update command to update the application with the callback and logout URLs.

Note down the Auth0 issuer (for example, https://dev-12345678.us.auth0.com/), CLIENT ID, and CLIENT SECRET from the output. You will use these values in the next step.

Configure the Spring Boot application

Configure the application by creating an application.properties file in the applications root folder with the following content:

# trailing `/` is important for issuer URI
okta.oauth2.issuer=https://<AUTH0_domain>/
okta.oauth2.client-id=<AUTH0_clientId>
okta.oauth2.client-secret=<AUTH0_clientSecret>

Add the application.properties file to the .gitignore file to avoid committing the secrets to the repository.

Run the application

To run the application, execute the following command:

./gradlew bootRun

The application should start successfully. Navigate to http://localhost:8080 in your browser. You will be redirected to the Auth0 universal login page for authentication.

Click on the Sign up link to register a new user. Enter any email address and click Continue. You will now be prompted to register a passkey.

Create a passkey using your platform authenticator or roaming authenticator like YubiKey. Once you have registered a passkey, you should be redirected back to the application and see the welcome message.

Open a new incognito window and navigate to http://localhost:8080. You will be prompted to sign in using your passkey. Once you have signed in, you will see the welcome message.

Isn't that cool? You just implemented passkeys in your Spring Boot application with so little effort thanks to Auth0.

WebAuthn for Java

Though Web Authentication’s user experience is a client-side implementation using JavaScript, the backend or Relying party can be a Java server. Ideally using an IdP like Auth0 would be the best option since it takes care of all the heavy lifting for you. But if you want to implement it yourself and walk the harder path, you can use one of the below libraries.

WebAuthn4j: A 100% FIDO2 conformant library with support for all attestation formats and validation. It is used by Keycloak and Spring Security.
java-webauthn-server: A library from Yubico that supports many attestation format. But it is not 100% FIDO2 conformant.

WebAuthn4j with Spring Security in Action

Let's look at a simple Spring Boot application that uses passkeys for authentication without using an IdP. You can find the sample app on GitHub.

Clone and run the application

Start by cloning the application.

git clone https://github.com/deepu105/webauthn4j-spring-boot-passkeys-demo.git

cd webauthn4j-spring-boot-passkeys-demo
./gradlew bootRun

Visit http://localhost:8080/. You should see the below screen. Try registering a new user with passkeys and log in.

WebAuthn4j configuration

Let's look at some of the important parts of the application.

The webauthn4j-spring-security-core dependency, in build.gradle file, provides the Spring Security integration for WebAuthn4j.
The required beans for WebAuthn4j are configured in src/main/java/com/example/demo/config/WebSecurityBeanConfig.java.
The InMemoryWebAuthnAuthenticatorManager is used to keep things simple but it means authenticator data is lost on application restart. For production use, it is better to implement the WebAuthnAuthenticatorManager interface and persist credential IDs for users.
WebAuthn4j is configured using the standard Spring Security filter chain in src/main/java/com/example/demo/config/WebSecurityConfig.java.

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {
    ...
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
        // WebAuthn Login
        http.apply(WebAuthnLoginConfigurer.webAuthnLogin())
            .defaultSuccessUrl("/", true)
            .failureHandler((request, response, exception) -> {
                logger.error("Login error", exception);
                response.sendRedirect("/login?error=Login failed: " + exception.getMessage());
            })
            .attestationOptionsEndpoint()
            .rp()
            .name("WebAuthn4J Passkeys Demo")
            .and()
            .pubKeyCredParams(
                // supported algorithms for cryptography
                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256),
                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS256)
            )
            .attestation(AttestationConveyancePreference.DIRECT)
            .extensions()
            .uvm(true)
            .credProps(true)
            .extensionProviders()
            .and()
            .assertionOptionsEndpoint()
            .extensions()
            .extensionProviders();

        http.headers(headers -> {
            // 'publickey-credentials-get *' allows getting WebAuthn credentials to all nested browsing contexts (iframes) regardless of their origin.
            headers.permissionsPolicy(config -> config.policy("publickey-credentials-get *"));
            // Disable "X-Frame-Options" to allow cross-origin iframe access
            headers.frameOptions(Customizer.withDefaults()).disable();
        });

        // Authorization
        http.authorizeHttpRequests(authz -> authz
            .requestMatchers(HttpMethod.GET, "/login").permitAll()
            .requestMatchers(HttpMethod.POST, "/signup").permitAll()
            .anyRequest().access(getWebExpressionAuthorizationManager("@webAuthnSecurityExpression.isWebAuthnAuthenticated(authentication)"))
        );

        http.exceptionHandling(eh -> eh.accessDeniedHandler((request, response, accessDeniedException) -> {
            logger.error("Access denied", accessDeniedException);
            response.sendRedirect("/login");
        }));

        http.authenticationManager(authenticationManager);

        // As WebAuthn has its own CSRF protection mechanism (challenge), CSRF token is disabled here
        http.csrf(csrf -> {
            csrf.csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse());
            csrf.ignoringRequestMatchers("/webauthn/**");
        });

        return http.build();
    }
    ...
}

The endpoints are configured in src/main/java/com/example/demo/web/WebAuthnSampleController.java. The / and /login endpoints are quite simple and self-explanatory. The /signup endpoint handles the WebAuthn registration request using WebAuthn4j. The request is first validated using WebAuthnRegistrationRequestValidator and then the authenticator is created using WebAuthnAuthenticatorManager.

@Controller
public class WebAuthnSampleController {
    ...
    @PostMapping(value = "/signup")
    public String create(HttpServletRequest request, @Valid @ModelAttribute("userForm") UserCreateForm userCreateForm, BindingResult result, Model model, RedirectAttributes redirectAttributes) {
        try {
            if (result.hasErrors()) {
                model.addAttribute("errorMessage", "Your input needs correction.");
                logger.error("User input validation failed.");
                return VIEW_LOGIN;
            }
            WebAuthnRegistrationRequestValidationResponse registrationRequestValidationResponse;
            try {
                registrationRequestValidationResponse = registrationRequestValidator.validate(
                    request,
                    userCreateForm.getClientDataJSON(),
                    userCreateForm.getAttestationObject(),
                    userCreateForm.getTransports(),
                    userCreateForm.getClientExtensions()
                );
            } catch (WebAuthnException | WebAuthnAuthenticationException e) {
                model.addAttribute("errorMessage", "Authenticator registration request validation failed. Please try again.");
                logger.error("WebAuthn registration request validation failed.", e);
                return VIEW_LOGIN;
            }
            var username = userCreateForm.getUsername();
            var authenticator = new WebAuthnAuthenticatorImpl(
                "authenticator",
                username,
                registrationRequestValidationResponse.getAttestationObject().getAuthenticatorData().getAttestedCredentialData(),
                registrationRequestValidationResponse.getAttestationObject().getAttestationStatement(),
                registrationRequestValidationResponse.getAttestationObject().getAuthenticatorData().getSignCount(),
                registrationRequestValidationResponse.getTransports(),
                registrationRequestValidationResponse.getRegistrationExtensionsClientOutputs(),
                registrationRequestValidationResponse.getAttestationObject().getAuthenticatorData().getExtensions()
            );
            try {
                webAuthnAuthenticatorManager.createAuthenticator(authenticator);
            } catch (IllegalArgumentException ex) {
                model.addAttribute("errorMessage", "Registration failed. The user may already be registered.");
                logger.error("Registration failed.", ex);
                return VIEW_LOGIN;
            }
        } catch (RuntimeException ex) {
            model.addAttribute("errorMessage", "Registration failed by unexpected error.");
            logger.error("Registration failed.", ex);
            return VIEW_LOGIN;
        }
        model.addAttribute("successMessage", "User registration successful. Please login.");
        return VIEW_LOGIN;
    }
}

Client-side configuration

The file src/main/resources/templates/login.html handles login and sign-up. The login button will invoke the navigator.credentials.get() API and the register button will invoke the navigator.credentials.create() API. The buttons submit the corresponding forms with the input data in them. All inputs except the username field are hidden as their data will be set using JavaScript.

WebAuthn4j exposes /webauthn/attestation/options endpoint in the application to fetch the registration options. Some of the option parameters need to be decoded from base64URL. The base64url-arraybuffer library is used for this. The options are then passed to the navigator.credentials.create() API. The response from the API is then updated to the form fields and submitted to the /signup endpoint.

document.getElementById('signup-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    const userHandle = document.getElementById('userHandle').value;
    const username = document.getElementById('username').value;
    try {
        const optionsRes = await fetch('/webauthn/attestation/options');
        const options = await optionsRes.json();
        const publicKey = {
            ...options,
            challenge: base64url.decode(options.challenge, true),
            user: {
                id: base64url.decode(userHandle, true),
                name: username,
                displayName: username,
            },
            excludeCredentials: options.excludeCredentials.map((credential) => ({
                ...credential,
                id: base64url.decode(credential.id, true),
            })),
            authenticatorSelection: {
                requireResidentKey: true,
                userVerification: 'discouraged',
            },
        };
        const credential = await navigator.credentials.create({ publicKey });
        document.getElementById('clientDataJSON').value = base64url.encode(credential.response.clientDataJSON);
        document.getElementById('attestationObject').value = base64url.encode(credential.response.attestationObject);
        document.getElementById('clientExtensions').value = JSON.stringify(credential.getClientExtensionResults());
        document.getElementById('signup-form').submit();
    } catch (error) {
        console.error('Error:%s, Message:%s', error.name, error.message);
    }
});

WebAuthn4j exposes /webauthn/assertion/options endpoint in the application to fetch the authentication options. Some of the option parameters need to be decoded from base64URL. The options are then passed to the navigator.credentials.get() API. The response from the API is then updated to the form fields and submitted to the /login endpoint.

document.getElementById('login-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    try {
        const optionsRes = await fetch('/webauthn/assertion/options');
        const options = await optionsRes.json();
        const publicKey = {
            ...options,
            challenge: base64url.decode(options.challenge, true),
            userVerification: 'preferred',
        };
        const credential = await navigator.credentials.get({ publicKey });
        document.getElementById('credentialId').value = credential.id;
        document.getElementById('loginClientDataJSON').value = base64url.encode(credential.response.clientDataJSON);
        document.getElementById('authenticatorData').value = base64url.encode(credential.response.authenticatorData);
        document.getElementById('signature').value = base64url.encode(credential.response.signature);
        document.getElementById('loginClientExtensions').value = JSON.stringify(credential.getClientExtensionResults());
        document.getElementById('login-form').submit();
    } catch (error) {
        console.error('Error:%s, Message:%s', error.name, error.message);
    }
});

Conclusion

You have now learned:

How to implement passkeys using an IdP like Auth0.
You also learned how to configure the application to use Auth0 as the Identity Provider and how to configure Auth0 for passkey support.
Roll your own passkey solution using WebAuthn4j and Spring Security.

Passkeys are the future of authentication. They are more secure and convenient than traditional passwords and OTPs. Though you could roll your own solution using WebAuthn4j, it is always better to use an IdP like Auth0 to handle the heavy lifting for you and take care of all the security best practices.

Resources

I hope that you found this article helpful. Here are some additional resources to learn more about WebAuthn and passkeys.

If you like this article, please leave a like or a comment.

You can follow me on Mastodon and LinkedIn.

Tips on migrating from Flask to FastAPI and vice-versa

Jessica Temporal — Fri, 15 Dec 2023 00:00:00 +0000

Are you migrating from Flask to FastAPI and facing problems? In this blog post, you will learn about some of the issues that you may encounter when migrating a web application from Flask to FastAPI, as well as how to solve them.

The web app that started it all

As a developer advocate at Auth0, I build sample applications that can be used to showcase our product. For example, I used a sample app built with Flask, Jinja, and Auth0 to build a demo for sponsored booths. This demo application showcases how Flask and Auth0 can be used together to develop web applications.

This app is a typical web app, consisting of a backend built in Flask, a frontend made with Jinja templates, and some CSS. It is secured with Auth0 to simplify the authentication and authorization processes.

While writing some code to answer a question from a developer a thought popped into my mind: “Since Auth0 can be used with any framework, why not create a version of the sample app using FastAPI in the backend instead of Flask?”

Thinking of the work that I do, I could use the new version built with FastAPI to write a guide that would help developers understand how to protect their applications built in FastAPI using Auth0. So I decided to use the sample built in Flask and migrate things over to a FastAPI-powered app. To make things easier on me, my plan was:

Reuse as much as possible of the original app built with Flask:
1. Copy templates and styling as well as any JavaScript.
Adjust anything necessary for the Flask code to work the “FastAPI way”.

That was a simple plan. Only two steps. “How hard could it be?” I know, I know, famous last words. So once I started migrating things over, I realized there were a few things that I would need to adjust for the app in FastAPI to function properly.

Below you can see what you’ll also need to adjust if you have a similar application you want to migrate over from Flask to FastAPI.

Disclaimer : Since the authentication guide in FastAPI is not public yet, I have created two sample applications with all the code shown in the examples of this blog post. If you are interested in reviewing the code, both applications are available on GitHub. You can follow the links below:

Templates

Both Flask and FastAPI support templating using Jinja, but there are a few differences.

Flask will automatically identify templates in your project so you can use the render_template method and Flask will look for the template in your project folder. You can even have two formats: either as a module where the template is on your root folder or as a package where the template lives inside your application folder.

As long as you use a templates/ folder Flask will automatically pick up on it. This will only vary if you are using Blueprints because you will need to pass the path for the templates to the blueprint you create.

FastAPI on the other hand, not only you do have to make sure to install Jinja2 on your environment, but you also need to tell FastAPI where to find the templates. With that said you can put the templates folder anywhere, but you’ll need to instantiate a templates variable for FastAPI to pick up on it like so:

from fastapi.templating import Jinja2Templates

templates = Jinja2Templates(directory="templates")

After that, you can use that variable to render the template for a given endpoint like this:

@app.get("/")
def home(request: Request):
    """
    Home endpoint
    """
    return templates.TemplateResponse("home.html")

Jinja Filters

Filters in Jinja serve as a way to modify variables. In this sample app, we created a filter to_pretty_json to “pretty print” a JSON object into the /profile endpoint. Even though the function is the same on both projects, the way to pass it along to the templates is a little bit different in each framework.

Note: you are going to notice that both frameworks will work similarly but the property names will be different.

Since Flask automatically picks up the templates, the Flask instance has a property called jinja_env that corresponds to the Jinja environment and that you can edit using the filters dictionary to register new filter like so:

app.jinja_env.filters['to_pretty_json'] = to_pretty_json

You can also use the template filter decorator.

Since in FastAPI you had to instantiate the templates variable, you’ll also use that variable to pass along the new filter. The templates variable has the env property allowing you to access the filters dictionary as you can see below:

templates.env.filters['to_pretty_json'] = to_pretty_json

Static files folder

Much like templates, both Flask and FastAPI, allow you to bundle the static files (CSS, JavaScript, and images) under the same folder, but once again there are a few differences.

Flask supports static files out of the gate with no configuration needed, you only need to add the static/ folder to your project, and that’s it, you don’t need any extra configuration to access static files from your templates.

For FastAPI, much like the template folder, you need to set the location of the static file by using the mount property, which is also known as “mounting” the static files, and the StaticFiles class to instantiate the directory.

from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount(
    "/static",
    StaticFiles(directory="static"),
    name="static"
)

Note that this way of creating the static files folder within the app creates an independent application and won’t be picked up by the OpenAPI or the docs but you’ll still be able to use things like the url_for function on your templates.

Using url_for function on the templates

Both templates on Flask and FastAPI will allow you to programmatically define URLs for files and endpoints using the url_for function, but as you can expect the parameters differ on each framework.

For example, in Flask, to add the style sheet on your base.html, you pass along the folder name static followed by the parameter named filename containing the name of your CSS file.

<link href="{{ url_for('static', filename='style.css') }}" rel="stylesheet" />

For FastAPI the functionality of the url_for function will be the same, but the parameter for the filename is called path:

<link href="{{ url_for('static', path='style.css') }}" rel="stylesheet" />

Sessions

For web applications, you usually have a way to manage sessions. Below you can see how you can interact with a session in each framework. The example will show how to clear a session when logging out.

In Flask, you can access the session from the session object that can be imported from the flask module as you can see below:

from flask import session

# ... blueprint definition

@auth_bp.route("/logout")
def logout():
    """
    Logs the user out of the session
    """
    session.clear()
    # ... rest of your logout code

Meanwhile, in FastAPI the session is part of the Request object, you can access it by passing the request as part of the endpoint function, and then using it request.session, like so:

from fastapi import Request

# ... router definition

@auth_router.get("/logout")
def logout(request: Request):
    """
    Logs the user out of the session
    """
    request.session.clear()
    # ... rest of your logout code

Modular applications: Blueprint and APIRouter

For more complex applications, which usually include multiple modules inside of an app, you’ll need to use a router so you can have some separation between responsibilities. For this, you will have a Blueprint in Flask and an APIRouter in FastAPI.

After creating the Blueprint or APIRouter you’ll need to register them with your app. Here’s what that looks like for both frameworks.

The Blueprint will need some more configuration like the name of that blueprint (’webapp’) as well as the import name (__name__) and any other configuration necessary, in this example, we passed along the template folder for the webapp:

from flask import Flask, Blueprint

webapp_bp = Blueprint(
    'webapp', __name__ , template_folder="templates"
)

app = Flask( __name__ )

Once the blueprint is created you can register it to your app. This helps make available any views/routes within your blueprint for your application. The registration occurs by calling the register_blueprint method from your app, and passing along the blueprint like so:

from flask import Flask

app = Flask( __name__ )

app.register_blueprint(webapp_bp, url_prefix='/')

For FastAPI the APIRouter will function similarly to the Blueprint in Flask, the difference is that you don’t need to pass any names, take a look:

from fastapi import APIRouter

webapp_router = APIRouter()

Then to register the router you can use the method include_router from your FastAPI app, and pass along the webapp_router like this:

from fastapi import FastAPI

app = FastAPI()

app.include_router(webapp_router)

Using url_for in the endpoints

Other than in templates, you can use the url_for in an endpoint to programmatically define the path for a given endpoint/route.

For using url_for in Flask you gotta import the function from the flask library and then pass the name of the endpoint. If your endpoint is in another module, remember to pass along the name of that module as well like so:

from flask import redirect, url_for

# ... blueprint definition

@auth_bp.route("/logout")
def logout():
    # ... your code
    return redirect(url_for("webapp.home")

Meanwhile, in FastAPI the url_for is a method and comes from the Request class. You need to pass along the endpoint name, if that endpoint is part of your app, even if it is in another module, everything will work from there and there’s no need to pass the module name as well.

from fastapi import Request
from fastapi import RedirectResponse

# ... router definition

@auth_router.get("/logout")
def logout(request: Request):
    # ... your logout code
    return RedirectResponse(url=request.url_for("home"))

Recap

Migrating frameworks in an application can be a daunting task especially if you don’t know where things might go wrong after copying and pasting code. But if you know where things will differ the migration will go much more smoothly.

Here’s a short version of the things to keep an eye out for if you are going to migrate from Flask to FastAPI and vice-versa:

Flask will pick up templates automatically, but FastAPI needs to be told where to find the templates using the Jinja2Templates class and passing along the templates directory.
Flask will use the render_template function to render pages, whereas FastAPI will use TemplateResponse which comes from Jinja2Templates class.
To create new filters in Flask you use the jinja_env property, FastAPI will use the env property.
Flask will pick up the static folder automatically, for FastAPI you need to “mount” the folder and use the StaticFiles class.
Sessions are handled differently, for Flask there’s a session object, for FastAPI the session object is part of the Request class.
For more complex applications you use Blueprint in Flask to define new routes whereas in FastAPI you’ll have a similar structure called APIRouter. Remember to register your blueprint or your router with your app.
Finally, remember to use the url_for function with the correct parameter filename for Flask and path for FastAPI, and that in your endpoints url_for exists as a standalone function in Flask whereas it is a method from the Request class in FastAPI.

In case you want to see apps in each framework and compare the differences for yourself here are the repositories on GitHub:

Finally, if you went through a similar process what other problems did you face and how did you solve them? I’d love to know more about your experience, send me a message on any of my social profiles.

From Zero to Hero: Identity Edition

Carla Urrea Stabile — Thu, 14 Dec 2023 17:24:58 +0000

Identity is a broad topic, and many resources are available. This blog post gives you a curated list of some of the most relevant resources at Auth0 by Okta and relevant identity organizations.

Identity Fundamentals

A digital identity is a set of attributes that define a particular user in the context of a function that is delivered by a specific application.

Learn it from Vittorio

Identity Fundamentals Course brought to you by the one and only Vittorio Bertocci.

IAM, CIAM, Am I?

Identity and Access Management provides control over user validation and resource access and it's commonly known as IAM.
Customer Identity and Access Management (CIAM) how companies give their end users access to their digital properties as well as how they govern, collect, analyze, and securely store data for those users.

No Time? Learn Identity In a Minute

Identity In a Minute Series is an ongoing series of 60-second shorts that describe key concepts in modern identity management, authentication and authorization.

More Time? Learn Directly from Identity Experts

Identity Unlocked Podcast: "Identity, Unlocked" is the podcast that discusses identity specs and trends from a developer perspective.
Authorization in Software Podcast: "Authorization in Software" features chats with industry subject matter experts in authorization.

Authentication

In authentication, a user or application proves that they are who they say they are by providing valid credentials.

There are many ways of authentication, though. 🤔 Learn about the most common ones:

Authorization

Authorization is the process of giving someone the ability to access a resource.

People usually mix up Authentication and Authorization because usually authentication leads to authorization, but authorization does not always lead to authentication.

Learn more about authorization and the different types: 👇

2FA, MFA all-the-FA

There are many options you can use to prove your digital identity. These are called authentication factors, and there are three main types:

knowledge or something that you know like a password,
possession or something that you have like a device
inherence which is something that you are or is inherent to you.

Usually, your application requires only one authentication factor to authenticate a user, typically a password. In some contexts, you may want more assurance about the user's identity. In that case, you can require two or more authentication factors. That's what two-factor authentication (2FA) and multi-factor authentication (MFA) are all about.

Learn more about 2FA and MFA 👇:

OAuth2, OIDC, Oh-what?

There are many standards used for identity. Some of the most relevant are OAuth2 and OIDC. OAuth 2.0, which stands for "Open Authorization", is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user. At the same time, Open ID Connect (OIDC) is an authentication protocol that utilizes the authorization and authentication mechanisms of OAuth 2.0.

But what else is out there? Learn more here 👇

OAuth 2.0 Simplified
OAuth 2.0 and OpenID Connect (in plain English)
OAuth in Five Minutes
An Illustrated Guide to OAuth and OpenID Connect
OIDC Playground
SAML Authentication: you can also use samltool.io's playground to learn more

Tokens, tokens, and more tokens!

A token is a piece of data that has no meaning or use on its own, but combined with the correct tokenization system, becomes a vital player in securing your application. There are different tokens, but what does each one do? how do you use them?

WebAuthn

WebAuthn is a W3C recommendation for defining an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications to authenticate users strongly. Here are some great resources to learn more:

Passkeys

Passkeys are password replacements that provide a faster, easier, and more secure user login experience that leverages WebAuthn under the hood. Learn more about passkeys:

Next.JS in a Nutshell: Rendering

Ceora Ford — Tue, 05 Dec 2023 16:58:00 +0000

Next.JS is one of the most popular modern React frameworks out there. I’ve spent the past few months building with Next.JS and learning the ins and outs of the language. Next.JS caught my eye initially because it offers a more seamless experience by abstracting away some of the tedious tasks that come with working with React like bundling and compiling. These are the things that usually make me want to pull my hair out so I had to try out Next.JS when I discovered that these things are automatically configured for you.

As I’ve been building, I’ve learned a lot along the way and I wanted to wrap my findings up into a blog post series that will cover a few things:

Core concepts in Next.JS
- Server side rendering vs Client side rendering
- Pages Router vs App router
What to do after learning the basics
Helpful resources

This post will specifically focus on rendering. We’ll cover routing and next steps in the future posts. My goal is to give you an introduction to Next.JS and a place to start so you can move forward and learn more on your own! I’m also happy to write more articles on specific Next.JS topics. Feel free to leave any requests in the comments!

Core Concepts👩🏾‍💻

Next.JS is built around some React concepts that you’ll be familiar with if you’ve worked with React before. But there are obviously a few things that make Next.JS a bit different. Next.JS has some enhancements that give it an added edge over React or other frameworks. I already mentioned the compiling and bundling improvements. Next.JS also comes with image and font optimizations that enhance user experience and site performance. Images are lazy-loaded and automatically resized based on device size. You can read more details on font optimization in the Next.JS documentation.

Next.JS's main claim to fame is how rendering and routing are handled. Even if you haven’t worked with Next.JS before, you’ve probably at least heard terms like “Server-side rendering” and “Client-side rendering”. It’s really important to understand these concepts when you’re building applications with Next.JS. So let’s dive in.

Server Side Rendering vs Client Side Rendering⚙️

In Next.JS, you can choose where you want your components to be rendered: on the server side or on the client side. Next.JS is all about performance optimization and for that reason, Next.JS uses server side rendering by default. Server side rendering improves performance in a few ways:

Data fetching → When data fetching is done on the server side, the time it takes to retrieve data is reduced since the server is architecturally closer to the data source
Caching → When you render on the server, results can be easily and quickly cached which leads to faster response times for future requests.
Bundling → Large dependencies can now be kept on the server which reduces the size of your bundle on the client side

There are other benefits but I think these 3 really highlight how server side rendering can improve performance. These changes might seem small but they add up quickly. If you want to know more about the mechanics of server side rendering, check out this documentation.

Static rendering, dynamic rendering, and streaming🔧

Server side rendering can be done in 3 ways: static, dynamic, or streaming. Static rendering is the default. Information is rendered at build time meaning it’s preloaded before a request is made and cached. This is perfect for data that doesn’t need to be customized per user. Any information that is the same for every user can be statically generated. Again, this is a huge performance optimization. With dynamic rendering, data is rendered on each request. This is good for data that is unique to each user or for information that changes quickly.

When I first learned about static and dynamic rendering, I panicked a bit because I assumed that I would have to decide how each possible route and every piece of data on my site should be rendered. The great thing is that Next.JS automatically chooses for you. You still have control when you want to because you can specify when to cache or revalidate certain data. You can also choose to stream some data in your UI.

Streaming is a new feature of Next.JS that’s only available with the App Router (which we’ll dive into soon). Streaming allows you to progressively render data from the server. Using this rendering method allows you to keep displaying parts of a page immediately while the streamed data is still loading. Instead of the whole page loading and forcing your user to stare at a blank screen, streaming allows you to pinpoint the data that needs more time to render while still displaying the rest of the page.

To put all of this into context, an About page would be statically rendered since the information won’t change no matter who’s viewing it. Components on a profile page that can be changed such as display name or status would be dynamically rendered. For large amounts of data that can take time to load such as product reviews, posts on a social media feed, and the like, streaming can be used.

Client side rendering🔨

Now, what about client side rendering? Client side rendering is rendered on the client side at request time. Server side rendering is the default so in order to use client side rendering, you have to opt in. Next.JS automatically handles whether server side components will be rendered statically or dynamically but it doesn’t do the same for client components. You have to manually specify when you want client side rendering to be used.

When should you use client side rendering? Since you can use state and event listeners with client components, it’s perfect for interactive components that are meant to produce an immediate result for users. So think of liking a post or comment on a social media site. This kind of feature could be built with client components since liking something involves interactivity, data that changes quickly, and displaying said data to users immediately.

Conclusion👩🏾‍🏭

So we’ve covered the basics of rendering in Next.JS. This is an overview and there’s obviously more that goes into rendering especially under the hood. If you want to learn more of the nitty gritty details, check out some of these resources:

The main take away you should walk away from this post with is: Next.JS really prioritizes performance. Relying primarily on server side rendering is done to enhance performance and user experience. If performance is important for the project you're working on, Next.JS might be the right choice for you!

I’ll post part 2 of this series shortly! The information is already drafted so don’t worry it’s coming soon! If you have any questions or comments, please leave them below! I’ll try to get to as many of them as possible! Thanks for reading :)

Auth0 Developer Advocates Tackle Advent of Code

Jessica Temporal — Thu, 30 Nov 2023 21:14:43 +0000

TL;DR: Auth0's developer advocates are ready to rock #AdventOfCode this December. 🎉 Click here to learn how you can find us and join the fun.

Do you remember the joy of advent calendars? 🎅 You would get one calendar on the 1st of December and every day until Christmas you would open one of the tiny boxes and get a surprise. 🎁

What is Advent of Code

According to the website:

Advent of Code (AoC) is an Advent calendar of small programming puzzles for a variety of skill sets and skill levels that can be solved in any programming language you like.

And we, developers advocates from Auth0 by Okta want to join the fun. 🚀

We will solve the puzzles in our favourite languages, mine is Python 🐍.

When can I start solving puzzles

Go to the AoC website starting on December 1st at midnight EST (UTC-5), and the first puzzle will be available. Get ready to flex your coding muscles and enjoy the challenge! 💪

How are Auth0's developer advocates joining the fun

We are really excited for Advent of Code! Some developers might relate to this but for me trying to solving puzzles alone is no fun. So this time around I'm pairing up with Carla, she likes Ruby so I'll teach a little Python and she will teach me a little Ruby while we figure out the challenges together.

Other advocates will also try to solve the puzzles alongside developers of the world, you can follow us on social networks to accompany our progress while we use the hashtag #AdventOfCode. 🎉

But not only that! Some of us will also livestream our attempt at solving the puzzles! And we will even have friends on our livestreams to pair on puzzles.

How can I find you

Make sure to connect with us and tag us when you participate in the AoC. You can also follow the hashtag #AdventOfCode on your favourite social media. We will be using #AdventOfCode for all things AoC-related. This way you'll see not only us but everyone that post something about AoC. 🌟

Carla Urrea - Preferred language: Ruby

Corey L Weathers - Preferred language: C#

Jess Temporal - Preferred language: Python 🐍

Juan Martinez - Preferred language: Python 🐍

Kiah Imani - Preferred language: C#

When will you be streaming?

Here's our calendar for the month of December, but remember, your best bet is to follow us on the streaming platforms linked above to be notified when we go live. It's going to be a coding party you won't want to miss! 🎊

Other coding advent calendars and resources

So far I've seen:

Advent of Code - The OG coding advent calendar.
C# Advent - I heard Corey and Kiah are particularly excited for this one.
Advent of Cyber - Focused on cyber security.

Know of any others? Drop them in comments I'd love to add them here. 😉

Also, you may want to join the AdventOfCode subreddit for more coding fun and discussions.

Edit: We are all putting our solutions up in GitHub you'll find the repositories below 👀

carlastabile / advent-of-code

My Advent Of Code solutions

Advent of Code

First time ever doing an advent of code was 2020. Initially I started using python3 but then switched to ruby because ruby is life.

For 2021 I'll try again with python3! Fingers crossed 🤞🏼

Each folder contains a year and each year the challenge of a day and my answer.

I usually start with a naive answer and try to iterate over it to improve. Nonetheless, I can't promess I iterated over all of them :D

Contribute

I feel fancy, but if you want to contribute by improving my answers please feel fre to open a PR. What's a GitHub repo without PRs am I right?

Be nice

No rude comments are accepted under this space. This is a safe space.

View on GitHub

jtemporal / adventofcode2023

my attempts at advent of code 2023

Advent of Code 2023

Puzzles list

Day 1: Trebuchet!
Day 2: Cube Conundrum
Day 3: Gear Ratios
Day 4: Scratchcards
Day 5: If You Give A Seed A Fertilizer
Day 6
Day 7
Day 8
Day 9
Day 10
Day 11
Day 12
Day 13
Day 14
Day 15
Day 16
Day 17
Day 18
Day 19
Day 20
Day 21
Day 22
Day 23
Day 24
Day 25

(Checkmarks indicate complete days)

View on GitHub

bajcmartinez / advent-of-code

Advent of Code 2023

My solutions in Python for the Advent of Code 2023.