DEV Community: Sandrino Di Mattia

JWT Bearer Authentication and Authorization for ASP.NET Core 5

Sandrino Di Mattia — Fri, 18 Dec 2020 00:00:00 +0000

Introduction

On November 10th, 2020 Microsoft released .NET 5 and the updated ASP.NET Core platform which includes a long list of performance improvements.

In this article we'll cover how you can configure JWT Bearer authentication and authorization for APIs built with ASP.NET Core 5. There are plenty of resources out which cover how to build your own "JWT authentication" with symmetric signing, but in this article we'll be focussing on leveraging OpenID Connect and OAuth 2 flows (using Auth0/Identity Server/Okta/...) where APIs are protected resources. Let's first take a look at how all pieces fit together from a high level. The APIs you build are typically called by applications on the user's behalf or on their own behalf.

Users interact with a SPA/Mobile App/Desktop App/Web Application/CLI/... and will be authenticating using OpenID Connect (Authorization Code Grant). The authorization server will issue an id_token (used by the application to authenticate the user) and an access_token which is used by the application to call the API on the users behalf.

When applications need to call an API on their own behalf they'll use the OAuth 2.0 Client Credentials Grant to acquire an access_token directly:

Configuring JWT Bearer Authentication

We'll start by creating a helper method which will handler all of the JWT Bearer configuration, using the Microsoft.AspNetCore.Authentication.JwtBearer package.

using System.Text.Json;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.IdentityModel.Tokens;

public static class JwtBearerConfiguration
{
  public static AuthenticationBuilder AddJwtBearerConfiguration(this AuthenticationBuilder builder, string issuer, string audience)
  {
    return builder.AddJwtBearer(options =>
    {
      options.Authority = issuer;
      options.Audience = audience;
      options.TokenValidationParameters = new TokenValidationParameters()
      {
        ClockSkew = new System.TimeSpan(0, 0, 30)
      };
      options.Events = new JwtBearerEvents()
      {
        OnChallenge = context =>
        {
          context.HandleResponse();
          context.Response.StatusCode = StatusCodes.Status401Unauthorized;
          context.Response.ContentType = "application/json";

          // Ensure we always have an error and error description.
          if (string.IsNullOrEmpty(context.Error))
            context.Error = "invalid_token";
          if (string.IsNullOrEmpty(context.ErrorDescription))
            context.ErrorDescription = "This request requires a valid JWT access token to be provided";

          // Add some extra context for expired tokens.
          if (context.AuthenticateFailure != null && context.AuthenticateFailure.GetType() == typeof(SecurityTokenExpiredException))
          {
            var authenticationException = context.AuthenticateFailure as SecurityTokenExpiredException;
            context.Response.Headers.Add("x-token-expired", authenticationException.Expires.ToString("o"));
            context.ErrorDescription = $"The token expired on {authenticationException.Expires.ToString("o")}";
          }

          return context.Response.WriteAsync(JsonSerializer.Serialize(new
          {
            error = context.Error,
            error_description = context.ErrorDescription
          }));
        }
      };
    });
  }
}

In the code above we're configuring the AddJwtBearer method with the following:

Authority: The issuer (eg: https://sandrino.auth0.com/)
Audience: Typically the identifier of your API which has been registered at the authorization server (eg: http://my-api)
ClockSkew: This is set to 5 minutes by default, but 30 seconds should be fine in most cases. This is to handle any differences in time between the authorization server and the API.

We're also modifiying the response of any JWT validation error to return a JSON object instead of the standard WWW-Authenticate challenge. This is optional and provides your clients with more context which can be useful to handle the error.

The helper can now be used to register an authentication service in the Startup class:

public class Startup
{
  private readonly IConfiguration _configuration;

  public Startup(IConfiguration configuration)
  {
    _configuration = configuration;
  }

  public void ConfigureServices(IServiceCollection services)
  {
    services.AddControllers();

    // Configure JWT authentication.
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
      .AddJwtBearerConfiguration(
        _configuration["Jwt:Issuer"],
        _configuration["Jwt:Audience"]
      );
  }

  public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  {
    app.UseRouting();
    app.UseAuthentication();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
      endpoints.MapControllers();
    });
  }
}

The Jwt.Issuer and Jwt.Audience settings will be read the appsettings.json configuration file:

{
  "Jwt": {
    "Issuer": "https://sandrino-dev.auth0.com/",
    "Audience": "urn:my-api"
  },
  ...
}

And that's it, we can now start creating the necessary APIs and secure them.

Creating a protected API

Let's start by creating a simple API which returns the claims for the current identity. In the Get action we'll use the [Authorize] attribute which requires the HTTP request to be authenticated.

public class UserInfo
{
  [JsonPropertyName("id")]
  public string Id { get; set; }

  [JsonPropertyName("claims")]
  public Dictionary<string, string> Claims { get; set; }
}

[ApiController]
[Route("/api/claims")]
public class UserController : ControllerBase
{
  [HttpGet]
  [Authorize]
  public UserInfo Get()
  {
    return new UserInfo()
    {
      Id = this.User.GetId(),
      Claims = this.User.Claims.ToDictionary(claim => claim.Type, claim => claim.Value)
    };
  }
}

In order to get the user's identifier using GetId() we can write a small helper class:

using System.Security.Claims;

public static class UserHelpers
{
  public static string GetId(this ClaimsPrincipal principal)
  {
    var userIdClaim = principal.FindFirst(c => c.Type == ClaimTypes.NameIdentifier) ?? principal.FindFirst(c => c.Type == "sub");
    if (userIdClaim != null && !string.IsNullOrEmpty(userIdClaim.Value))
    {
      return userIdClaim.Value;
    }

    return null;
  }
}

Let's go ahead and start our API. If we call this endpoint without providing a valid access_token in the Authorization header this will result in the following error:

{
  "error": "invalid_token",
  "error_description": "This request requires a valid JWT access token to be provided"
}

We can now try that same request with a valid token in the Authorization header:

curl \
  --request GET 'http://localhost:5001/api/claims' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InA0UVUtODVUY09GeG03c05JMWlaYyJ9.eyJpc3MiOiJodHRwczovL3NhbmRyaW5vLWRldi5hdXRoMC5jb20vIiwic3ViIjoiYXV0aDB8NTk3YTA2NTExM2Y0MGIwODQ4NWVlN2JkIiwiYXVkIjpbInVybjpteS1hcGkiLCJodHRwczovL3NhbmRyaW5vLWRldi5hdXRoMC5jb20vdXNlcmluZm8iXSwiaWF0IjoxNjA4Mjg2OTMxLCJleHAiOjE2MDgyOTY5MzEsImF6cCI6IllRd0Q0YTBBMTFreURJQzJPcVBLNnVDR3FHNEQ3cnVJIiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBvZmZsaW5lX2FjY2VzcyIsImd0eSI6InBhc3N3b3JkIn0.l9dOVOXvnFhmMbUAelGiQJTwlCpgXqE6nbrdbTJhg1shxhMiGSuMg3YN3eFLD3-TfU8T5nHNttjgHdlIus-oQuJspYg4Mqu6NTIE0PxGnQQDYqADnXzpLV4OdFc2k1YuZwCpE8dJDJ0lzvXTsio3DKvWq_Vq3gL7qAWtF5EefKbsfTOaLhVPZ8YIcY8C0VSReJnC2M8da0KAdP0SqYJB_BIZYeQiPg668MrGFWsKuQv1h4C9DU3o9Ol0S1nHZ6r8KiiMSQRJyFV7v82VQ3dZWjrj5YWGGR4Uk1Wuf3iochLxRz64MQp-iV_fuE1DECLjKTt6Bj-nLR2PZFDTHAheCA'

And this will then return the user's ID and the claims as expected:

