Sudo og tilgangsstyring-tokenet

I test, review og lokalt kan en klient opptre som en syntetisk bruker ved hjelp av sudo-headere. Coprocessoren i supergrafen gjør headerne om til det interne tilgangsstyring-tokenet, det samme tokenet subgrafene får i alle miljøer i headeren supergraph-authorization. Av sikkerhetsmessige årsaker stopper supergrafen sudo-headerne, så de sendes ikke videre til subgrafene. Subgrafen får bare tokenet, og trenger aldri å lese sudo-headerne selv.

Siden har to deler. Den første er for deg som sender forespørsler med sudo, for eksempel fra FS Admin, en testklient eller studieadm-cli. Den andre er for deg som eier en subgraf.

For arkitekturen, tokenet og hvorfor alt styres fra produksjon, se Tilgangsstyring.

Hvor sudo virker

Hvor sudo virker

Miljø	Sudo-headere
test, review, local	Gjøres om til tilgangsstyring-tokenet
production, demo	Avvises med 400 før forespørselen når noen subgraf

Sudo gir aldri tilgang på egen hånd. Forespørselen må ha en gyldig Authorization-header som ellers, og sudo-headerne leses først etter at innloggingen er godkjent. Det eneste unntaket er lokal kjøring med studieadm-cli.

Del 1: Slik bruker du sudo

De fire headerne

De fire headerne

Header	Hva den gjør
sudo-fodselsnr	Påtar seg identiteten til en syntetisk person. Blir nin i tokenet.
sudo-username	Påtar seg identiteten med en Feide-ID. Blir email i tokenet.
sudo-organisasjonskode	Hjemmeorganisasjonen til personaen, for eksempel 7777. Gir ingen tilgang, og leses bare sammen med en av de to over.
sudo-orgtilganger	Tilgangene personaen skal ha, som organisasjonskode:rollekode-par. Behandles som en ekte tildeling.

Dette er hele flaten. Enhver annen header som heter sudo eller begynner på sudo- avvises, også med tom verdi. Headernavn er uavhengige av store og små bokstaver, som alle HTTP-headere.

De to første headerne påtar seg en identitet. sudo-orgtilganger endrer bare tilganger. Setter du den alene, beholder den innloggede brukeren sin egen identitet bare hvis brukeren er syntetisk. Ekte identiteter sendes aldri videre til subgrafene i et syntetisk miljø.

Avviklede navn

sudo-roller er erstattet av sudo-orgtilganger, og sudo-organisasjonsnr av sudo-organisasjonskode. De gamle navnene avvises med 400, og feilmeldingen navngir erstatningen. Formatet er også nytt, se under.

Formatet på sudo-orgtilganger

sudo-orgtilganger: 7777:STUDENTDATA_LES1,7777:PERSONDATA_LES1,7778:STUDENTDATA_LES1

• Flere roller i samme organisasjon oppgis som gjentatte par.
• Rollekoder med norske tegn må prosentkodes, for eksempel 7777:FS-ADMIN_OPPTAK_S%C3%98KNADSBEHANDLER. En rå Ø i en HTTP-header stopper i routeren.
• Et tomt sett avvises.
• Rollene behandles som en ekte tildeling: de utvides med rollene de impliserer, og begrenses av applikasjonens tak. Du kan derfor få både flere og færre roller i tokenet enn du ba om.

Kravet til sudo-fodselsnr

Fødselsnummeret må være syntetisk: fra Skatteetatens testserie (måned pluss 80, slik Tenor lager dem) eller generert av FS. Et nummer som kan tilhøre et ekte menneske avvises med 400.

Når flere headere er satt

sudo-orgtilganger går foran sudo-username, som går foran den faktiske innloggingen. Den som taper, ignoreres.

Eksempel

curl https://api-test.fsweb.no/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "sudo-fodselsnr: 01880012345" \
  -H "sudo-organisasjonskode: 7777" \
  -H "sudo-orgtilganger: 7777:STUDENTDATA_LES1,7777:PERSONDATA_LES1" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

$TOKEN er et vanlig token for testmiljøet, se Autentisering. Subgrafene får et tilgangsstyring-token med nin lik 01880012345, orgtilganger for organisasjon 7777 og amr lik ["sudo"].

Feilsvar

Svaret er et GraphQL-feilsvar med Content-Type: application/graphql-response+json og feilkoden BAD_REQUEST. Meldingen navngir headeren, men aldri verdien.

Feilsvar

Situasjon	Status	Melding
Authorization mangler eller godkjennes ikke	401	Sudo-headerne leses ikke
Sudo-header i production eller demo	400	Ugyldig forespørsel: sudo-headere er bare tillatt i syntetiske miljø
Avviklet navn	400	Ugyldig forespørsel: Sudo-Roller er avviklet — bruk Sudo-Orgtilganger
Ukjent navn	400	Ugyldig forespørsel: ukjent sudo-header «…». Kjente: …
Feil format på sudo-orgtilganger	400	Ugyldig forespørsel: Sudo-Orgtilganger har ugyldig format
sudo-fodselsnr som kan være ekte	400	Ugyldig forespørsel: Sudo-Fodselsnr er ikke en syntetisk identitet

Lokalt med studieadm-cli

studieadm-cli local up kjører supergrafen på din egen maskin, mot coprocessoren i produksjon og med miljøet local. Reglene er de samme som i test, med ett unntak: en forespørsel uten Authorization slipper gjennom, fordi en lokal supergraf ikke kan nås fra internett.

