Ge en medarbetare åtkomst till Kvarts

01

API-användare och SSO-konton

kvarts user add hanterar besökare. Det skapar inte en publiceringsnyckel. Rauthy-inloggning ger inte automatiskt åtkomst till https://api.kvarts.network.

Den här guiden använder en befintlig kund och ett befintligt projekt. Skapa inte en ny kundorganisation åt varje medarbetare. En administratör behöver create:user och create:key, åtkomst till den valda kunden och projektet samt de rättigheter som ska delegeras. En installationsadministratör kan också utföra stegen.

02

Välj rätt projekt och rättigheter

Bestäm kund-ID, projekt-ID, personens användarnamn och nyckelns giltighetstid. Använd en projektnyckel när personen ska få skapa och publicera sidor inom ett projekt. En nyckel för en enda befintlig sida kan i stället begränsas till scope_type: "site" och sidans ID.

Exemplet ger möjlighet att ändra åtkomstregler inom projektet. Utelämna update:config om personen enbart ska uppdatera innehåll och inte hantera en malm.yaml. Lägg bara till delete:file om personen ska kunna rensa filer, och update:site om personen även ska hantera besökarkonton. Dela inte ut * eller rätt att skapa nycklar för vanlig publicering.

03

Skapa plattformsanvändare och API-nyckel

Följande skript använder de befintliga API-anropen POST /users och POST /keys. Det återanvänder en användare med samma namn inom kunden och skapar en projektnyckel som gäller i 90 dagar. För ett nytt konto genererar det ett slumpmässigt plattformslösenord; det är inte personens Rauthy-lösenord. Rollen admin är en befintlig plattformsroll, medan nyckelns omfattning och rättigheter begränsar API-åtkomsten.

Kräver Bun. Spara skriptet som create-api-user.ts lokalt utanför en webbplatsmapp:

const api = "https://api.kvarts.network";
const adminKey = process.env.MALM_ADMIN_API_KEY;
const clientID = process.env.KVARTS_CLIENT_ID;
const projectID = process.env.KVARTS_PROJECT_ID;
const username = process.env.KVARTS_USERNAME;
if (!adminKey || !clientID || !projectID || !username) {
  throw new Error("Ange administratörsnyckel, kund-ID, projekt-ID och användarnamn");
}

async function request(path: string, body?: unknown) {
  const headers: Record<string, string> = { "X-API-Key": adminKey! };
  if (body !== undefined) {
    headers["Content-Type"] = "application/json";
    headers["Idempotency-Key"] = crypto.randomUUID();
    console.error("Request-ID:", headers["Idempotency-Key"], path);
  }
  const response = await fetch(api + path, {
    method: body === undefined ? "GET" : "POST",
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
    redirect: "error",
    signal: AbortSignal.timeout(30000),
  });
  if (!response.ok) throw new Error(path + ": HTTP " + response.status);
  return response.json();
}

const projects = await request("/clients/" + encodeURIComponent(clientID) + "/projects");
if (!projects?.some((project: any) => project.id === projectID)) {
  throw new Error("Projektet tillhör inte den valda kunden");
}
const users = await request("/clients/" + encodeURIComponent(clientID) + "/users");
let user = users?.find((item: any) => item.username === username);
if (!user) {
  user = await request("/users", {
    client_id: clientID,
    username,
    password: crypto.randomUUID() + crypto.randomUUID(),
    role: "admin",
  });
}
const result = await request("/keys", {
  user_id: user.id,
  name: username + " / publicering",
  scope_type: "project",
  scope_id: projectID,
  permissions: ["read:project", "create:site", "list:files",
    "upload:file", "update:config"],
  expires_at: new Date(Date.now() + 90 * 86400000).toISOString(),
});
if (!result.access_key) throw new Error("Ingen ny hemlig nyckel returnerades");
// Nyckeln visas bara här. Spara den i er godkända lösenordshanterare.
console.log(JSON.stringify(result, null, 2));

Läs in din administratörsnyckel lokalt och ange rätt ID:n. Byt ut alla exempelvärden. Inmatningen av nyckeln är dold i bash och zsh:

read -r -s MALM_ADMIN_API_KEY
export MALM_ADMIN_API_KEY
export KVARTS_CLIENT_ID="KUND_ID"
export KVARTS_PROJECT_ID="PROJEKT_ID"
export KVARTS_USERNAME="fornamn.efternamn@whitespace.se"
bun create-api-user.ts

Svaret innehåller key_id och den hemliga access_key, som bara returneras vid skapandet. Spara nyckeln direkt i er godkända lösenordshanterare och dela den med rätt person där. Skicka även projekt-ID och installationsguiden. Medarbetaren använder sin nyckel som MALM_API_KEY, inte administratörsnyckeln.

Skriptet skriver ett Request-ID för varje skapande. Vid ett avbrott kan en användare eller nyckel redan ha skapats. Kontrollera GET /clients/{kund-id}/users och GET /projects/{projekt-id}/keys före ett nytt försök. Samma anrop med samma Idempotency-Key undviker dubbel skapning, men en återspelning kan inte lämna ut den hemliga nyckeln igen. En borttappad nyckel behöver spärras och ersättas.

04

Kontrollera och avsluta API-åtkomst

Låt medarbetaren kontrollera GET /whoami, GET /projects eller kvarts list --project-id PROJEKT_ID med sin egen nyckel. Kontrollera att rätt projekt visas och att en publicering med ofarligt testinnehåll fungerar när ni vill göra ett praktiskt test.

Lista nycklarnas metadata med GET /projects/{projekt-id}/keys. Administratören kan återkalla en nyckel med DELETE /keys/{key_id}, vilket kräver delete:key och rätt omfattning. API-nycklar kan också ha ett utgångsdatum. Ge en ny personlig nyckel när den gamla behöver ersättas.

Att spärra ett Rauthy-konto eller köra kvarts user disable återkallar inte personens API-nycklar. Hantera båda typerna av åtkomst när någon byter uppdrag eller slutar.

05

Ge även åtkomst till en skyddad sida

Använd en nyckel med update:site för rätt omfattning. Följande är ett exempel med sidan min-proxy, gruppen medarbetare och ett nytt Rauthy-konto. Byt ut namn, sida och e-post:

kvarts user add fornamn.efternamn --site min-proxy \
  --email fornamn.efternamn@whitespace.se --group medarbetare

Personen får ett mejl från identitetstjänsten för att slutföra kontot. Om personen redan finns i Rauthy ska du i stället koppla det befintliga kontot:

kvarts user add fornamn.efternamn --site min-proxy \
  --email fornamn.efternamn@whitespace.se --group medarbetare --link-existing

Välj ett av dessa två skapandekommandon, inte båda. --site begränsar besökarkontot till en sida; --project eller --client ger bredare omfattning. Gruppnamnet måste stämma med sidans regler, exempelvis:

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

Kontrollera kontot och ändra en befintlig besökares grupp med:

kvarts user status fornamn.efternamn --site min-proxy
kvarts user groups fornamn.efternamn --site min-proxy --add medarbetare

Gör gruppändringar och spärrning via Kvarts, så att även dess sessionsinformation uppdateras. Testa därefter inloggningen med personens eget konto. Se integrationsguiden om tjänsten bakom proxyn också ska skapa ett lokalt konto.