{
  "id": "auth0|597a065113f40b08485ee7bd",
  "claims": [
    {
      "name": "iss",
      "value": "https://sandrino-dev.auth0.com/"
    },
    {
      "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
      "value": "auth0|597a065113f40b08485ee7bd"
    },
    {
      "name": "aud",
      "value": "urn:my-api"
    },
    {
      "name": "aud",
      "value": "https://sandrino-dev.auth0.com/userinfo"
    },
    {
      "name": "iat",
      "value": "1608286931"
    },
    {
      "name": "exp",
      "value": "1608296931"
    },
    {
      "name": "azp",
      "value": "YQwD4a0A11kyDIC2OqPK6uCGqG4D7ruI"
    },
    {
      "name": "scope",
      "value": "openid profile offline_access"
    },
    {
      "name": "gty",
      "value": "password"
    }
  ]
}

Note that you can easily test the above using Auth0 and Insomnia.

What just happened?

You might be wondering what just happened?! How was the API able to validate the JWT Bearer token without having to configure a secret or a public key? This is because the authentication service will use the OIDC metadata endpoints to get all of the necessary information.

The OpenID Configuration is read first: https://sandrino-dev.auth0.com/.well-known/openid-configuration
From there it will find the url to the jwks_uri and then load that one: https://sandrino-dev.auth0.com/.well-known/jwks.json
The public key(s) are loaded from that document and used to verify the incoming JWT Bearer tokens

Creating an Authorization Policy

The above is a good step to create a secure API, but it might not be granular enough. Not everyone might have access to all operations that are exposed in your API. This is where you'll want to create an Authorization Policy in which you'll be able to restrict access to certain operations.

In our example we'll create an endpoint to query the Billing Settings which is only available to users who have the read:billing_settings scope. In your Authorization Server you'll typically configure that only users that are member of a certain group, only users with a specific role or permission ... can receive this scope. But once the application can request that scope on the user's behalf it will be available in the access_token and the call to this endpoint will succeed.

The authorization handler implements our business requirement. It will extract the scope claim from the current principal and will then validate if the configured claim (eg: read:billing_settings) is available. If it is, then the request is allowed to continue.

public class ScopeRequirement : IAuthorizationRequirement
{
  public string Issuer { get; }

  public string Scope { get; }

  public ScopeRequirement(string issuer, string scope)
  {
    Issuer = issuer ?? throw new ArgumentNullException(nameof(issuer));
    Scope = scope ?? throw new ArgumentNullException(nameof(scope));
  }
}

public class RequireScopeHandler : AuthorizationHandler<ScopeRequirement>
{
  protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, ScopeRequirement requirement)
  {
    // The scope must have originated from our issuer.
    var scopeClaim = context.User.FindFirst(c => c.Type == "scope" && c.Issuer == requirement.Issuer);
    if (scopeClaim == null || String.IsNullOrEmpty(scopeClaim.Value))
      return Task.CompletedTask;

    // A token can contain multiple scopes and we need at least one exact match.
    if (scopeClaim.Value.Split(' ').Any(s => s == requirement.Scope))
      context.Succeed(requirement);
    return Task.CompletedTask;
  }
}

We should then register this policy for every scope our API supports and also register the handler:

// Create an authorization policy for each scope supported by my API.
services.AddAuthorization(options =>
{
  var scopes = new[] {
    "read:billing_settings",
    "update:billing_settings",
    "read:customers",
    "read:files"
  };

  Array.ForEach(scopes, scope =>
    options.AddPolicy(scope,
      policy => policy.Requirements.Add(
        new ScopeRequirement(_configuration["Jwt:Issuer"], scope)
      )
    )
  );
});

// Register our authorization handler.
services.AddSingleton<IAuthorizationHandler, RequireScopeHandler>();

For each scope we register a policy with the name of that scope, allowing us to use [Authorize("read:billing_settings")] later in our code.

As a final step we can now create a BillingController in which we'll expose the necessary functionality for a user to manage their billing settings. The /api/billing/settings endpoint requires the presence of the read:billing_settings scope:

[ApiController]
[Route("/api/billing")]
public class BillingController : ControllerBase
{
  [HttpGet]
  [Route("settings")]
  [Authorize("read:billing_settings")]
  public BillingSettings Get()
  {
    return new BillingSettings()
    {
      Country = "United States",
      State = "Washington",
      Street = "Microsoft Road 1",
      VATNumber = "987654321"
    };
  }
}

When interacting with my authorization server I'll want to make sure to request this scope:

https://sandrino-dev.auth0.com/authorize
  ?client_id=5CMfGLsLworduMTOfVD0Kap2IQm4xpLH
  &scope=openid profile read:billing_settings
  &redirect_uri=https://jwt.io
  &response_type=code
  &audience=urn:my-api
  &...

And then the resulting access_token which now includes the read:billing_settings scope can be used to call the endpoint:

GET /api/billing/settings
Host: localhost:5001
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InA0UVUtODVUY09GeG03c05JMWlaYyJ9.eyJpc3MiOiJodHRwczovL3NhbmRyaW5vLWRldi5hdXRoMC5jb20vIiwic3ViIjoiYXV0aDB8NTk3YTA2NTExM2Y0MGIwODQ4NWVlN2JkIiwiYXVkIjpbInVybjpteS1hcGkiLCJodHRwczovL3NhbmRyaW5vLWRldi5hdXRoMC5jb20vdXNlcmluZm8iXSwiaWF0IjoxNjA4Mjg3MzY4LCJleHAiOjE2MDgyOTczNjgsImF6cCI6IllRd0Q0YTBBMTFreURJQzJPcVBLNnVDR3FHNEQ3cnVJIiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSByZWFkOmJpbGxpbmdfc2V0dGluZ3Mgb2ZmbGluZV9hY2Nlc3MiLCJndHkiOiJwYXNzd29yZCJ9.CMvAa4gVO5dFnXBqWK8UIq5mB--3JacVv9MwocnWFTSR5p938zhw5hMREqUGCesIWy5UUZeb7ka7Dhp4Mf3tK-8h3psfsPMMpI3OP4q8IglKplt1KaXe5rn8Fmm2daNDnxmMccXusLI7T_Ea3hfVrjrfURprNfXW9vCS17Xj6mRHF9RBHNkeg8CKyotatPQojY_uex2L3qBhJhGXBd8CHvnnbEVZMYVlc_D02tqMu4bvs9QCml8y3qQkyvBHOAEJcE7b84trIJK2vIh7B339l-ukeSyK1AEkf5hHAlUjGRuB1dhtfodWLexEd5rH-Tn55xwdvL2CyQI-J2JVIQS0Kw

{
  "country": "United States",
  "state": "Washington",
  "street": "Microsoft Road 1",
  "vat_number": "987654321"
}

Calling this endpoint without the required read:billing_settings scope will result in a 403 Forbidden.

Auth0 Role Based Access Control

If you're using Auth0 as your authorization server you can configure the "RBAC authorization policies" for your APIs:

This will restrict access to the scopes defined on the API to users who have the required Role or Permission assigned.

We can now create a Role Billing Admin in which we'll add the read:billing_settings permission:

And as a final step we can assign the role to our users, allowing applications to request the read:billing_settings scope for them.

✅ Success!

With all of the above you should be all setup to configure JWT Bearer authentication and authorization in your own APIs.

A full demo application is available on GitHub: https://github.com/sandrinodimattia/aspnet-core-5-jwt-bearer-demo

Insomnia Core: Testing APIs secured with Auth0

Sandrino Di Mattia — Wed, 16 Dec 2020 00:00:00 +0000

Introduction

After having been a long time Postman user I recently switched to Insomnia Core, a lightweight and simple tool to test REST but also GraphQL and gRPC services.

