Authenticate requests with Functions

Guard an Object Storage bucket with a function that validates a JSON Web Token and serves the object only to an authorized request.

Last updated

View as Markdown Agent setup

You can put a function in front of an Object Storage bucket, so the function validates a JSON Web Token before any object leaves the bucket.

A request that carries a valid token receives the object with its content type. Every other request receives HTTP 401, and the bucket is never read. A bucket that needs no token is served by a connector and a Rules Engine rule instead, which Use a bucket as an application origin covers.

Prerequisites

  • An Azion account.
  • The Azion CLI installed and authorized.
  • Node.js version 18 or higher.
  • A bucket that holds the objects to protect, with Workloads Access set to Read Only or Read & Write. A bucket set to Restricted is not read by Azion Runtime, so the function reaches nothing in it. Refer to Create a bucket.
  • A signing secret for the tokens your application issues.

How the check runs

The function answers the requests a rule routes to it. It reads the token from the Authorization header or from the auth_token cookie, verifies the signature against the shared secret, and calls Object Storage only after the signature checks out. A bucket is also reachable through the S3 endpoint and through a connector, and neither of those paths asks for a token; the function guards the path it sits on.

The flow below shows the two refusals and the single route that reaches the bucket:

Create the function project

The Azion CLI scaffolds the project and npm adds the library that verifies the token. To set up the project:

Initialize the project
azion init my-auth-storage

At the prompts, set Template to JavaScript and Runtime to Azion Runtime. The Azion CLI writes the project into a my-auth-storage folder.

Go to the project folder
cd my-auth-storage
Install the token library
npm install jose

The jose library verifies JSON Web Tokens in JavaScript runtimes. npm adds it to package.json.

The project folder holds the template source and the jose dependency.

Write the handler

Open the main JavaScript file of the project and replace its contents with this handler:

