Add Keycloak OIDC token bridge for PixelUnion API access.

Store encrypted refresh tokens per session and expose POST /api/auth/oidc-token so authenticated clients can exchange them for Keycloak access tokens.

Author: jochbru

open-api/immich-openapi-specs.json

@@ -4679,6 +4679,46 @@
         "x-immich-state": "Stable"
       }
     },
+    "/auth/oidc-token": {
+      "post": {
+        "description": "Exchange the stored Keycloak refresh token for a fresh access token for use with PixelUnion APIs.",
+        "operationId": "getOidcToken",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OidcTokenResponseDto"
+                }
+              }
+            },
+            "description": ""
+          }
+        },
+        "security": [
+          {
+            "bearer": []
+          },
+          {
+            "cookie": []
+          },
+          {
+            "api_key": []
+          }
+        ],
+        "summary": "Exchange OIDC access token",
+        "tags": [
+          "Authentication"
+        ],
+        "x-immich-history": [
+          {
+            "version": "v1",
+            "state": "Added"
+          }
+        ]
+      }
+    },
     "/auth/pin-code": {
       "delete": {
         "description": "Reset the pin code for the current user by providing the account password",
@@ -19559,6 +19599,19 @@
         ],
         "type": "object"
       },
+      "OidcTokenResponseDto": {
+        "properties": {
+          "accessToken": {
+            "description": "OIDC access token for use with PixelUnion APIs",
+            "type": "string"
+          },
+          "reauth": {
+            "description": "Whether the user must re-authenticate via OAuth",
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      },
       "OnThisDayDto": {
         "properties": {
           "year": {

server/src/controllers/auth.controller.ts

@@ -9,6 +9,7 @@ import {
   LoginCredentialDto,
   LoginResponseDto,
   LogoutResponseDto,
+  OidcTokenResponseDto,
   PinCodeChangeDto,
   PinCodeResetDto,
   PinCodeSetupDto,
@@ -118,6 +119,19 @@ export class AuthController {
     return this.service.getAuthStatus(auth);
   }
 
+  @Post('oidc-token')
+  @Authenticated()
+  @HttpCode(HttpStatus.OK)
+  @Endpoint({
+    summary: 'Exchange OIDC access token',
+    description:
+      'Exchange the stored Keycloak refresh token for a fresh access token for use with PixelUnion APIs.',
+    history: new HistoryBuilder().added('v1'),
+  })
+  getOidcToken(@Auth() auth: AuthDto): Promise<OidcTokenResponseDto> {
+    return this.service.getOidcToken(auth);
+  }
+
   @Post('pin-code')
   @Authenticated({ permission: Permission.PinCodeCreate })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/dtos/auth.dto.ts

@@ -184,3 +184,11 @@ export class AuthStatusResponseDto {
   @ApiPropertyOptional({ description: 'PIN expiration date' })
   pinExpiresAt?: string;
 }
+
+export class OidcTokenResponseDto {
+  @ApiPropertyOptional({ description: 'OIDC access token for use with PixelUnion APIs' })
+  accessToken?: string;
+
+  @ApiPropertyOptional({ description: 'Whether the user must re-authenticate via OAuth' })
+  reauth?: boolean;
+}

server/src/repositories/crypto.repository.ts

@@ -1,7 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import { compareSync, hash } from 'bcrypt';
 import jwt from 'jsonwebtoken';
-import { createHash, createPublicKey, createVerify, randomBytes, randomUUID } from 'node:crypto';
+import { createCipheriv, createDecipheriv, createHash, createPublicKey, createVerify, randomBytes, randomUUID } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 
 @Injectable()
@@ -66,4 +66,21 @@ export class CryptoRepository {
   verifyJwt<T = any>(token: string, secret: string): T {
     return jwt.verify(token, secret, { algorithms: ['HS256'] }) as T;
   }
+
+  encryptAesGcm(plaintext: string, key: Buffer): Buffer {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, encrypted]);
+  }
+
+  decryptAesGcm(data: Buffer, key: Buffer): string {
+    const iv = data.subarray(0, 12);
+    const tag = data.subarray(12, 28);
+    const encrypted = data.subarray(28);
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    return decipher.update(encrypted) + decipher.final('utf8');
+  }
 }

server/src/repositories/index.ts

@@ -30,6 +30,7 @@ import { OAuthRepository } from 'src/repositories/oauth.repository';
 import { OcrRepository } from 'src/repositories/ocr.repository';
 import { PartnerRepository } from 'src/repositories/partner.repository';
 import { PersonRepository } from 'src/repositories/person.repository';
+import { PixelUnionSessionTokenRepository } from 'src/repositories/pixelunion-session-token.repository';
 import { PluginRepository } from 'src/repositories/plugin.repository';
 import { ProcessRepository } from 'src/repositories/process.repository';
 import { PuApiRepository } from 'src/repositories/pu-api.repository';
@@ -85,6 +86,7 @@ export const repositories = [
   OcrRepository,
   PartnerRepository,
   PersonRepository,
+  PixelUnionSessionTokenRepository,
   PluginRepository,
   ProcessRepository,
   PuApiRepository,

server/src/repositories/oauth.repository.ts

@@ -11,7 +11,9 @@ import {
   None,
   randomPKCECodeVerifier,
   randomState,
+  refreshTokenGrant,
   skipSubjectCheck,
+  tokenRevocation,
   type UserInfoResponse,
 } from 'openid-client';
 import { OAuthTokenEndpointAuthMethod } from 'src/enum';
@@ -113,6 +115,66 @@ export class OAuthRepository {
     }
   }
 
+  async getProfileWithTokens(
+    config: OAuthConfig,
+    url: string,
+    expectedState: string,
+    codeVerifier: string,
+  ): Promise<{ profile: OAuthProfile; refreshToken?: string }> {
+    const client = await this.getClient(config);
+    const pkceCodeVerifier = client.serverMetadata().supportsPKCE() ? codeVerifier : undefined;
+
+    try {
+      const tokens = await authorizationCodeGrant(client, new URL(url), { expectedState, pkceCodeVerifier });
+
+      let profile: OAuthProfile;
+      const tokenClaims = tokens.claims();
+      if (tokenClaims && 'email' in tokenClaims) {
+        this.logger.debug('Using ID token claims instead of userinfo endpoint');
+        profile = tokenClaims as OAuthProfile;
+      } else {
+        profile = await fetchUserInfo(client, tokens.access_token, skipSubjectCheck);
+      }
+
+      if (!profile.sub) {
+        throw new Error('Unexpected profile response, no `sub`');
+      }
+
+      return { profile, refreshToken: tokens.refresh_token };
+    } catch (error: Error | any) {
+      if (error.message.includes('unexpected JWT alg received')) {
+        this.logger.warn(
+          [
+            'Algorithm mismatch. Make sure the signing algorithm is set correctly in the OAuth settings.',
+            'Or, that you have specified a signing key in your OAuth provider.',
+          ].join(' '),
+        );
+      }
+
+      this.logger.error(`OAuth login failed: ${error.message}`);
+      this.logger.error(error);
+
+      throw new Error('OAuth login failed', { cause: error });
+    }
+  }
+
+  async refreshAccessToken(
+    config: OAuthConfig,
+    refreshToken: string,
+  ): Promise<{ accessToken: string; newRefreshToken?: string }> {
+    const client = await this.getClient(config);
+    const tokens = await refreshTokenGrant(client, refreshToken);
+    return {
+      accessToken: tokens.access_token!,
+      newRefreshToken: tokens.refresh_token,
+    };
+  }
+
+  async revokeToken(config: OAuthConfig, token: string): Promise<void> {
+    const client = await this.getClient(config);
+    await tokenRevocation(client, token);
+  }
+
   async getProfilePicture(url: string) {
     const response = await fetch(url);
     if (!response.ok) {

server/src/repositories/pixelunion-session-token.repository.ts

@@ -0,0 +1,30 @@
+import { Injectable } from '@nestjs/common';
+import { Kysely } from 'kysely';
+import { InjectKysely } from 'nestjs-kysely';
+import { DB } from 'src/schema';
+import { asUuid } from 'src/utils/database';
+
+@Injectable()
+export class PixelUnionSessionTokenRepository {
+  constructor(@InjectKysely() private db: Kysely<DB>) {}
+
+  get(sessionId: string) {
+    return this.db
+      .selectFrom('pixelunion_session_token')
+      .select('keycloakRefreshToken')
+      .where('sessionId', '=', asUuid(sessionId))
+      .executeTakeFirst();
+  }
+
+  upsert(sessionId: string, keycloakRefreshToken: Buffer) {
+    return this.db
+      .insertInto('pixelunion_session_token')
+      .values({ sessionId, keycloakRefreshToken })
+      .onConflict((oc) => oc.column('sessionId').doUpdateSet({ keycloakRefreshToken }))
+      .execute();
+  }
+
+  delete(sessionId: string) {
+    return this.db.deleteFrom('pixelunion_session_token').where('sessionId', '=', asUuid(sessionId)).execute();
+  }
+}

server/src/schema/index.ts

@@ -56,6 +56,7 @@ import { PartnerAuditTable } from 'src/schema/tables/partner-audit.table';
 import { PartnerTable } from 'src/schema/tables/partner.table';
 import { PersonAuditTable } from 'src/schema/tables/person-audit.table';
 import { PersonTable } from 'src/schema/tables/person.table';
+import { PixelUnionSessionTokenTable } from 'src/schema/tables/pixelunion-session-token.table';
 import { PluginActionTable, PluginFilterTable, PluginTable } from 'src/schema/tables/plugin.table';
 import { SessionTable } from 'src/schema/tables/session.table';
 import { SharedLinkAssetTable } from 'src/schema/tables/shared-link-asset.table';
@@ -115,6 +116,7 @@ export class ImmichDatabase {
     PartnerTable,
     PersonTable,
     PersonAuditTable,
+    PixelUnionSessionTokenTable,
     SessionTable,
     SharedLinkAssetTable,
     SharedLinkTable,
@@ -224,6 +226,8 @@ export interface DB {
   person: PersonTable;
   person_audit: PersonAuditTable;
 
+  pixelunion_session_token: PixelUnionSessionTokenTable;
+
   session: SessionTable;
   session_sync_checkpoint: SessionSyncCheckpointTable;
 

server/src/schema/migrations/1775200000000-AddPixelUnionSessionToken.ts

@@ -0,0 +1,23 @@
+import { Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await sql`CREATE TABLE "pixelunion_session_token" (
+  "sessionId" uuid NOT NULL,
+  "keycloakRefreshToken" bytea NOT NULL,
+  "createdAt" timestamp with time zone NOT NULL DEFAULT now(),
+  "updatedAt" timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT "pixelunion_session_token_pkey" PRIMARY KEY ("sessionId"),
+  CONSTRAINT "pixelunion_session_token_sessionId_fkey" FOREIGN KEY ("sessionId") REFERENCES "session" ("id") ON UPDATE CASCADE ON DELETE CASCADE
+);`.execute(db);
+  await sql`CREATE OR REPLACE TRIGGER "pixelunion_session_token_updatedAt"
+  BEFORE UPDATE ON "pixelunion_session_token"
+  FOR EACH ROW
+  EXECUTE FUNCTION updated_at();`.execute(db);
+  await sql`INSERT INTO "migration_overrides" ("name", "value") VALUES ('trigger_pixelunion_session_token_updatedAt', '{"type":"trigger","name":"pixelunion_session_token_updatedAt","sql":"CREATE OR REPLACE TRIGGER \\"pixelunion_session_token_updatedAt\\"\\n  BEFORE UPDATE ON \\"pixelunion_session_token\\"\\n  FOR EACH ROW\\n  EXECUTE FUNCTION updated_at();"}'::jsonb);`.execute(db);
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await sql`DROP TRIGGER "pixelunion_session_token_updatedAt" ON "pixelunion_session_token";`.execute(db);
+  await sql`DROP TABLE "pixelunion_session_token";`.execute(db);
+  await sql`DELETE FROM "migration_overrides" WHERE "name" = 'trigger_pixelunion_session_token_updatedAt';`.execute(db);
+}

server/src/schema/tables/pixelunion-session-token.table.ts

@@ -0,0 +1,19 @@
+import { Column, CreateDateColumn, ForeignKeyColumn, Generated, Table, Timestamp, UpdateDateColumn } from '@immich/sql-tools';
+import { UpdatedAtTrigger } from 'src/decorators';
+import { SessionTable } from 'src/schema/tables/session.table';
+
+@Table('pixelunion_session_token')
+@UpdatedAtTrigger('pixelunion_session_token_updatedAt')
+export class PixelUnionSessionTokenTable {
+  @ForeignKeyColumn(() => SessionTable, { onDelete: 'CASCADE', onUpdate: 'CASCADE', primary: true })
+  sessionId!: string;
+
+  @Column({ type: 'bytea' })
+  keycloakRefreshToken!: Buffer;
+
+  @CreateDateColumn()
+  createdAt!: Generated<Timestamp>;
+
+  @UpdateDateColumn()
+  updatedAt!: Generated<Timestamp>;
+}