One of the key capabilities of Insomnia is the support for different authentication methods including AWS IAM, NTLM and OAuth 2.0 (which is technically not authentication 🙃 ). The support for OAuth 2.0 and its different grants makes it extremely easy to test your APIs which are secured with Auth0. Let's take a look.

Client Credentials Grant

A very popular capability in Auth0 is the support for machine-to-machine scenarios with the OAuth 2.0 client_credentials grant. In this example I've created an API in Auth0 (optionally with some scopes) and then I've also created a Machine to Machine application:

This application then needs to be authorized for the API I created:

Similar to Postman it's also possible to create environments with Insomnia, in which you can define all of your settings, secrets, URLs, ... as variables. I've gone ahead and created some variables for my Auth0 account:

{
  "AUTH0_TOKEN_ENDPOINT": "https://sandrino-dev.auth0.com/oauth/token",
  "AUTH0_CLIENT_ID": "xYHne6VBWIhWBzxF4Hy8ZTiDCrex00N3",
  "AUTH0_CLIENT_SECRET": "bNZ2xSbbS3Mvq1ND1xZC0J2zu...",
  "AUTH0_AUDIENCE": "urn:my-api"
}

This then allows me to use these values in my requests without having to copy them all over the place. As a next step Ican enable authentication for my request and configure OAuth 2 with the Client Credentials grant type with the following settings:

ACCESS TOKEN URL: The /oauth/token endpoint for your Auth0 tenant
CLIENT ID: The Client ID of your Machine to Machine application
CLIENT SECRET: The Client Secret of your Machine to Machine application
HEADER PREFIX: Set to Bearer
AUDIENCE: The identifier of your API

The Fetch Tokens button can now be used to request a new access_token from Auth0. Once that's done I can call my protected API endpoint:

The Timeline tab allows you to inspect the HTTP request in more detail, including the Authorization header and the access_token which was sent to the API:

Authorization Code Grant

For testing any user based flows you can choose to create a Regular Web Application, a Single Page Application or Native application and also test the authorization_code grant with Insomnia.

In this example I've gone and created a Regular Web Application and an API with Offline Access enabled (for requesting a refresh_token). The Callback URL of the application has to be set to something, so for this test I'm just setting it to http://insomnia

As a next step I've updated the Insomnia Environment to also include the AUTH0_AUTHORIZE_ENDPOINT:

{
  "AUTH0_AUTHORIZE_ENDPOINT": "https://sandrino-dev.auth0.com/authorize",
  "AUTH0_TOKEN_ENDPOINT": "https://sandrino-dev.auth0.com/oauth/token",
  "AUTH0_CLIENT_ID": "DVIiCVJccDTscB1eBFS3BFrQ8JACl3EF",
  "AUTH0_CLIENT_SECRET": "ZLSi5XpuG6YLdryNX2dKsicU1....",
  "AUTH0_AUDIENCE": "urn:my-api"
}

On the request authentication the Authorization Code grant type can now be selected in OAuth 2:

Pay close attention to the following settings:

REDIRECT URL: Also set to http://insomnia. When you fetch the tokens a browser window will open in which you'll be able to sign in as a user. At the end Auth0 will redirect to http://insomnia where Insomnia will catch that redirect and perform a code exchange.
SCOPE: You'll want to use the offline_access scope if you need a refresh_token or require any scope for your API.

Clicking Fetch Tokens will open a browser window in which I'm able to sign in and Insomnia will take care of the OAuth 2 dance.

Any subsequent Fetch Tokens will use the refresh_token if it was originally requested using the offline_access scope, so you won't have to login again.

One nice thing here is that Insomnia also supports Refresh Token Rotation, so if your Authorization Server returns a new refresh_token for each exchange.

Resource Owner Password Grant

And finally if you have legacy applications which use the Resource Owner Password Grant you can also use this in Insomnia:

Note that for Auth0 you'll need to configure the credentials to be In Request Body

When using multiple Database Connections in Auth0 you might run into issues because Insomnia won't allow you to define which connection to use. A default Database Connection can be configured in the Auth0 Tenant Settings instead:

✅ Success!

And there we go. Testing APIs which are secured with Auth0 has never been easier! You can even take it one step further and use the Insomnia CLI (inso) to automate your tests.

Securing Netlify Functions with serverless-jwt and Auth0

Sandrino Di Mattia — Tue, 28 Jul 2020 00:00:00 +0000

Want to skip the details? Try out the online demo.

Introduction

With the rise of JAMstack we've seen a lot of frameworks and platforms offer the ability to build and host Serverless functions as lightweight backends for your applications.

In the last few years the Node.js ecosystem has provided many solutions to handle authentication in your web applications through libraries like Passport.js and express-jwt. But due to the different programming model of Serverless functions (lambdas as opposed to full blown web servers) these libraries are not the perfect tool for the job.

This is where serverless-jwt comes in: a simple and lightweight solution focused at solving authentication for your Serverless functions. Here's an example of what it would take to protect a Netlify Function:

const { NetlifyJwtVerifier } = require('@serverless-jwt/netlify');

const verifyJwt = NetlifyJwtVerifier({
  issuer: 'https://sandrino.auth0.com/',
  audience: 'urn:my-api'
});

exports.handler = verifyJwt(async (event, context) => {
  const { claims } = context.identityContext;
  return {
    statusCode: 200,
    body: `Hi there ${claims.email}!`
  };
});

Let's take a look at how we can use this library to secure Netlify Functions: we're going to create a very simple Gatsby application which will authenticate users with Auth0 and then interact with Netlify Functions.

Configuring Auth0

Before we can build our application we're going to configure our Auth0 account with 2 new entities:

A Application representing the Gatsby application
An API representing the API we'll build in Netlify Functions

Configuring the Gatsby client

In the Applications section we'll create a new Application:

Application Type: Single Page Application
Allowed Callback URL: http://localhost:8888
Allowed CORS: http://localhost:8888
Allowed Web Origins: http://localhost:8888
Allowed Logout URL: http://localhost:8888

Configuring the API

In the APIs section we'll create a new API representing our backend. In this example we'll create a simple TV shows API so I'm filling in the following settings:

Name: TV Shows
Identifier: https://api/tv-shows

It doesn't really matter what you choose as the Identifier, this will simply be the identifier or audience of your API.

We'll also create a few scopes in this API. Later in the implementation we'll enforce the presence of certain scopes to restrict access to certain functions. Applications will be able to request the read:shows and create:shows scopes.

Creating an API using Netlify Functions

So we'll create 2 functions which can be called from the Gatsby application:

/.netlify/functions/me: This function will require the user to be authenticated and simply return the current user information.
/.netlify/functions/shows: In addition to being authenticated, this function will also require the read:shows scope to be available.

To start we'll create a file containing all of the authentication logic using @serverless-jwt/netlify. This will create a JWT verifier for Netlify which we can use to secure our functions.

const { NetlifyJwtVerifier, removeNamespaces, claimToArray } = require('@serverless-jwt/netlify');

const verifyJwt = NetlifyJwtVerifier({
  issuer: process.env.JWT_ISSUER,
  audience: process.env.JWT_AUDIENCE,
  mapClaims: (claims) => {
    const user = claims;
    user.scope = claimToArray(user.scope);
    return user;
  }
});

/**
 * Require the request to be authenticated.
 */
module.exports.requireAuth = verifyJwt;

Let's also go ahead and create a .env file containing the issuer and audience:

JWT_ISSUER: Your Auth0 (Custom) Domain
JWT_AUDIENCE: The identifier of the API you created

JWT_ISSUER=https://sandrino.auth0.com/
JWT_AUDIENCE=https://api/tv-shows

And that's it. We can now import the verifier and secure our handler:

