auth: issue user identity claims and create limited user tokens from them

Co-authored-by: Camila Belo <camilaibs@gmail.com>
Signed-off-by: Fredrik Adelöw <freben@gmail.com>

plugins/auth-node/api-report.md

@@ -109,6 +109,19 @@ export interface BackstageSignInResult {
   token: string;
 }
 
+// @public
+export interface BackstageTokenPayload {
+  [claim: string]: JsonValue;
+  aud: typeof TokenTypes.user.audClaim;
+  ent: string[];
+  exp: number;
+  iat: number;
+  iss: string;
+  sub: string;
+  typ: typeof TokenTypes.user.typClaim;
+  uip: string;
+}
+
 // @public
 export type BackstageUserIdentity = {
   type: 'user';
@@ -116,6 +129,14 @@ export type BackstageUserIdentity = {
   ownershipEntityRefs: string[];
 };
 
+// @public
+export interface BackstageUserIdentityProofPayload {
+  exp: number;
+  iat: number;
+  sub: string;
+  typ: typeof TokenTypes.limitedUser.typClaim;
+}
+
 // @public (undocumented)
 export type ClientAuthResponse<TProviderInfo> = {
   providerInfo: TProviderInfo;
@@ -639,6 +660,20 @@ export type TokenParams = {
   } & Record<string, JsonValue>;
 };
 
+// @public
+export const TokenTypes: Readonly<{
+  user: Readonly<{
+    typClaim: 'vnd.backstage.user';
+    audClaim: 'backstage';
+  }>;
+  limitedUser: Readonly<{
+    typClaim: 'vnd.backstage.limited-user';
+  }>;
+  service: Readonly<{
+    typClaim: 'vnd.backstage.service';
+  }>;
+}>;
+
 // @public
 export type WebMessageResponse =
   | {

plugins/auth-node/src/index.ts

@@ -29,13 +29,15 @@ export * from './proxy';
 export * from './sign-in';
 export type {
   AuthProviderConfig,
-  AuthProviderRouteHandlers,
   AuthProviderFactory,
+  AuthProviderRouteHandlers,
   AuthResolverCatalogUserQuery,
   AuthResolverContext,
   BackstageIdentityResponse,
   BackstageSignInResult,
+  BackstageTokenPayload,
   BackstageUserIdentity,
+  BackstageUserIdentityProofPayload,
   ClientAuthResponse,
   CookieConfigurer,
   ProfileInfo,
@@ -44,3 +46,4 @@ export type {
   SignInResolver,
   TokenParams,
 } from './types';
+export { TokenTypes } from './types';

plugins/auth-node/src/types.ts

@@ -375,3 +375,100 @@ export type CookieConfigurer = (ctx: {
   secure: boolean;
   sameSite?: 'none' | 'lax' | 'strict';
 };
+
+/**
+ * Core properties of various token types.
+ *
+ * @public
+ */
+export const TokenTypes = Object.freeze({
+  user: Object.freeze({
+    typClaim: 'vnd.backstage.user',
+    audClaim: 'backstage',
+  }),
+  limitedUser: Object.freeze({
+    typClaim: 'vnd.backstage.limited-user',
+  }),
+  service: Object.freeze({
+    typClaim: 'vnd.backstage.service',
+  }),
+});
+
+/**
+ * The payload contents of a valid Backstage JWT token
+ *
+ * @public
+ */
+export interface BackstageTokenPayload {
+  /**
+   * The token type
+   */
+  typ: typeof TokenTypes.user.typClaim;
+
+  /**
+   * The issuer of the token, currently the discovery URL of the auth backend
+   */
+  iss: string;
+
+  /**
+   * The entity ref of the user
+   */
+  sub: string;
+
+  /**
+   * The entity refs that the user claims ownership througg
+   */
+  ent: string[];
+
+  /**
+   * A hard coded audience string
+   */
+  aud: typeof TokenTypes.user.audClaim;
+
+  /**
+   * Standard expiry in epoch seconds
+   */
+  exp: number;
+
+  /**
+   * Standard issue time in epoch seconds
+   */
+  iat: number;
+
+  /**
+   * A separate user identity proof that the auth service can convert to a limited user token
+   */
+  uip: string;
+
+  /**
+   * Any other custom claims that the adopter may have added
+   */
+  [claim: string]: JsonValue;
+}
+
+/**
+ * The payload contents of a valid Backstage user identity claim token
+ *
+ * @public
+ */
+export interface BackstageUserIdentityProofPayload {
+  /**
+   * The token type
+   */
+  typ: typeof TokenTypes.limitedUser.typClaim;
+
+  /**
+   * The entity ref of the user
+   */
+  sub: string;
+
+  /**
+   * Standard expiry in epoch seconds
+   */
+  exp: number;
+
+  /**
+   * Standard issue time in epoch seconds
+   */
+  iat: number;
+}