Supergraf

Denne siden er under utarbeidelse

I supergrafen presenteres dataene i ett samlet API. Dette gjør det mulig for konsumenter å hente og kombinere data fra forskjellige datakilder, eller subgrafer, gjennom ett sentralisert endepunkt. Dermed trenger ikke konsumentene å forholde seg til flere endepunkter for å finne fram til- og hente data.

Med supergrafen kan migrering av data gjøres uten at konsumentene trenger å forholde seg til det. For eksempel kan data flyttes fra å ligge i FS til å ligge i Utdanningsregisteret, men fortsatt framstå som uendret i supergrafen. Ved innføring av nye datakilder/subgrafer, kan data fra disse legges til i supergrafen uten at konsumentene trenger å integrere mot et nytt endepunkt.

Per i dag er følgende subgrafer inkludert:

Tilgjengelighet og kildekode

Supergrafendepunktet er basert på Hive Gateway og kjører i Platon PaaS. Gatewayen er ansvarlig for å rute GraphQL-spørringer til de ulike subgrafenes endepunkter, basert på Apollo Federation 2-protokollen. Supergrafskjemaet hentes fra skjemaregisteret Hive Schema Registry og blir automatisk oppdatert med endringer som skjer der ved publisering av subgrafskjema til supergraf.

Supergrafendepunktet er tilgjengelig i flere miljøer:

Miljø	URL
TEST	https://supergraf-gateway-test.fsweb.no/graphql
DEMO	TBA
PROD	TBA

Kildekoden til supergrafen ligger i supergraf-repoet på GitLab.

Hvordan gjøre en datakilde/subgraf til en del av supergrafen

For å bli en del av supergrafen er du nødt til å oppfylle kravene under og inkludere skjemasjekking og publisering som en del av din pipeline. En subgraf blir automatisk inkludert når man bruker skjemasjekking og publiseringsfunksjonaliteten.

Krav:

URL til subgraf-API - et endepunkt som svarer på GraphQL-spørringer for subgrafen
GraphQL-skjemafil som representerer subgrafen
Sette opp hjelpe-jobber i CI/CD pipeline

Håndtering av endringer i subgraf

For å påse at endringer i en subgraf er trygge og ikke skaper uventede problemer i supergrafen er det laget GitLab CI/CD-jobber som kan brukes i pipeline for å automatisk sjekke og publisere trygge skjemaendringer.

Hjelpejobbene ligger her med dokumentasjon om hvordan de kan brukes.

Prosessen som disse jobbene representerer er todelt:

Sjekker subgrafskjema for feil og brekkende endringer
Publisering av subgrafskjema til supergraf

1 Sjekker subgrafskjema for feil og brekkende endringer

Ved opprettelse av MR blir det kjørt en schema check gjennom Hive - schema registry.

Ved feil i skjemaet eller brekkende endringer vil man se at feilene blir presentert i GitLab som en kommentar på MR-en. Feilene kan også sees sammen med schema diff m.m. i Hive sitt webgrensesnitt*. Dersom en MR fører til skjemaendringer som gir composition errors, altså at skjemaet er ugyldig fordi det inneholder syntaksfeil, eller mer relevant fordi det ikke er kompatibelt med en annen subgraf, så vil pipelinen knekke og bli rød. MR-en ikke kunne merges før dette er rettet.

Resultat fra skjemasjekk i form av kommentar i merge request ser slik ut: MR kommentar som viser feil i skjema

Man kan også se feilene i loggen til skjemasjekk-jobben og mer informasjon i Hive sitt grensesnitt. For å navigere deg dit må du klikke på lenken som vises i jobbens log-output. Skjema-check-job-output

*) Det kreves Hive-bruker for å se dette. Hive støtter SSO, så vi kommer til å se på muligheten for å integrere dette dersom det blir ønskelig.

2. Publisering av subgrafskjema til supergraf

Når MR-en merges til main må vi sørge for at skjemaendringen blir publisert til Hive - schema registry. Dette gjøres ved å inkludere jobber i pipeline som publiserer skjemaendringene til de ulike miljøene i Hive. Det vil typisk være ulike regler for når skjemaet skal publiseres til de ulike miljøene. Jobben som publiserer skjemaet til et gitt miljø må settes til å være avhengig av at jobben som deployer applikasjonen/subgrafen til samme miljø er ferdig, slik at skjemaet ikke blir publisert før subgrafen er deployet med de nye endringene.