const { requireAuth } = require('../../lib/auth');

exports.handler = requireAuth(async (event, context) => {
  try {
    const { claims } = context.identityContext;

    return {
      statusCode: 200,
      body: JSON.stringify({ claims })
    };
  } catch (err) {
    return {
      statusCode: 500,
      body: JSON.stringify({ error_description: err.message })
    };
  }
});

This handler will now only execute if a valid token has been provided, otherwise it will fail and return an error message to the user. Let's go ahead and build a Gatsby application to test this out.

Building the Gatsby application

I will not go into too much detail on how to build the Gatsby application, since there's plenty of resources available covering this topic in depth. Now for this example to work we'll need to use Auth0's React SDK:

import React from 'react';
import { navigate } from 'gatsby';
import { Auth0Provider } from '@auth0/auth0-react';

import './src/styles/site.css';

const onRedirectCallback = (appState) => navigate(appState?.returnTo || '/');

export const wrapRootElement = ({ element }) => {
  return (
    <Auth0Provider
      domain={process.env.GATSBY_AUTH0_DOMAIN}
      clientId={process.env.GATSBY_AUTH0_CLIENT_ID}
      audience={process.env.GATSBY_AUTH0_AUDIENCE}
      scope={process.env.GATSBY_AUTH0_SCOPE}
      redirectUri={window.location.origin}
      onRedirectCallback={onRedirectCallback}
    >
      {element}
    </Auth0Provider>
  );
};

The environment variables come from my .env file. The environment variables are prefixed with GATSBY_*, making them available in the browser. Fill in the following settings:

GATSBY_AUTH0_DOMAIN: Your Auth0 (Custom) Domain
GATSBY_AUTH0_CLIENT_ID: The Client ID of your Gatsby application
GATSBY_AUTH0_AUDIENCE: The identifier of the API you created
GATSBY_AUTH0_SCOPE: The openid profile scopes are used for authentication while the read:shows scope will be present in the access_token which we'll provide to Netlify Functions.

GATSBY_AUTH0_DOMAIN=sandrino.auth0.com
GATSBY_AUTH0_CLIENT_ID=6qy0GxNC46tKvoYPc60mlW6X55jyrlaY
GATSBY_AUTH0_AUDIENCE=https://api/tv-shows
GATSBY_AUTH0_SCOPE=openid profile read:shows

Now that the Gatsby application has been configured we'll add a Login button to the header:

import React from 'react';
import { useAuth0 } from '@auth0/auth0-react';

export default () => {
  const { loginWithRedirect } = useAuth0();

  return (
    <header>
      <div>
        <span className="text-xl">Gatsby &amp; Netlify Functions</span>
        <button onClick={() => loginWithRedirect()}>Login</button>
      </div>
    </header>
  );
};

Clicking this button will redirect users to Auth0 where they can authenticate. Once they are authenticated they can call the API:

export default function Home() {
  const [response, setResponse] = useState();
  const { getAccessTokenSilently, isLoading, error, user } = useAuth0();

  const getUserProfile = async () => {
    try {
      setResponse('Loading...');

      const token = await getAccessTokenSilently({
        audience: process.env.GATSBY_AUTH0_AUDIENCE
      });

      const api = await fetch('/.netlify/functions/me', {
        headers: {
          authorization: 'Bearer ' + token
        }
      });

      const body = await api.json();
      setResponse({
        status: api.status,
        statusText: api.statusText,
        body
      });
    } catch (e) {
      setResponse(e.message);
    }
  };

  return <Layout>...</Layout>;
}

We'll first use the Auth0 React SDK to acquire an access_token using the getAccessTokenSilently method, which can then be presented to our first function. If the token is valid, the function will return the user and it will be rendered on the page.

Implementing Authorization

Let's now also add a simple authorization use case to our example. If you want to list the TV Shows that are available you might need to have a subscription or a specific role.

So we'll implement a helper which will require a scope to be present when a call is made to a function:

module.exports.requireScope = (scope, handler) =>
  verifyJwt(async (event, context, cb) => {
    const { claims } = context.identityContext;

    // Require the token to contain a specific scope.
    if (!claims || !claims.scope || claims.scope.indexOf(scope) === -1) {
      return json(403, {
        error: 'access_denied',
        error_description: `Token does not contain the required '${scope}' scope`
      });
    }

    // Continue.
    return handler(event, context, cb);
  });

If a valid token is presented, this will now require the existence of a given scope. And we can use this to implement our TV Shows endpoint. For this function, the user must present a token with a read:shows claim.

const fetch = require('node-fetch');
const { requireScope } = require('../../lib/auth');

exports.handler = requireScope('read:shows', async (event, context) => {
  try {
    const res = await fetch('https://api.tvmaze.com/shows');
    const shows = await res.json();

    return {
      statusCode: 200,
      body: JSON.stringify(
        shows.map((s) => ({
          id: s.id,
          url: s.url,
          name: s.name
        }))
      )
    };
  } catch (err) {
    return {
      statusCode: 500,
      body: JSON.stringify({ error_description: err.message })
    };
  }
});

By default Auth0 will allow applications to request any of the available scopes on an API. But we can change this by flipping the Enable RBAC toggle on our API. By doing this, only users with the necessary role or permission will receive this scope.

We can now create a role (eg: TV Shows Viewer), add permissions to this role (eg: the read:shows permissions) and then finally assign this role to a user.

Users without this role will not receive the read:shows scope in their access_token. If they attempt to call the function it will result in the following error:

{
  "error": "access_denied",
  "error_description": "Token does not contain the required 'read:shows' scope"
}

Users with the scope will be able to call the API just fine.

✅ Success!

And that's it. In a few simple steps we've configured Auth0, added authentication to our Gatsby application, secured our Netlify Functions and implemented RBAC. Phew! 🚀

A demo application is available in which you can test the flow end to end: https://gatsby-auth0-netlify-functions.netlify.app/.

The full source for the example application is available on GitHub.

Controlling access to your AWS API Gateway HTTP API with Auth0

Sandrino Di Mattia — Thu, 28 May 2020 18:16:52 +0000

Want to skip the details? Try out the online demo.

Introduction

A few weeks ago AWS API Gateway HTTP APIs became generally available - offering a simpler, faster and cheaper way to build APIs.
One of the capabilities that has been simplified is the whole authorization story, which is what we'll be covering in this blog post.

For the traditional REST APIs you would often write your own Custom Authorizer using a Lambda function to support JWT authorization (mainly in the context of OpenID Connect and OAuth 2.0).
This is no longer needed for HTTP APIs, which offers a JWT authorizer out of the box.

What this means is that you can configure your own JWT Authorizer by providing 3 simple settings instead of having to deploy and maintain your custom authorizers:

