Zuplo Identity Token

Each deployment of Zuplo is issued a unique OAuth client identity. This identity can be used to create ID Tokens that can be used to securely identify requests from your Zuplo API that are made to outside services. This is token can also be used for purposes such as Identity Federation to securely call APIs in other Cloud Services like GCP or AWS.

To create a Zuplo Identity Token simply run the following code from withing a policy, handler, or module in your Zuplo API.

import { ZuploServices, ZuploContext, ZuploRequest } from "@zuplo/runtime";
 
export default async function handler(
  request: ZuploRequeset,
  context: ZuploContext,
) {
  const idToken = await ZuploServices.getIDToken(context, {
    audience: "https://my-api.example.com",
  });
}

The audience argument is optional, but typically this is set to a value identifying the service you are calling.

The issued JWT token contains the following claims.

Securing Your Backend#

The Zuplo ID Token can be used as a means of securing your backend API so that only Zuplo can call the API. This can be done by restricting the incoming requests using a standard OAuth middleware on your API. For example, if you were using Fastify on your backend, you could use the Fastify JWT Middlware using the JWKS verification method and checking the account, project, or other claims.

Verifying the Token Using a Library#

To verify the JWT token on your own service, you can use any standard JWT library. The verification method will use the JWKS hosted at https://dev.zuplo.com/v1/client-auth/auth_o8PUdhKxSTOiB794GWPwLQCD/.well-known/jwks.json. You can also use OAuth tools that handle automatic discovery.

Below is an example of how to verify the token using the jose Javascript library.

import jose from "jose";
 
// Create the Remote JWK set
const JWKS = jose.createRemoteJWKSet(
  new URL(
    "https://dev.zuplo.com/v1/client-auth/auth_o8PUdhKxSTOiB794GWPwLQCD/.well-known/jwks.json",
  ),
);
 
// Verify the token
const { payload, protectedHeader } = await jose.jwtVerify(jwt, JWKS, {
  issuer: "https://dev.zuplo.com/v1/client-auth/auth_o8PUdhKxSTOiB794GWPwLQCD",
  audience: "https://my-api.example.com",
});
 
// Verify the token is from your account/project/etc.
if (
  payload["account"] !== "my-account" ||
  payload["project"] !== "my-project"
) {
  throw new Error("Not my account or project");
}