Supergrafen blir automatisk oppdatert med endringene etter disse er publisert. Dette er en viktig del av prosessen for å sikre at konsumentene av supergrafen alltid har tilgang til oppdatert skjema.

Autentisering og autorisering

For å kunne gjøre nødvendig tilgangsstyring i grafen trenger vi å autentisere brukere og å autorisere hvilke tilganger de skal ha. Vi bruker Feide for autentisering. Feide har både innebygd autentisering knyttet til institusjoner og en integrasjon med ID-porten. Sistnevnte fungerer også uten at brukeren er tilknyttet en institusjon.

JWT access token

Feide bruker Oauth2. Gjennom autentisering med Feide, også gjennom ID-porten, får vi et JWT access token. Dette kan brukes for å autentisere brukere for datakilder/clienter. Dette tokenet må sendes med i GraphQL-spørringen som en Authorization header.

Under terminering av JWT access token validerer man først tokenet. Dette inkluderer:

å sjekke om tokenet er utgått,
om signatur er gyldig,
om utsteder av tokenet er noen vi stoler på,
og om vi er riktig mottaker av tokenet (audience definert i tokenet).

Mer informasjon

Her er et eksempel på payload i et JWT token:

{
    "aud": "https://n.feide.no/datasources/7360e291-8e0e-4aef-837c-5ba48cb6eb37",
    "jti": "8011475e-ebcf-4a12-a7dc-43b65c81d7d2",
    "iss": "https://auth.dataporten.no",
    "iat": 1736851234,
    "exp": 1736851234,
    "nbf": 1736851234,
    "client_id": "04b32ca3-ab64-4d04-89f2-aa1dca79c4b3",
    "sub": "cd8cb5c9-8410-49d9-8cf2-4b5a7f386a88",
    "scope": "default",
    "act": {
        "sub": "04b32ca3-ab64-4d04-89f2-aa1dca79c4b3",
        "https://n.feide.no/claims/customer_portal_id": "https://n.feide.no/service_ids/123456"
    }
}

Etter at man har validert tokenet så kan man hente ut userinfo fra Feide. Userinfo kan inneholde diverse informasjon, som f.eks. fødselsnummeret til brukeren. For å hente brukerinfo fra Feide kreves det blant annet:

access token
client id
client secret

Client id/secret tilhører datakilden som er autorisert til å userinfo fra Feide med dette tokenet.

For å få tak i et access token, så må man først utføre en token exchange request hvor man sender inn JWT tokenet til Feide, og feide returnerer et access token du kan bruke for å hente userinfo.

Man får bare lov til å hente userinfo som er registrert for denne datakilden i Feide kundeportalen. Når man skal hente userinfo så kan man spesifisere spesifikt hvilke scope man vil ha. Eksempel på scope er "userid-nin" som gir oss fødselsnummeret til brukeren.

Terminering av JWT access token

I nåværende løsning terminerer vi JWT i subgrafene.

Supergraf gjør med andre ord ingenting med token, den videresendes direkte til subgrafene. Subgrafene må derfor ha "client id" og "client secret" til supergrafen for termineringen, og bare supergrafen skal være registrert i Feide som datakilde. På denne måten kan subgrafene hente nødvendig brukerinfo fra Feide. Applikasjonene må derfor ha støtte for at "audience" er supergrafen, slik at JWT tokens ikke feiler under validering.

Nåværende supergraf videresender Authorization header til subgrafene. Her kan du se hvordan supergrafen videresender auth headers:

export const gatewayConfig = defineConfig({
  ...
  propagateHeaders: {
    fromClientToSubgraphs({ request, subgraphName }) {
      if (subgraphName === "admissio") {
        return {
          Authorization: request.headers.get("Authorization"),
          "Sudo-Fodselsnr": request.headers.get("Sudo-Fodselsnr"),
          "Sudo-Organisasjonsnr": request.headers.get("Sudo-Organisasjonsnr")
        };
      } else {
        return {
          Authorization: request.headers.get("Authorization"),
          "Sudo-Fodselsnr": request.headers.get("Sudo-Fodselsnr")
        };
      }
    },
  },
  ...
});

Tilgjengelighet og kildekode​

Hvordan gjøre en datakilde/subgraf til en del av supergrafen​

Håndtering av endringer i subgraf​

1 Sjekker subgrafskjema for feil og brekkende endringer​

2. Publisering av subgrafskjema til supergraf​

Autentisering og autorisering​

JWT access token​

Terminering av JWT access token​