identitySource: Which refers to where the token can be found (eg: the Authorize header)
issuer: The issuer URI of the Identity Provider (eg: https://acme.auth0.com/)
audience: The audience of your API

Auth0 as a JWT Authorizer

Let's see how we can configure Auth0 as a JWT Authorizer. We'll be building a simple API returning colors with public endpoints and private endpoints, requiring the user to authenticate first.

Configuring your Auth0 account

In your account you'll want to represent your HTTP API as an API in Auth0, which you'll need to give a name and an identifier. The identifier is what will end up being the audience of your JWT Authorizer.

I'm also going to create a "Single Page Application" under Applications since I'll write a small React application to interact with the HTTP API. Also here the configuration is relatively simple.

Allowed Callback URLs: http://localhost:3000
Allowed Web Origins: http://localhost:3000
Allowed Origins (CORS): http://localhost:3000

We configure the application with http://localhost:3000 so we can test everything locally.

And the last thing we'll do on the Auth0 side is write a rule which will add some custom claims to the access_token:

function (user, context, callback) {
  context.accessToken['http://sandrino/roles'] =  [ 'admin', 'member' ];
  context.accessToken['http://sandrino/email'] =  user.email;
  context.accessToken['http://sandrino/email_verified'] =  user.email_verified.toString();
  return callback(null, user, context);
}

And that's actually all there is to it. Let's move on to the HTTP API.

Configuring your HTTP API

There are plenty of resources out there (example on the auth0.com blog) which show you how to configure a JWT Authorizer in the AWS console, so in this post we'll use the Serverless framework instead.

In the configuration below you'll see a few things:

CORS is enabled for my API because we want the browser to be able to interact with it
Auth0 was configured as an authorizer, by simply providing the Issuer URL and the audience of the API we created in the Auth0 dashboard
We have two endpoints: /colors which is public (no authorizer configured), and /my/profile which will the request to be authorized

service: http-api-jwt-example

provider:
  name: aws
  runtime: nodejs12.x
  httpApi:
    cors:
      allowedHeaders:
        - Content-Type
        - Authorization
      allowedMethods:
        - GET
        - OPTIONS
      allowedOrigins:
        - http://localhost:3000
    payload: '2.0'
    authorizers:
      accessTokenAuth0:
        identitySource: $request.header.Authorization
        issuerUrl: https://sandrino.auth0.com/
        audience:
          - urn:colors-api

functions:
  # List all colors (public endpoint)
  getColors:
    handler: handler.colors
    events:
      - httpApi:
          method: GET
          path: /colors
  # List my profile (requires authorization)
  myProfile:
    handler: handler.myProfile
    events:
      - httpApi:
          method: GET
          path: /my/profile
          authorizer:
            name: accessTokenAuth0

If we apply this configuration you'll see a new JWT Authorizer show up in your AWS console:

When using Custom Domains in Auth0, you should configure that domain as the issuerUrl. So for example, you should use https://auth.sandrino.dev/ instead of https://sandrino.auth0.com/.

When a JWT Authorizer is configured for a route you won't have to worry about parsing and validating the token. If a valid token is provided, the claims will be available in the event - otherwise the request will fail.
Below is an example of a function accessing the claims provided by the JWT Authorizer and also extracting any custom claims we might have added (using Auth0 Rules):

module.exports.myProfile = async (event) => {
  const claims = event.requestContext.authorizer.jwt.claims;
  return {
    id: claims.sub,
    roles: claims['http://sandrino/roles'],
    claims
  };
};

Calling the API from the browser

We'll also create a simple Next.js application which use auth0-spa-js to sign in from the browser.

import { Auth0Client } from '@auth0/auth0-spa-js';

export default new Auth0Client({
  domain: 'https://sandrino.auth0.com', // Should be your Auth0 domain or your custom domain if you have configured it
  client_id: 'z9p3mE4Oc1PN4XKooapkPpn22nRONdJC',
  audience: 'urn:colors-api', // This should be the audience of the API you configured
  scope: 'openid profile email'
});

Our application will have a login button:

login = async () => {
  await auth0.loginWithRedirect({
    redirect_uri: window.location.href
  });
};

And after the user has signed in, we'll use a React hook to fetch the data from our API:

export default () => {
  const { data, error, isPending, get } = useApi(process.env.API_GATEWAY_BASE_URL);

  const getColors = () => get('/colors', { auth: false });
  const getMyProfile = () => get('/my/profile');

  return (
    <>
      <Stack mb={5} isInline spacing={4}>
        <Button size="md" onClick={getColors}>
          List All Colors
        </Button>
        <Button size="md" onClick={getMyProfile}>
          My Profile
        </Button>
      </Stack>
      <Snippet
        code={
          (isPending && '// Loading...') ||
          (error && JSON.stringify(error, null, 2)) ||
          (data && JSON.stringify(data, null, 2)) ||
          '// Press one of the buttons above to call the API Gateway'
        }
        language="json"
      />
    </>
  );
};

useApi is a custom React hook which retrieves the access_token from auth0-spa-js and attaches it to the Authorization header of the HTTP request. The implementation can be found in the sample project.

If we try this out we'll notice that unauthenticated calls fail:

But when we do sign in through Auth0 and the access_token is provided in the HTTP request the JWT Authorizer will allow the request to go through to our handler:

You'll notice that the issuer here is set to https://auth.sandrino.dev/ since I'm doing all of my tests with my Auth0 Custom Domain

Authorization Scopes and Role Based Access Control

On each route you also have the option to configure Authorization Scopes, allowing you to define which scope should be present in the token to access the API route. In the example below you can see that I'm now requiring the read:colors scope for a new endpoint:

If you're using the Serverless framework, you can just add the required scope to your route:

myColors:
  handler: handler.myColors
  events:
    - httpApi:
        method: GET
        path: /my/colors
        authorizer:
          name: accessTokenAuth0
          scopes:
            - read:colors

No code changes are required to your Lambda function, everything is handled by the JWT Authorizer. The only change you'll need to make is to request this scope on the client side:

import { Auth0Client } from '@auth0/auth0-spa-js';

export default new Auth0Client({
  domain: 'https://sandrino.auth0.com', // Should be your Auth0 domain or your custom domain if you have configured it
  client_id: 'z9p3mE4Oc1PN4XKooapkPpn22nRONdJC',
  audience: 'urn:colors-api', // This should be the audience of the API you configured
  scope: 'openid profile email read:colors' // We're requesting an additional scope here
});

Where it gets really interesting is the link with Auth0's Role Based Access Control features, where we can control access to certain scopes using roles and permissions. Let's look at an example. On the API we'll configure a new read:colors permission:

As part of this we'll also want to enable authorization policies for our API (the Enable RBAC toggle). This will require the user to have the right set of permissions:

With this setting enabled, the user needs to have the read:colors permission otherwise the scope will not be allowed. So even if a client requests openid profile email read:colors, the token will end up looking like this:

{
  "http://sandrino/email": "sandrino@auth0.com",
  "http://sandrino/email_verified": "true",
  "iss": "https://auth.sandrino.dev/",
  "sub": "auth0|593b80d5f8a341400599ce4f",
  "aud": [
    "urn:colors-api",
    "https://sandrino.auth0.com/userinfo"
  ],
  "iat": 1590666735,
  "exp": 1590753135,
  "azp": "z9p3mE4Oc1PN4XKooapkPpn22nRONdJC",
  "scope": "openid profile email"
}

Notice how the read:colors scope is not there, even though it was requested by the client

And as a result, a call to the new endpoint we created will fail because our token is missing the right scope:

Let's go ahead and create a Role in Auth0 to which we'll add the read:colors permission. By adding the permission to this role, any user with this role assigned will be able to receive the read:colors scope.

After creating the roles we can now assign it to a user:

Now when the user signs in you'll notice an important difference, the read:colors scope is available.

{
  "http://sandrino/email": "sandrino@auth0.com",
  "http://sandrino/email_verified": "true",
  "iss": "https://auth.sandrino.dev/",
  "sub": "auth0|593b80d5f8a341400599ce4f",
  "aud": [
    "urn:colors-api",
    "https://sandrino.auth0.com/userinfo"
  ],
  "iat": 1590678148,
  "exp": 1590764548,
  "azp": "z9p3mE4Oc1PN4XKooapkPpn22nRONdJC",
  "scope": "openid profile email read:colors"
}

When we try to access the new endpoint ... it works! With the required scope we are able to make a call to the new route:

You users will need to retieve a new access token from Auth0 before such a change has effect in your application. This happens by signing in again, through Silent Authentication (using an iframe) or by using a Refresh Token.

✅ Success!

As you've seen, with JWT Authorizers it becomes very easy to cover the authorization aspect of your API Gateway. And while this article has focused on end-user authentication, the same concepts of access_tokens and scope also apply to applications talking to your API on their own behalf.

The full sample of the Serverless framework project and the Next.js application can be found on GitHub.

Configuring Auth0 as a custom authentication provider for MongoDB Stitch applications

Sandrino Di Mattia — Mon, 18 May 2020 00:00:00 +0000

Want to skip the details? Try out the online demo.

Introduction

MongoDB Stitch is MongoDB's serverless platform which brings the power of MongoDB directly to your client-side application in the browser and on mobile. The serverless platform allows end-users to authenticate and access a subset of the data in your cluster based on the rules you have configured.

One of the core capabilities offered by the MongoDB Stitch platform is authentication with support for several providers: anonymous, email/password, Facebook, Google and Apple. There's also support for custom providers like static API keys, custom functions and custom JWT.

In this blog post we'll be using the Custom JWT Authentication provider to allow users to sign in using Auth0. This will allow your users to sign in only once and then talk to MongoDB Stitch as if it was just one more API used by your applications.

The diagram below illustrates how the JWT authentication provider works. Your user will first sign in using Auth0 after which the user will receive an id_token and an access_token. The access_token is then sent to MongoDB Stitch which will retrieve the public key from Auth0 and validate the tokens signature. If the token is valid, a MongoDB access_token and refresh_token will be returned (this happens using the Stitch SDK). These tokens can then be used to query your database, execute functions, ...

Configuration

Auth0

In Auth0 I started by creating a new application for my test application:

Application Type: Single Page Application
Allowed Callback URL: http://localhost:3000
Allowed Web Origins: http://localhost:3000
Allowed Origins: http://localhost:3000

I also created an API which represents MongoDB Stitch. The identifier can be whatever you want and you'll use it when configuring your application and MongoDB Stitch.

Once the API is created we'll also write a sample rule to add extra claims to the access_token, which will later be consumed by MongoDB Stitch:

function (user, context, callback) {
  context.accessToken['http://sandrino/email'] = user.email;
  context.accessToken['http://sandrino/email_verified'] = user.email_verified.toString();
  return callback(null, user, context);
}

MongoDB Stitch

In the MongoDB dashboard we need to create the following:

A MongoDB database cluster
A MongoDB Stitch application

After creating both of these resources you'll need to link them. This is done in the MongoDB Stitch application under the Clusters section:

You'll see that this link also has a name, my-app in this example.

We'll be building a sample todo application so we'll want to make sure users can only access their data. This is achieved through Rules (not to be confused with Auth0 Rules) where we'll create a role limiting access to documents where the ownerId field mathches the current user ID.

The final step is to configure the JWT authentication provider under the Users section. In this section the following will need to be configured:

The JWK URI, this will be https://AUTH0_DOMAIN/.well-known/jwks.json
Any mapping between incoming claims and to which fields in the user profile you want to persist these claims
The audience, the identifier of the API you created in the Auth0 dashboard

Integrating Auth0 and MongoDB Stitch

Now that both sides have been configured we can integrate them. In this example we'll create a client side application with React and auth0-spa-js.

With the following piece of code our user can sign in with Auth0:

import { Auth0Client } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
  domain: 'sandrino.auth0.com',
  client_id: '0EastzVCcEX1CXXD5usVXGnqnSSzWFMN',
  audience: 'urn:stitch-sandrino',
  scope: 'openid profile email''
});

