Logga in användare i tjänsten bakom proxyn

01

Från SSO till din applikation

1. Besökaren öppnar en skyddad adress genom Kvarts och loggar in via Rauthy.
2. Kvarts kontrollerar sessionen och sidans åtkomstregler.
3. Proxyn skickar ett signerat JWT i HTTP-headern X-Malm-Identity till din server.
4. Din server verifierar intyget, hittar eller skapar ett lokalt konto och tillämpar applikationens egna behörigheter.

Integrationen använder X-Malm-Identity. Du ska inte skicka vidare en Rauthy-token eller anta att en vanlig Authorization-header innehåller den här identiteten. Headernamnet och prefixet MALM_ finns kvar av kompatibilitetsskäl.

Headern tillkommer på godkända, skyddade proxyförfrågningar när signering är aktiverad. Den är ingen funktion för enbart statiska filer och skapar inte konton i målsystemet av sig själv.

02

Förbered proxyn och servern

Be Kvarts-administratören bekräfta att identitetssignering är aktiverad på både kontrollplanet och Edge Auth. Din server behöver webbplatsens beständiga ID, förväntad utfärdare och signeringens publika RSA-nyckel i PEM-format. Den privata nyckeln stannar i Kvarts.

I produktionskonfigurationen är utfärdaren https://kvarts.network. Det är Kvarts som utfärdar intyget till din tjänst. Rauthys egna signeringsnycklar och utfärdare hör till det föregående SSO-steget.

Skydda de adresser som använder inloggningen, exempelvis hela proxyn:

auth_methods: [oidc]
auth:
  - path: "/*"
    allowed_groups: [medarbetare]

Reglerna ligger i filen malm.yaml, även efter namnbytet. Se administratörsguiden för hur ett konto kopplas till rätt sida och grupp. Ändra proxyns konfiguration genom ert befintliga publiceringsflöde.

Använd HTTPS med certifikatkontroll mellan Kvarts och målsystemet och begränsa direkt åtkomst till ursprungsservern. Logga inte intyget och skicka det inte till webbläsaren. Det är läsbart, inte krypterat, och en stulen token kan återanvändas under sin korta giltighetstid.

03

Verifiera identitetsintyget

Intyget är signerat med RS256, har typen malm-identity+jwt och är giltigt i högst 30 sekunder. Kontrollera signatur, utfärdare, mottagare, typ och tider med ett JWT-bibliotek. Att enbart avkoda innehållet är inte verifiering.

Följande Bun/TypeScript-exempel använder biblioteket jose. Installera det i din serverapplikation med bun add jose. Sätt KVARTS_SITE_ID och KVARTS_PUBLIC_KEY_FILE i serverns miljö. Dessa två namn är exempel för din applikation, inte nya Kvarts-inställningar.

import { importSPKI, jwtVerify } from "jose";

const issuer = "https://kvarts.network";
const siteID = process.env.KVARTS_SITE_ID;
const keyFile = process.env.KVARTS_PUBLIC_KEY_FILE;
if (!siteID || !keyFile) throw new Error("Identitetskonfiguration saknas");
const publicKey = await importSPKI(await Bun.file(keyFile).text(), "RS256");

export async function verifyKvartsIdentity(request: Request) {
  const token = request.headers.get("X-Malm-Identity");
  // Ett JWT i kompakt format. Sammanfogade värden avvisas.
  if (!token || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token)) {
    throw new Error("Identitetsintyg saknas eller är felaktigt");
  }
  const { payload } = await jwtVerify(token, publicKey, {
    algorithms: ["RS256"],
    typ: "malm-identity+jwt",
    issuer,
    audience: siteID,
    clockTolerance: 5,
    maxTokenAge: 35,
    requiredClaims: ["iss", "sub", "aud", "iat", "exp", "jti",
      "user_id", "username", "site_id", "groups"],
  });
  const now = Math.floor(Date.now() / 1000);
  if (payload.site_id !== siteID || payload.user_id !== payload.sub
      || typeof payload.sub !== "string" || !payload.sub
      || typeof payload.username !== "string" || !payload.username
      || typeof payload.jti !== "string" || !payload.jti
      || typeof payload.iat !== "number" || typeof payload.exp !== "number"
      || payload.iat > now + 5 || payload.exp <= payload.iat
      || payload.exp - payload.iat > 30
      || !Array.isArray(payload.groups)
      || !payload.groups.every(group => typeof group === "string")) {
    throw new Error("Ogiltiga identitetsuppgifter");
  }
  return {
    issuer,
    subject: payload.sub,
    username: payload.username,
    groups: payload.groups as string[],
    email: payload.email_verified === true && typeof payload.email === "string"
      ? payload.email : undefined,
  };
}

Hantera verifieringsfel i din HTTP-hanterare med ett nekande svar, exempelvis 401, utan att skriva ut token. Din HTTP-server ska avvisa flera identitetshuvuden innan de eventuellt slås ihop. Exemplet avvisar även sammanfogade värden.

Kvarts skickar också Remote-User, Remote-Groups och Remote-Scope. De är inte signerade var för sig. Använd det verifierade intyget för kontokopplingen. Principerna för algoritm, utfärdare och mottagare beskrivs i JWT Best Current Practices, RFC 8725.

04

Hitta eller skapa ett lokalt konto

Efter verifieringen använder du kombinationen issuer och subject som en unik extern identitet i databasen. subject är Kvarts-kontots ID, inte Rauthys interna användar-ID. Användarnamn och e-post kan ändras.

1. Sök efter en befintlig koppling till (issuer, subject).
2. Om kopplingen saknas, skapa ett lokalt konto med lägsta nödvändiga behörighet och spara kopplingen i samma databastransaktion. Lägg ett unikt villkor på kombinationen så att samtidiga förfrågningar inte skapar dubbletter.
3. Skapa eller uppdatera applikationens session enligt dess vanliga rutiner. Byt sessions-ID vid inloggning.
4. Översätt bara uttryckligen godkända grupper till lokala roller. En grupp eller ett inloggat konto ska inte automatiskt ge administratörsbehörighet.

Återanvänd inte ett befintligt konto enbart för att användarnamnet matchar. En eventuell koppling via verifierad e-post behöver en beslutad, kontrollerad rutin, särskilt för befintliga administratörskonton.

Repot innehåller exempel för WordPress och Matomo. De visar anpassningar till respektive system. Granska kontokoppling, sessioner och rollmappning för er tjänst innan ni använder dem.

05

Testa åtkomst och utloggning

• En godkänd SSO-användare får rätt lokalt konto. Nästa besök ger samma konto.
• Saknad, ändrad eller utgången token nekas, liksom fel webbplats-ID, utfärdare eller signeringsnyckel.
• En användare utan rätt grupp nekas. Testa också direkt mot ursprungsadressen och med en egen påhittad identitetsheader.
• Utloggning och indragen åtkomst fungerar även om applikationen har en egen sessionscookie.

En lokal session kan leva längre än Kvarts-sessionen. Fortsätt därför kräva giltig Kvarts-identitet på skyddade förfrågningar, eller bestäm en begränsad livslängd och hur sessionen återkallas. Edge Auth kan dessutom ha en kort fördröjning innan en indragen behörighet slår igenom. JWT-intygets 30 sekunder ersätter inte den policyn.