JavaScript
01import Storage from "azion:storage";
02import { jwtVerify } from "jose";
03
04async function verifyToken(token) {
05 try {
06 const secretKey = new TextEncoder().encode(Azion.env.get("JWT_SECRET"));
07 const { payload } = await jwtVerify(token, secretKey);
08 return { valid: true, payload };
09 } catch (error) {
10 console.error("JWT verification failed:", error.message);
11 return { valid: false, error: error.message };
12 }
13}
14
15function extractToken(request) {
16 // The Authorization header comes first.
17 const authHeader = request.headers.get("Authorization");
18 if (authHeader && authHeader.startsWith("Bearer ")) {
19 return authHeader.substring(7);
20 }
21
22 // The cookie is the fallback.
23 const cookieHeader = request.headers.get("Cookie");
24 if (cookieHeader) {
25 const cookies = cookieHeader.split(";").map(c => c.trim());
26 const authCookie = cookies.find(c => c.startsWith("auth_token="));
27 if (authCookie) {
28 return authCookie.substring(11);
29 }
30 }
31
32 return null;
33}
34
35async function handleRequest(event) {
36 const request = event.request;
37 const url = new URL(request.url);
38
39 // /files/image.png reaches the bucket as the key image.png
40 const objectKey = url.pathname.replace(/^\/files\//, "");
41
42 if (!objectKey) {
43 return new Response(JSON.stringify({ error: "Object key required" }), {
44 status: 400,
45 headers: { "Content-Type": "application/json" }
46 });
47 }
48
49 const token = extractToken(request);
50
51 if (!token) {
52 return new Response(JSON.stringify({
53 error: "Authentication required",
54 message: "Provide a valid JWT token in Authorization header or auth_token cookie"
55 }), {
56 status: 401,
57 headers: {
58 "Content-Type": "application/json",
59 "WWW-Authenticate": "Bearer"
60 }
61 });
62 }
63
64 const verification = await verifyToken(token);
65
66 if (!verification.valid) {
67 return new Response(JSON.stringify({
68 error: "Invalid token",
69 message: verification.error
70 }), {
71 status: 401,
72 headers: { "Content-Type": "application/json" }
73 });
74 }
75
76 try {
77 const storage = new Storage(Azion.env.get("BUCKET_NAME"));
78 const storageObject = await storage.get(objectKey);
79
80 return new Response(storageObject.content, {
81 status: 200,
82 headers: {
83 "Content-Type": storageObject.contentType || "application/octet-stream",
84 "Content-Length": String(storageObject.contentLength ?? ""),
85 "Cache-Control": "private, max-age=3600"
86 }
87 });
88 } catch (error) {
89 console.error("Storage error:", error);
90
91 if (error.message && error.message.includes("not found")) {
92 return new Response(JSON.stringify({
93 error: "Object not found"
94 }), {
95 status: 404,
96 headers: { "Content-Type": "application/json" }
97 });
98 }
99
100 return new Response(JSON.stringify({
101 error: "Internal server error"
102 }), {
103 status: 500,
104 headers: { "Content-Type": "application/json" }
105 });
106 }
107}
108
109addEventListener("fetch", (event) => {
110 event.respondWith(handleRequest(event));
111});

Six decisions sit in the code:

  • The object key is the request path with /files/ removed, so /files/image.png reads the key image.png. A request that leaves the key empty returns 400 with the body {"error": "Object key required"}.
  • A request with no token returns 401, carries the header WWW-Authenticate: Bearer, and names both accepted places in its message field.
  • A token the secret does not verify returns 401 with the body {"error": "Invalid token"} and the message jose raised.
  • A verified token reads the object and returns it with the content type Object Storage stored, or application/octet-stream when the object carries none. Cache-Control: private, max-age=3600 keeps the response out of a shared cache.
  • A key that is not in the bucket returns 404 with the body {"error": "Object not found"}. Every other storage failure returns 500.
  • console.error writes JWT verification failed: and Storage error:, and both lines reach the function logs.

The handler reads JWT_SECRET and BUCKET_NAME with Azion.env.get, so neither value is written into the code.

Configure the environment variables

Create a .env file in the root of the project, with the bucket the handler reads and the secret it verifies against:

Text
01BUCKET_NAME=your-bucket-name
02JWT_SECRET=your-secret

Configure local storage for development

Azion Runtime answers a local Object Storage call from a folder on your machine. Add a storage block to azion.config so storage.get resolves while you develop:

JavaScript
01storage: [
02 {
03 name: 'your-bucket-name',
04 prefix: 'your-bucket-prefix',
05 dir: './path/to/storage/files',
06 workloadsAccess: 'read_only',
07 },
08],

Replace your-bucket-name, your-bucket-prefix, and ./path/to/storage/files with the values of your project. workloadsAccess is the camelCase spelling the configuration file uses for the bucket’s access level, and read_only is enough for a handler that only reads.

Deploy the function

The deploy sends the code, and azion sync sends the values the code reads. To put both on your account:

Deploy the project
azion deploy

The Azion CLI builds the project and sends the function to your account.

Send the environment variables
azion sync

The handler reads BUCKET_NAME and JWT_SECRET at run time. Without this step the variables exist only in your .env file, and the function does not find them.

The function runs on your account with the bucket name and the signing secret it needs.

Verify the setup

Sign a token with the same secret, then request an object three times: with the header, with the cookie, and with neither. To check the function:

Sign a test token

Save the script as sign-token.mjs in the project folder, so Node.js reads it as a module, and run it with node sign-token.mjs:

JavaScript
01import { SignJWT } from 'jose';
02
03const secret = new TextEncoder().encode('your-secret-key');
04
05const token = await new SignJWT({
06 sub: 'user123',
07 permissions: ['read:files']
08})
09 .setProtectedHeader({ alg: 'HS256' })
10 .setIssuedAt()
11 .setExpirationTime('2h')
12 .sign(secret);
13
14console.log(token);

The script prints the signed token. Set secret to the value you stored in JWT_SECRET, or the function refuses every token the script issues.

Request an object with the Authorization header
Shell
01curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
02 https://your-domain.com/files/document.pdf

The response carries the object and the content type Object Storage stored for it.

Request the same object with the cookie
Shell
01curl -b "auth_token=YOUR_JWT_TOKEN" \
02 https://your-domain.com/files/document.pdf

The response is the same, which confirms the cookie fallback.

Request the object with no token
curl https://your-domain.com/files/document.pdf

The function refuses the request with HTTP 401:

JSON
01{
02 "error": "Authentication required",
03 "message": "Provide a valid JWT token in Authorization header or auth_token cookie"
04}

A signed token returns the object, and an absent or unverifiable token returns 401 without reaching the bucket.

Next steps

Create a bucketCreate the bucket this function reads, and set its access level.Use a bucket as an application originServe a bucket through a connector and a rule when the objects need no token.Storage runtime APIEvery method and field of the azion:storage module the handler calls.FunctionsHow a function is built, deployed, and routed on the Azion platform.