export default class LoginAuth0 extends React.Component {
  async componentDidMount() {
    if (window.location.search.includes('code=')) {
      await auth0.handleRedirectCallback();

      history.pushState('', document.title, window.location.pathname);

      const user = await auth0.getUser();
      const accessToken = await auth0.getTokenSilently();

      ...
    }
  }

  login = async () => {
    await auth0.loginWithRedirect({
      redirect_uri: window.location.href
    });
  };

  render() {
    return (
      ...
    );
  }
}

After the user has signed in we can initialize the MongoDB Stitch SDK:

import { Stitch, RemoteMongoClient, CustomCredential } from 'mongodb-stitch-browser-sdk';

// The Stitch Application ID, which can be found under SDKs
const client = Stitch.hasAppClient(process.env.MONGO_APPLICATION_ID)
  ? Stitch.getAppClient(process.env.MONGO_APPLICATION_ID)
  : Stitch.initializeAppClient(process.env.MONGO_APPLICATION_ID);

const accessToken = await auth0.getTokenSilently();

const credential = new CustomCredential(accessToken);
await client.auth.loginWithCredential(credential);

And that's all there is to it. Your user has now signed in with Auth0 and used the access_token to authorize with MongoDB Stitch. This now allows you to create a service client and interact with the database from within the browser, eg:

const serviceClient = client.getServiceClient(
    RemoteMongoClient.factory,
    // The Stitch Service name, which can be found under the Clusters section. Eg: my-app
    process.env.MONGO_SERVICE_NAME
  );
};

// Get a collection.
const collection = this.serviceClient
  .db(process.env.MONGO_DATABASE)
  .collection('things');

// Query the collection, where I'm the owner of the record.
const things = await collection
  .find({}, { limit: 20 })
  .asArray();

// Delete items from the collection, where I'm the owner of the record.
const result = await collection
  .deleteOne({ _id: things[0]._id });

Functions

MongoDB Stitch also allows you to define serverless functions which can be called from the client side and in the context of the user. We can for example have a function which will create a record in a collection and set the ownerId field to the current user:

exports = async function doSomething(data) {
  if (!context.user) {
    throw new Error('User not authenticated');
  }

  var collection = context.services.get('my-app').db('development').collection('things');

  var document = await collection.insertOne({
    name: data.name,
    date: data.date,
    ownerId: context.user.id,
    createdOn: new Date()
  });

  return document;
};

The function needs to be configured using Application Authentication which will allow it to run in the context of the current user.

You can now call the function from the client side using the MongoDB Stitch client. Here's an example of how you can call the function from the client to create a record. As you can see the ownerId is not provided here, instead it will be set by the serverless function using the current user ID.

onSaveClick = async () => {
  const result = await serviceClient.callFunction('createThing', [
    {
      name: 'A new record'',
      date: new Date()
    }
  ]);
};

Integrating with Auth0 Role Based Access Control (RBAC)

The advantage of connecting Auth0 as an authentication provider is that you can also leverage other Auth0 capabilities like RBAC. We can for example create a role for our application and assign it to the user:

The goal is to expose this information to the MongoDB Stitch API where it can be used to apply certain authorization logic. First we need to enable the API for RBAC:

By enabling this setting the RBAC authorization policy will run and evaluate role assignments during every login transaction. You can then modify the Rule we had initially created to also add the user's roles to the access token:

function (user, context, callback) {
  context.accessToken['http://sandrino/roles'] =  context.authorization.roles;
  context.accessToken['http://sandrino/email'] =  user.email;
  context.accessToken['http://sandrino/email_verified'] =  user.email_verified.toString();
  return callback(null, user, context);
}

As users sign in again they will now have their role assignments added to the access token. Here's an example:

{
  "http://sandrino/roles": ["things_app_admin"],
  "http://sandrino/email": "sandrino@auth0.com",
  "http://sandrino/email_verified": "true",
  "iss": "https://sandrino.auth0.com/",
  "sub": "auth0|593b80d5f8a341400599ce4f",
  "aud": ["urn:stitch-sandrino"],
  "iat": 1589756749,
  "exp": 1589843149,
  "azp": "0EastzVCcEX1CXXD5usVXGnqnSSzWFMN",
  "scope": "openid profile email"
}

With this information now available in the token we can also update the metadata mapping on the authentication provider:

The user's role memberships will be persisted in the user's profile and will be made available in the current user context. This means you could update your createThing function to now also require the user to be assigned a specific role, eg:

