Compute@Edge OAuth application starter kit

Connect to an identity provider such as Auth0 using OAuth 2.0 and validate authentication status at the Edge, to authorize access to your edge or origin hosted applications.

For more details about other starter kits for Compute@Edge, see the Fastly developer hub

Authentication at Fastly's edge, using OAuth 2.0, OpenID Connect, and Compute@Edge

This is a self-contained Rust implementation 🦀 for the OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (PKCE), deployed to Compute@Edge.

It includes JSON Web Token (JWT) verification, and access token introspection.

Scroll down to view the flow in more detail.

Getting started

After you have installed the starter kit, you'll need to do some configuration before you can deploy it, so that Fastly knows which identity provider to use and how to authenticate.

Set up an identity provider

You might operate your own identity service, but any OAuth 2.0, OpenID Connect (OIDC) conformant provider (IdP) will work. You will need the following from your IdP:

• A Client ID -> Add to src/config.toml
• An OpenID Connect Discovery document -> Save as src/well-known/openid-configuration.json
• A JSON Web key set -> Save as src/well-known/jwks.json
• The hostname of the IdP's authorization server -> Create as a backend called idp on your Fastly service

As an example, if you are using Auth0, follow these steps after installing the starter kit:

1. In the Auth0 dashboard, choose Create Application. Give your app a name and choose "Regular web application".
   • The client ID (eg. 4PWZBMqMWxnKXt1heitack0Jy2xRQP0p) is shown next to your application name.
2. Open src/config.toml in your Fastly project and paste in the client_id from your IdP. Set the nonce_secret field to a long, non-guessable random string of your choice. Save the file.
3. Back in Auth0's dashboard, click Settings, and note down the authorization server hostname (eg. dev-wna8lqtb.us.auth0.com) is shown in the Domain field.
4. In a new tab, navigate to https://{authorization-server-hostname}/.well-known/openid-configuration. Save it to src/well-known/openid-configuration.json in your Fastly project.
5. Open the file you just created and locate the jwks_uri property. Fetch the document at that URL and save it to src/well-known/jwks.json in your Fastly project.

Deploy the Fastly service and get a domain

Now you can build and deploy your new service:

$ fastly compute publish

You'll be prompted to enter the hostname of your own origin to configure the backend called backend, and also the authorization server of the identity provider which will be used to configure a backend called idp. When the deploy is finished you'll be given a Fastly-assigned domain such as random-funky-words.edgecompute.app.

Link the identity provider to your Fastly domain

Add https://{your-fastly-domain}/callback to the list of allowed callback URLs in your identity provide's app configuration (In Auth0, within your application's Settings tab, the field is labelled Allowed Callback URLs).

This allows the authorization server to send the user back to the Compute@Edge service.

Try it out!

Now you can visit your Fastly-assigned domain. You should be prompted to follow a login flow with your identity provider, and then after successfully authenticating, will see content delivered from your own origin.

---

The flow in detail

Here is how the authentication process works:

1. The user makes a request for a protected resource, but they have no session cookie.
2. At the edge, this service generates:
   • A unique and non-guessable state parameter, which encodes what the user was trying to do (e.g., load /articles/kittens).
   • A cryptographically random string called a code_verifier.
   • A code_challenge, derived from the code_verifier.
   • A time-limited token, authenticated using the nonce_secret, that encodes the state and a nonce (a unique value used to mitigate replay attacks).
3. The state and code_verifier are stored in session cookies.
4. The service builds an authorization URL and redirects the user to the authorization server operated by the IdP.
5. The user completes login formalities with the IdP directly.
6. The IdP will include an authorization_code and a state (which should match the time-limited token we created earlier) in a post-login callback to the edge.
7. The edge service authenticates the state token returned by the IdP, and verifies that the state cookie matches its subject claim.
8. Then, it connects directly to the IdP and exchanges the authorization_code (which is good for only one use) and code_verifier for security tokens:
   • An access_token – a key that represents the authorization to perform specific operations on behalf of the user)
   • An id_token, which contains the user's profile information.
9. The end-user is redirected to the original request URL (/articles/kittens), along with their security tokens stored in cookies.
10. When the user makes the redirected request (or subsequent requests accompanied by security tokens), the edge verifies the integrity, validity and claims for both tokens. If the tokens are still good, it proxies the request to your origin.

Issues

If you encounter any non-security-related bug or unexpected behavior, please file an issue using the bug report template.

Security issues

Please see our SECURITY.md for guidance on reporting security-related issues.