• Uten sudo-headere får tokenet da ingen identitet og tomme tilganger, og amr er ["anonymous"].
• Med sudo-orgtilganger er sudo-settet hele tilgangen.
• Takene og gulvene for local er en kopi av dem i test.

Kall som går rett mot en subgraf på maskinen din, utenom supergrafen, går ikke gjennom coprocessoren. Se Direkte mot subgrafen.

Del 2: Slik leser subgrafen tokenet

Hva tokenet bærer

Hva tokenet bærer

Tilfelle	sub	name, email, nin	amr
production og demo	Feide-subjektet	Fra Feide	["feide"]
Syntetisk miljø, syntetisk person	Feide-subjektet	Fra Feide	["feide"]
Syntetisk miljø, ekte person	sudo	Utelates	["feide"]
Sudo	sudo	Fra sudo-headerne	["sudo"]

En ekte person som logger inn i test får altså ingen identitet i tokenet. Skal vedkommende se en identitet der, må den oppgis med sudo-fodselsnr. amr er sudo bare når en identitet er påtatt. Med sudo-orgtilganger alene gjelder raden for den faktiske innloggingen.

Eksempel på token ved sudo:

{
  "iss": "tilgangsstyring",
  "aud": ["test"],
  "sub": "sudo",
  "iat": 1737846000,
  "exp": 1737849600,
  "client_id": "04b32ca3-ab64-4d04-89f2-aa1dca79c4b3",
  "amr": ["sudo"],
  "email": "test.student@uio.no",
  "nin": "01880012345",
  "orgtilganger": {
    "7777": ["STUDENTDATA_LES1", "PERSONDATA_LES1"]
  }
}

Tokenet har ikke noe act-claim med den ekte brukeren. Sporingen tilbake til den som opptrådte som personaen, ligger i coprocessorens logg.

Ingen sudo-headere gjennom supergrafen

Routeren videresender ikke sudo-headere til subgrafene. Alt subgrafen trenger, står i tokenet. Les aldri en sudo-header når tokenet finnes.

Claimene du trenger

Claimene du trenger

Spørsmål	Claim
Hvem er brukeren?	nin. Kan mangle: maskinbruker, ekte person i syntetisk miljø, eller anonym lokalt.
Hva har brukeren tilgang til?	orgtilganger, et objekt fra organisasjonskode til liste av rollekoder.
Er identiteten påtatt?	amr inneholder sudo.
Er forespørselen anonym?	amr inneholder anonymous. Forekommer bare lokalt.

Bruk ikke sub som identitet for personer. Den er sudo i flere av tilfellene over.

Med MicroProfile JWT, slik oppskriften for MP-JWT og Postgres setter det opp:

JsonWebToken jwt = jwtInstance.get();

String nin = jwt.getClaim("nin");
JsonObject orgtilganger = jwt.getClaim("orgtilganger");
JsonArray amr = jwt.getClaim("amr");

boolean paatattIdentitet = amr.getValuesAs(JsonString.class).stream()
        .anyMatch(v -> "sudo".equals(v.getString()));

Trenger subgrafen å behandle sudo annerledes, for eksempel hoppe over provisjonering av en bruker som ikke finnes, er amr stedet å se. Headerne er ikke der.

Direkte mot subgrafen

Integrasjonstester og GraphiQL rett mot subgrafen går ikke gjennom supergrafen, og det finnes ingen coprocessor som lager et token. Der kan subgrafen lese sudo-headerne selv, og bruke dem til å bygge den samme brukerkonteksten som tokenet ville gitt. To regler gjelder:

• Lesingen er bare aktiv når miljøet er merket som syntetisk (application.environment.synthetic=true). I produksjon leses ingenting.
• Finnes tokenet, vinner tokenet. Sudo-headerne er en erstatning når tokenet mangler, aldri en overstyring av det.

Bruk de samme fire navnene som over, så virker tester og eksempler likt uansett om de går gjennom supergrafen eller ikke.

Sjekkliste for subgraf-eiere

1. Leser subgrafen en sudo-header når supergraph-authorization finnes? Fjern lesingen, eller gjør den betinget av at tokenet mangler.
2. Avgjør subgrafen noe ut fra at en sudo-header finnes, for eksempel om en bruker skal provisjoneres? Les amr fra tokenet i stedet.
3. Bruker kode, tester eller klienter sudo-roller eller sudo-organisasjonsnr? Bytt til sudo-orgtilganger og sudo-organisasjonskode, og til det nye formatet.
4. Leser subgrafen sudo-headere ved direktekall bare når miljøet er syntetisk?

Overgang

Reglene over innføres trinnvis. Først avvises sudo-headere i production og demo med 400. Deretter gir avviklede og ukjente navn 400 også i test, review og local, og routeren slutter å videresende de gamle sudo-headerne til subgrafene. Fram til da gir avviklede navn bare en advarsel i coprocessoren. Rett subgrafen og klientene dine nå, og si fra til team BAT når det er gjort. Bruken av sudo-headere i alle miljøer vises i Grafana-dashboardet Tilgangsstyring: sudo-headere.

Se også

• Tilgangsstyring: arkitektur og tokenet
• Koble en subgraf på tilgangsstyringen med MP-JWT og Postgres
• Supergraf