exports = async function doSomething(data) {
  var collection = context.services.get('my-app').db('development').collection('things');
  if (!context.user) {
    throw new Error('User not authenticated');
  }

  if (!context.user.data || !context.user.data.roles || context.user.data.roles.indexOf('things_app_admin') === -1) {
    throw new Error('User is not allowed to create new things');
  }

  var document = await collection.insertOne({
    name: data.name,
    date: data.date,
    ownerId: context.user.id,
    createdOn: new Date()
  });

  return document;
};

Users that don't have this role assigned will not be able to create any new documents.

MongoDB Charts

Since your users are now creating data in your application it's time to create some reports. MongoDB Charts allows you to easily create reports over your data in MongoDB Atlas.

MongoDB Charts allows you to use your MongoDB Stitch application as an authentication provider (which in turn has the Custom JWT Authentication provider configured), allowing you to embed these charts in your client applications. When configuring the provider you can choose if the data has to be fetched using the rules you have configured in MongoDB Stitch (eg: fetch data in the context of the user).

For charts you wish to embed in your applications you'll be able to enable authenticated access.

The only thing left to do is then simply render them using the MongoDB access token, the Chart ID and the Carts Base URL:

import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';

export default class MongoChart extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      height: 0
    };
  }

  onClickBtn = async (e) => {
    e.preventDefault();

    try {
      this.setState({
        height: 500
      });

      // Get the access token from the Stitch client.
      const { accessToken } = client.auth.activeUserAuthInfo;

      const sdk = new ChartsEmbedSDK({
        baseUrl: 'https://charts.mongodb.com/your-charts-app',
        getUserToken: () => MongoClient.getAccessToken()
      });

      const chart = sdk.createChart({
        chartId: 'ed50b273-072d-418a-b68a-9910ffaa325a'
      });

      // render the chart into a container
      await chart.render(document.querySelector('#chart'));
    } catch (error) {
      console.error(error);
    }
  };

  render() {
    return (
      ...
      <div id="chart" style={{ height: `${this.state.height}px` }} />
    );
  }
}

As users sign in they'll now be able to access these embedded charts in the client application:

The power of MongoDB in your browser

It's amazing to see how MongoDB Stitch can bring the MongoDB experience we know to browsers and mobile applications in a secure way. This post focused only on browser applications, but everything you see here is also possible on mobile.

A fully working demo application is available here https://mongodb-stitch-auth0-example.now.sh/ (source code).

An in-depth overview of writing Cypress end-to-end tests when using Auth0

Sandrino Di Mattia — Wed, 13 May 2020 00:00:00 +0000

Introduction

With a great developer experience, a good looking UI and a simply way to extend the tooling Cypress is slowly becoming the standard for end to end testing.

One of the biggest issues of the platform is the limitation when it comes to supporting multiple top level origins.
The cypress#944 issue has been open since 2017 and doesn't provide a clear solution yet.

This makes it extra complicated to use redirect based authentication (OpenID Connect, SAML, ...) using products like Auth0.
And while there are some workarounds available using chromeWebSecurity, these don't seem to work in a consistent way and they could also influence the results of your tests (eg: third party cookies & SameSite)

The official SSO example provides some guidance but is so generic that it's hard to translate this to an actual system you use.

So the goal of this blog post is to explain how you can write test where users can authenticate using Auth0. Since signing in to a regular web application is so different from signing in to a JAMstack application/SPA, we'll be covering the two use cases separately.

General Concepts

Let's quickly cover some general concepts:

The login transaction should always be initiated by the application and it will simply be based on redirects. We're not going to do anything crazy with the ROPG or have tokens fly around in all directions.
The user will sign in to Auth0 where the IdP session will be created. We'll want to cache this across tests.
The user will then be redirected back to the application, where a local application session will be created (in the form of a cookie or a token). We'll also want to cache this across tests.

By following these concepts we can make sure we also include the actual login experience (which could contain custom data, RBAC ...) as part of the application with minimal impact on the tests.

In order to overcome the cross-domain issues that exist in Cypress we will be using Puppeteer for the section highlighted in gray and load this part as a Cypress plugin.
The only thing that needs to happen in this part is have the user be redirected to Auth0, have them enter their credentials and extract the Auth0 session cookie and the "redirect" to the application.
Then we can take that information and use it in our Cypress tests to complete the login transaction.

