http-auth-middleware

This repo is an example of how to compose a middleware component with a business logic component.

Repo structure

The github-oauth/ directory contains an API for using GitHub oauth in an application. It consists of

The authorize handler which kicks off the github oauth flow allowing a user to give permissions to a GitHub app
The callback handler which GitHub uses as the redirect url in the oauth flow. The callback handler is responsible for taking a code from the URL param and exchanging it for authentication token from GitHub for the user.
The authenticate handler which validates a given access token in an incoming request with the GitHub user API.
The login handler which returns a login button.

The example/ directory contains a Spin application which consists of one http handler which returns an HTTP response contains Hello, Fermyon! in the body. In the spin.toml file, the component build instructions point to a build.sh script which builds the example component and composes it with the github-oauth component.

Demo instructions

Pre-requisites

Install cargo component v0.4.0:

cargo install --git https://github.com/bytecodealliance/cargo-component --tag v0.4.0 cargo-component --locked

Install wasm-tools:

cargo install --git https://github.com/bytecodealliance/wasm-tools wasm-tools --locked

Install latest Spin
Create an OAuth App in your GitHub Developer Settings. Set the callback URL to http://127.0.0.1:3000/login/callback. Accept defaults and input dummy values for the rest of the fields.
- Save the Client ID
- Generate a new Client Secret and save that as well

Build the components and run the demo

# Build the middleware
cargo component build --manifest-path github-oauth/Cargo.toml --release

# Build and run the example
spin up --build -f example -e CLIENT_ID=<YOUR_GITHUB_APP_CLIENT_ID> -e CLIENT_SECRET=<YOUR_GITHUB_APP_CLIENT_SECRET>

# Open http://127.0.0.1:3000/login in a browser

Running with Wasmtime

This component can be universally run by runtimes that support WASI preview 2's HTTP proxy world. For example, it can be served directly by Wasmtime, the runtime embedded in Spin. First, ensure you have installed the Wasmtime CLI with at least version v14.0.3. We will use the wasmtime serve subcommand which serves requests to/from a WASI HTTP component.

Unfortunately, wasmtime serve does not currently support setting environment variables in component, so we cannot pass environment variables at runtime as we did with Spin. Instead, set the CLIENT_ID and CLIENT_SECRET oauth app secrets generated in the prerequisites step as environment variables and build the oauth component with the compile-time-secrets feature flag. The flag ensures the environment variables are set in the component at compile time so they are no longer needed from the WebAssembly runtime. It is not recommended to embed secrets in production applications; rather, environment variables should be passed at runtime if the WebAssembly Host supports it. This is configurable with Spin and Fermyon Cloud.

export CLIENT_ID=<YOUR_GITHUB_APP_CLIENT_ID> 
export CLIENT_SECRET=<YOUR_GITHUB_APP_CLIENT_SECRET>
cargo component build --manifest-path github-oauth/Cargo.toml --release --features compile-time-secrets
# Compose the auth component with the business logic component using wasm-tools
cd example && ./build.sh
# Serve the component on the expected host and port
wasmtime serve service.wasm --addr 127.0.0.1:3000

Configuring the callback URL

Instead of using the default callback URL of http://127.0.0.1:3000/login/callback, you can configure the URL in an environment variable that is resolved at build time. This is useful in the case that the component is not running locally, rather in a hosted environment such as Fermyon Cloud.

export AUTH_CALLBACK_URL=http://my-auth-app.fermyon.app/login/callback
export CLIENT_ID=<YOUR_GITHUB_APP_CLIENT_ID> 
export CLIENT_SECRET=<YOUR_GITHUB_APP_CLIENT_SECRET>
cargo component build --manifest-path github-oauth/Cargo.toml --release --features compile-time-secrets
spin deploy -f example

Using Runtime Environment Variables

Not all WebAssembly runtimes fully support exporting the wasi:cli/environment interface to components. Spin, however, does support this and can load environment variables into a component's environment. Simply pass the environment variables during a spin up:

cargo component build --manifest-path github-oauth/Cargo.toml --release
spin up --build -f example -e CLIENT_ID=<YOUR_GITHUB_APP_CLIENT_ID> -e CLIENT_SECRET=<YOUR_GITHUB_APP_CLIENT_SECRET>

To deploy an app to Fermyon Cloud that uses environment variables, you need to configure them in your spin.toml. Update the example application manifest to contain your CLIENT_ID and CLIENT_SECRET environment variables. Since we do not know the endpoint for our Fermyon Cloud application until after the first deploy, we cannot yet configure the AUTH_CALLBACK_URL.

[component.example]
source = "service.wasm"
allowed_outbound_hosts = ["https://github.com", "https://api.github.com"]
environment = { CLIENT_ID = "YOUR_GITHUB_APP_CLIENT_ID", CLIENT_SECRET = "YOUR_GITHUB_APP_CLIENT_SECRET" }
[component.example.build]
command = "./build.sh"

Now deploy your application.

$ spin deploy -f example
Uploading example version 0.1.0 to Fermyon Cloud...
Deploying...
Waiting for application to become ready............. ready
Available Routes:
  example: https://example-12345.fermyon.app (wildcard)

In the example deploy output above, the app now exists at endpoint https://example-12345.fermyon.app. This means our callback URL should be https://example-12345.fermyon.app/login/callback. Configure this in the spin.toml with another environment variable:

[component.example]
source = "service.wasm"
allowed_outbound_hosts = ["https://github.com", "https://api.github.com"]
environment = { CLIENT_ID = "YOUR_GITHUB_APP_CLIENT_ID", CLIENT_SECRET = "YOUR_GITHUB_APP_CLIENT_SECRET", AUTH_CALLBACK_URL = "https://example-<HASH>.fermyon.app/login/callback" }
[component.example.build]
command = "./build.sh"

Now, redeploy with another spin deploy -f example. Be sure to update your GitHub OAuth App to update the callback URL.

This example uses environment variable to import secrets, since that is a ubiquitous interface and enables cross cloud portability of your component. If you are interested in configuring dynamic secrets that are not exposed in text in your spin.toml and can be updated with the spin cloud variables CLI, see Spin's documentation on configuring application variables.

thangchung / http-auth-middleware