Below you can find part of the Puppeteer logic which receives the login url (eg: https://acme.auth0.com/authorize?...) and where the user input will be provided. You'll need to modify this if you require additional user input.

const puppeteer = require('puppeteer');

module.exports = async function Login(options = {}) {
  const browser = await puppeteer.launch({
    headless: options.headless,
    args: options.args || ['--no-sandbox', '--disable-setuid-sandbox']
  });

  const page = await browser.newPage();
  try {
    await page.setViewport({ width: 1280, height: 800 });
    await page.setRequestInterception(true);
    page.on('request', preventApplicationRedirect(options.callbackUrl));

    await page.goto(options.loginUrl);

    // Enter credentials.
    await writeUsername({ page, options });
    await writePassword({ page, options });

    // The press login.
    const response = await clickLogin({ page, options });

    // The login failed.
    if (response.status() >= 400) {
      throw new Error(`'Login with user ${options.username} failed, error ${response.status()}`);
    }

    // Redirected to MFA/consent/... which is not implemented yet.
    const url = response.url();
    if (url.indexOf(options.callbackUrl) !== 0) {
      throw new Error(`User was redirected to unexpected location: ${url}`);
    }

    // Now let's fetch all cookies.
    const { cookies } = await page._client.send('Network.getAllCookies', {});
    return {
      callbackUrl: url,
      cookies
    };
  } finally {
    await page.close();
    await browser.close();
  }
};

...

Regular Web Applications

Let's start by signing in to a regular web application which will create a session cookie when the user is signed in. We'll want to be able to write tests where we can sign in and then access both public and protected routes:

describe('My web application', () => {
  beforeEach(() => {
    const user = Cypress.env('DEFAULT_USER');
    cy.loginAuth0(user);
    cy.loadLoginState(user);
  });

  it('Visit the homepage without authentication', () => {
    cy.visit('http://localhost:8080');
  });

  it('Sign in and access a protected resource', () => {
    const user = Cypress.env('DEFAULT_USER');
    cy.visit('http://localhost:8080/protected');
    cy.contains('body', `Hello user: ${user}`, {
      timeout: 5000
    });
  });
});

We also have a sample web application which exposes several routes:

/login, the route which users hit to start the login transaction
/callback, the route where the user will be sent after they signed in using Auth0 and where the application session is created
/, the home page (not protected)
/protected a protected page

The package.json file comes with a test script that can start the server and run the tests in parallel: run-p --race start cy:run.

Signing in with Auth0

To start with we first need to have the user sign in with Auth0. We'll have the user hit the /login endpoint first which will redirect the user to Auth0. We'll capture that redirect and send it to Puppeteer:

/**
 * Hit the local login endpoint in the application which will redirect to Auth0.
 */
function startLogin() {
  return cy.request({
    url: 'http://localhost:8080/login',
    followRedirect: false
  });
}

/**
 * Universal Login
 * @param {*} user
 * @param {*} loginUrl
 */
function followUniversalLogin(user, loginUrl) {
  return cy.task('LoginPuppeteer', {
    username: user.email,
    password: user.password,
    loginUrl,
    callbackUrl: 'http://localhost:8080/callback'
  });
}

Then when Puppeteer is done signing in the user on the Auth0 side, we'll capture the redirect url provided by Auth0 and visit that URL in the Cypress test.

startLogin().then((response) =>
  followUniversalLogin(user, response.headers.location).then(
    ({ cookies, redirectUrl }) => {
      sessions.auth0 = cookies.map(createCookie);
      sessions.auth0.forEach((c) => cy.setCookie(c.name, c.value, c.options));

      cy.visit(redirectUrl);
      cy.getCookie('appSession').then((cookie) => {
        userSessions[user.email].app = [createCookie(cookie)];
      });
    }
  )
);

When Auth0 tries to redirect the user back to the application you'll see that the user will be redirected to http://localhost:8080/callback?code=...&state=.... By simply visiting this URL in Cypress the application (or the SDK/middleware you are using to be more precise) will perform a code exchange, retrieve the user and create a session.

Note that this assumes that your application is using the Authorization Code grant. This example does not support the Implict grant (where the id_token is passed through the front channel)

In my example I then read the appSession cookie (the application session cookie), but you might need to use a different value here. This is highly dependant on the framework you are using.

The userSessions session object is a cache in which we store the Auth0 session and the application session. By doing that we can reuse those cookies to stay signed in for any Cypress tests that requires it whithout having to talk to Auth0 all the time.

Signing in to the application

Now that we have the Auth0 session and the application session cached in Cypress, we can have a few additional commands to load the application session from the cache and store it in a cookie.

Cypress.Commands.add('loadLoginState', (email) => {
  return getUserSessions(email).then(({ user, sessions }) => {
    cy.log('Loading login state for' + user.email);

    if (!sessions.app) {
      throw new Error('Unable to find login state');
    }

    sessions.app.forEach((c) => {
      cy.log('Loading ' + c.name);
      cy.setCookie(c.name, c.value, c.options);
    });
  });
});

Testing

And that's it. With those commands you can now write very simple test that allow you to sign in to your regular web application:

describe('My web application', () => {
  beforeEach(() => {
    const user = Cypress.env('DEFAULT_USER');
    cy.loginAuth0(user);
    cy.loadLoginState(user);
  });

  it('Visit the homepage without authentication', () => {
    cy.visit('http://localhost:8080');
  });

  it('Sign in and access a protected resource', () => {
    const user = Cypress.env('DEFAULT_USER');
    cy.visit('http://localhost:8080/protected');
    cy.contains('body', `Hello user: ${user}`, {
      timeout: 5000
    });
  });
});

A fully working sample is available here: https://github.com/sandrinodimattia/code-samples/tree/master/cypress-auth0-example

JAMstack and Single Page Applications

For applications which receive the id_token and access_token on the client side it's slightly more challenging but not impossible.
Before you continue it's important to call out that this method is not compatible with Auth0's old auth0.js SDK. It only works for auth0-spa-js or any wrappers using that SDK.

For this scenario to work we need to make a tiny change in the actual application. When the application is initialized and it's running inside a Cypress test, we'll want to use localstorage as a cache location. This will allow us to inject the necessary tokens in local storage to create the "application session".

if (window.Cypress) {
  this.auth0 = window.auth0 = new window.Auth0Client({
    domain: 'sandrino.auth0.com',
    client_id: '3OnFkR1sYqxycE6RoLJx4xq5n5hy',
    cacheLocation: 'localstorage',
    redirect_uri: 'http://localhost:8080',
    audience: 'https://api/tv-shows'
  });
}

We also add the Auth0 client to the window, which allows our Cypress test to interact with it.

Signing in with Auth0

The overall logic here remains the same with the only exception that there is no /login endpoint which we can hit. So instead of doing that we need to talk to an instance of the Auth0 SDK and request it to generate the authorize URL:

cy.window().should('have.property', 'auth0');
cy.window().then((win) => {
  win.auth0.buildAuthorizeUrl();
});

return cy
  .window()
  .then((win) => win.auth0.buildAuthorizeUrl({}))
  .then((authorizeUrl) => {
    return followUniversalLogin(user, authorizeUrl);
  })
  .then(({ cookies }) => {
    cy.clearCookies({ domain: Cypress.env('AUTH0_DOMAIN') });

    sessions.auth0 = cookies.map(createCookie);
    sessions.auth0.forEach((c) => cy.setCookie(c.name, c.value, c.options));
  });

This will reuse the same logic with Puppeteer after which the Auth0 cookies will be cached.

Signing in to the application

Now that the Auth0 session has been established we can hit any protected route in the SPA which will then use getTokenSilently() to retrieve an access_token from Auth0. It does this by creating an hidden iframe and then performing a code exchange in the browser.
Once that successfully succeeded the SDK will persist all of the necessary data in local storage (because we changed the cacheLocation settings), which is our opportunity to extract and cache it.

Cypress.Commands.add('saveLoginState', (email) => {
  return getUserSessions(email).then(({ user, sessions }) => {
    cy.log(`Saving login state for ${user.email}`);

    if (!sessions.app) {
      sessions.app = [];
    }

    Object.keys(localStorage).forEach((key) => {
      cy.log(`Persisting ${key}`);
      sessions.app.push({
        name: key,
        value: localStorage[key]
      });
    });
  });
});

Cypress.Commands.add('loadLoginState', (email) => {
  return getUserSessions(email).then(({ user, sessions }) => {
    cy.log(`Loading login state for ${user.email}`);

    if (!sessions.app) {
      throw new Error('Unable to find login state');
    }

    sessions.app.forEach((c) => {
      cy.log(`Loading ${c.name}`);
      localStorage.setItem(c.name, c.value);
    });
  });
});

Testing

We can now go and write our test which will first sign in using Auth0 and then perform an action which calls getTokenSilently() after which the data from local storage is extracted and cached.

describe('Authenticated user', () => {
  beforeEach(() => {
    const user = Cypress.env('DEFAULT_USER');

    cy.visit('index.html');
    cy.loginAuth0(user);

    cy.hasLoginState(user).then((hasLoginState) => {
      if (!hasLoginState) {
        cy.log(`No application session found for ${user}`);
        cy.get('#getToken').click();
        cy.contains('div', 'Tokens:', {
          timeout: 5000
        });

        cy.saveLoginState(user);
      } else {
        cy.clearLocalStorage();
        cy.loadLoginState(user);
      }
    });
  });

  afterEach(() => {
    cy.clearStorage();
  });

  it('Call an API', () => {
    cy.server();
    cy.route('GET', Cypress.env('SHOWS_API')).as('shows');

    cy.visit('index.html');
    cy.get('#callApi').click();

    cy.wait('@shows').then((xhr) => {
      assert.isNotNull(
        xhr.response.body.shows,
        'TV shows were returned by the API'
      );
    });

    cy.contains('div', 'API Response:', {
      timeout: 5000
    });
  });
});

Handling Failures

The example also comes with an other helper that can intercept messages from the iframe, allowing you to also capture login failures:

Cypress.Commands.add('validateSilentAuthentication', (validateFn) => {
  return cy.window().then((win) => {
    return new Cypress.Promise((resolve) => {
      const listener = (e) => {
        if (e.data.type === 'authorization_response') {
          win.removeEventListener('message', listener);
          const { response } = e.data;
          validateFn(response);
          resolve();
        }
      };
      win.addEventListener('message', listener);
    });
  });
});

With this you can now also test how your application behaves when the user is not signed in:

it('Call an API', () => {
  cy.server();

  cy.visit('index.html');
  cy.get('#callApi').click();

  cy.validateSilentAuthentication((response) => {
    expect(response.error, 'Login should be required').to.equal(
      'login_required'
    );
  });

  cy.contains('div', 'Error:', {
    timeout: 5000
  });
});

Example application

A fully working sample is available here: https://github.com/sandrinodimattia/code-samples/tree/master/cypress-auth0-spa-sample

Keep on testing

Testing these scenarios in Cypress are way harder than they should be, but with the examples above you should have everything you need to get started with your Auth0 end to end tests.