Autentisering

All bruk av FS GraphQL API krever autentisering, selv om man bare skal hente offentlige data.

Vi støtter fire hovedtyper av autentisering:

Type	Beskrivelse	Bruksområde
Basic auth	Enkel system-til-system autentisering	Klassiske integrasjoner hvor en applikasjon henter data på vegne av institusjonen
Feide (OIDC)	Moderne brukerautentisering	Applikasjoner hvor en sluttbruker logger inn og handler på egne vegne
Feide (OAuth2)	Moderne system-til-system-autentisering	Automatiserte prosesser og integrasjoner uten sluttbruker som ønsker sikker, moderne autentisering
Maskinporten	System-til-system-autentisering med signert JWT grant	Integrasjoner uten sluttbruker, for virksomheter som ikke har Feide

Anbefalinger

Vi anbefaler at så mange som mulig benytter seg av moderne autentisering med Feide hvor sluttbrukeren blir en del av autentiseringsflyten. Dette gjør det mulig for APIene våre å opprettholde høy datasikkerhet, siden vi kan kontrollere tilgang basert på hvem brukeren er.

Basic auth egner seg best for:

• Batch-jobber og automatiserte prosesser
• Integrasjoner som ikke har en sluttbruker involvert
• Enkel testing og utvikling

---

Hvordan får jeg tilgang?

Før du kan autentisere deg mot API-et, må du ha fått tildelt tilgang. Prosessen er forskjellig avhengig av om du skal bruke basic auth, Feide eller Maskinporten.

Oversikt over tilgangsprosessen

Oversikt over tilgangsprosessen

Autentiseringsmetode	Hvem kan gi tilgang	Selvbetjent?
Basic auth	FS-institusjonen (din lokale FS-administrator) eller Sikt	Nei - må bestilles
Feide (OIDC)	Feide Kundeportal + godkjenning fra Sikt	Delvis - se under
Maskinporten	Digdirs selvbetjening + Sikt, etter godkjenning fra FS-institusjonen	Delvis - se under

For basic auth

1. Kontakt din FS-institusjon - Alle data i FS eies av institusjonene. Du må derfor først få godkjenning fra institusjonen du ønsker å hente data fra.

2. Institusjonen bestiller tilgang - Institusjonens FS-kontakt kan:

   • Delegere tilgang direkte (hvis institusjonen har mulighet til dette)
   • Bestille bruker og tilganger via nettskjema på fellesstudentsystem.no

3. Motta brukernavn og passord - Når tilgangen er opprettet, får du tildelt brukernavn og passord.

Databehandleravtale

Vi forutsetter at nødvendige databehandleravtaler er inngått mellom deg og institusjonen før tilgang blir bestilt.

For Feide (OIDC)

1. Registrer din tjeneste i Feide Kundeportal (selvbetjent)

   • Gå til Feide Kundeportal og følg Feides veiledning for registrering av tjeneste
   • Velg om du logger inn som vertsorganisasjon eller tjenesteleverandør
   • Registrer en ny tjeneste med OIDC-konfigurasjon
   • Sett opp Client ID, Client Secret og Redirect URI

2. Be om tilgang til datakilden "Felles studentsystem" (krever godkjenning)

   • I Feide Kundeportal, søk om tilgang til datakilden
   • Velg enten "Data for student" eller "Data for ansatt" avhengig av ditt behov
   • Send en epost til kontakt@sikt.no og be om at forespørselen blir godkjent

3. Vent på godkjenning fra Sikt

   • Vi vurderer søknaden og gir tilbakemelding
   • Ved godkjenning får din tjeneste tilgang til de aktuelle scopene

For Maskinporten

1. Opprett en integrasjon i Maskinporten (selvbetjent)

   • Følg Digdirs veiledning for API-konsumenter
   • Integrasjonen får en client_id (en UUID), som du trenger i neste steg

2. Kontakt din FS-institusjon - Som for basic auth må institusjonen du vil hente data fra, godkjenne bruken.

3. Institusjonen bestiller tilgang - Institusjonens FS-kontakt bestiller registrering og tilganger hos Sikt via kontakt@sikt.no. Oppgi:

   • client_id fra Maskinporten-integrasjonen
   • Organisasjonsnummeret til virksomheten din på ISO 6523-form (for eksempel 0192:991825827)

4. Sikt registrerer applikasjonen i FS Admin og tildeler tilgangene institusjonen har godkjent, per organisasjon og miljø.

Selvbetjening for institusjonene

Foreløpig er det bare Sikt som kan registrere applikasjoner. Institusjonene vil senere kunne registrere applikasjoner og tildele tilganger selv i FS Admin.

Trenger du hjelp?

Kontakt kontakt@sikt.no dersom du trenger veiledning om tilgangsprosessen eller har spørsmål om hvilken autentiseringsmetode som passer for ditt behov.

---

Basic auth

Basic auth er den enkleste måten å autentisere seg mot FS GraphQL API. Du sender brukernavn og passord som en Base64-kodet streng i Authorization-headeren.

Slik bruker du basic auth

1. Få tildelt brukernavn og passord fra din FS-administrator eller via tilgangsbestilling

2. Kod brukernavnet og passordet til Base64:

   Base64(<brukernavn>:<passord>)

3. Send med Authorization-headeren i alle forespørsler:

   POST https://api.fellesstudentsystem.no/graphql/
   Authorization: Basic <Base64-kodet brukernavn:passord>
   Content-Type: application/json
   
   {"query":"{ __typename }","variables":{}}

Eksempel med curl

curl -X POST https://api.fellesstudentsystem.no/graphql/ \
  -H "Authorization: Basic $(echo -n 'brukernavn:passord' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}'

Begrensninger

• Basic auth gir tilgang basert på hva som er konfigurert for brukeren/integrasjonen
• Det er ikke mulig å begrense tilgang basert på sluttbruker
• Passordet må holdes hemmelig og bør ikke eksponeres i klientside-kode

---

Feide (OIDC)

For applikasjoner hvor en sluttbruker logger inn, anbefaler vi å bruke Feide. Dette gir bedre sikkerhet og gjør det mulig å tilpasse datatilgang basert på hvem brukeren er.

Forutsetninger

For å følge denne oppskriften må du ha fullført tilgangsprosessen for Feide beskrevet over. Du trenger:

• Client ID og Client Secret fra din tjeneste i Feide Kundeportal
• Redirect URI after login satt til din callback-URL (f.eks. http://localhost:3000/auth/callback)
• Godkjent tilgang til datakilden Felles studentsystem

Overordnet flyt

Autentiseringsflyten består av fire steg:

┌─────────────────────────────────────────────────────────────────────────┐
│  1. Start autentisering    →  Bruker sendes til Feide                   │
│  2. Hent Feide-token       →  Bytt autorisasjonskode til Feide-token    │
│  3. Hent JWT access token  →  Bytt Feide-token til JWT for API-bruk     │
│  4. Kall API               →  Bruk JWT som Bearer-token                 │
└─────────────────────────────────────────────────────────────────────────┘

Bruk et bibliotek

Vi anbefaler å bruke et etablert OIDC-bibliotek for ditt programmeringsspråk. Det du implementerer er authorization code grant. For frontend-klienter (SPA, mobilapper o.l.) bør du bruke PKCE i tillegg. Backend-klienter som kan holde på en client secret trenger ikke PKCE. De fleste biblioteker håndterer steg 1 og 2 automatisk.

Steg 1: Start autentiseringsflyten

Send brukeren til Feides autentiseringsendepunkt. Dette gjøres typisk ved å returnere en HTTP 302-redirect fra din backend.

https://auth.dataporten.no/oauth/authorization?
  client_id=<Client ID>&
  redirect_uri=<Redirect URI after login>&
  scope=openid&
  response_type=code&
  state=<Tilfeldig verdi>

Parametere:

Parameter	Beskrivelse
client_id	Din Client ID fra Feide Kundeportal
redirect_uri	URL-encoded callback-URL
scope	openid for OpenID Connect. Kan inkludere flere scopes separert med mellomrom
response_type	code for authorization code-flyten
state	En tilfeldig verdi du genererer for å beskytte mot CSRF-angrep

Scopes for FS GraphQL API:

For å få tilgang til FS-data via token exchange, inkluder relevante scopes:

• gk_07d5b019-57c4-4e9b-89c7-3c63baea0f99_student - for studentdata
• gk_07d5b019-57c4-4e9b-89c7-3c63baea0f99_ansatt - for ansattdata

07d5b019-57c4-4e9b-89c7-3c63baea0f99 er identifikatoren for datakilden FS GraphQL API.

Se Feide-dokumentasjonen for mer informasjon.

Steg 2: Bytt autorisasjonskode til Feide-token

Etter vellykket pålogging blir brukeren sendt tilbake til din redirect_uri:

http://localhost:3000/auth/callback?
  code=29e9cbb4-1c76-4323-bd72-15ba6cb4120a&
  state=<din state-verdi>

Viktig: Verifiser at state stemmer med verdien du sendte i steg 1.

Bytt code til et Feide-token:

POST https://auth.dataporten.no/oauth/token
Authorization: Basic <Base64 av Client ID:Client Secret>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=29e9cbb4-1c76-4323-bd72-15ba6cb4120a&
client_id=<Client ID>&
redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback

Respons:

{
  "access_token": "c1219f4f-788f-47d6-aa57-c1516074ebef",
  "token_type": "Bearer",
  "expires_in": 28799,
  "scope": "openid userid ...",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU..."
}

Feide-tokenet er ikke for API-bruk

access_token fra dette steget skal kun brukes mot Feide. Du må utføre en token exchange (steg 3) for å få et token som kan brukes mot FS GraphQL API.

Steg 3: Bytt Feide-token til JWT access token

Utfør en token exchange for å få et JWT som kan brukes mot FS GraphQL API:

POST https://auth.dataporten.no/oauth/token
Content-Type: application/x-www-form-urlencoded

audience=https://n.feide.no/datasources/<datakilde-UUID>&
client_id=<Client ID>&
client_secret=<Client Secret>&
grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
scope=&
subject_token=<Feide access_token fra steg 2>&
subject_token_type=urn:ietf:params:oauth:token-type:access_token

Parametere:

Parameter	Beskrivelse
audience	URL til datakilden du vil ha tilgang til
grant_type	urn:ietf:params:oauth:grant-type:token-exchange
subject_token	Feide access_token fra steg 2
scope	La være tom for å få alle scopes, eller spesifiser ønskede scopes

Respons:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI...",
  "token_type": "Bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "expires_in": 299,
  "scope": "open student"
}

Kort levetid på JWT

JWT-tokenet har kun 5 minutters levetid (expires_in: 299). Dette er en sikkerhetsmekanisme siden JWT-tokens ikke kan tilbakekalles. Din applikasjon må hente nye tokens ved behov.

Se Feide-dokumentasjonen om token exchange for mer informasjon.

Steg 4: Kall FS GraphQL API

Nå kan du sende forespørsler til FS GraphQL API med JWT-tokenet:

POST https://api.fellesstudentsystem.no/graphql/
Authorization: Bearer <JWT access_token fra steg 3>
Content-Type: application/json

{"query":"{ __typename }","variables":{}}

Feilhåndtering

Feilhåndtering

HTTP-status	Betydning
401 Unauthorized	Tokenet er ugyldig (utgått, feil format, ugyldig signatur)
403 Forbidden	Tokenet har ikke riktige tilganger (feil audience eller manglende scopes)

Når tokenet utløper

Siden JWT-tokenet har kort levetid, må du håndtere fornyelse:

1. Hvis Feide-tokenet fortsatt er gyldig: Gjenta steg 3
2. Hvis Feide-tokenet er utgått: Gjenta fra steg 1

Refresh tokens

Feide støtter ikke refresh tokens direkte. Du må i stedet bruke token exchange-mekanismen beskrevet over for å hente nye JWT-tokens.

Oppsummering av flyten

┌──────────────────────────────────────────────────────────────────────────┐
│  Din applikasjon                                                         │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  1. Redirect bruker til Feide  ──────────────────►  Feide                │
│                                                        │                 │
│  2. Motta callback med code    ◄──────────────────────┘                  │
│                                                                          │
│  3. POST /oauth/token          ──────────────────►  Feide                │
│     (authorization_code)                               │                 │
│     Motta Feide access_token   ◄──────────────────────┘                  │
│                                                                          │
│  4. POST /oauth/token          ──────────────────►  Feide                │
│     (token-exchange)                                   │                 │
│     Motta JWT access_token     ◄──────────────────────┘                  │
│                                                                          │
│  5. POST /graphql              ──────────────────►  FS GraphQL API       │
│     Authorization: Bearer JWT                          │                 │
│     Motta GraphQL-respons      ◄──────────────────────┘                  │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

---

Maskinporten

Med Maskinporten autentiserer applikasjonen seg på egne vegne, uten sluttbruker. Applikasjonen henter et access token fra Maskinporten og sender det direkte som Bearer-token til FS GraphQL API. Det er ikke noe token exchange-steg slik som for Feide.

Forutsetninger

For å følge denne oppskriften må du ha fullført tilgangsprosessen for Maskinporten beskrevet over. Du trenger:

• En integrasjon i Maskinporten med client_id og nøkkel for å signere JWT grant
• At applikasjonen er registrert hos Sikt med samme client_id og har fått tildelt tilganger

Slik bruker du Maskinporten

1. Hent et access token fra Maskinporten med JWT grant. Se Digdirs dokumentasjon om Maskinporten for hvordan du lager og signerer JWT grant.

   • Testmiljøet: https://test.maskinporten.no/token
   • Produksjon: https://maskinporten.no/token

2. Send access tokenet i Authorization-headeren i alle forespørsler:

   POST https://api.fellesstudentsystem.no/graphql/
   Authorization: Bearer <access_token fra Maskinporten>
   Content-Type: application/json
   
   {"query":"{ __typename }","variables":{}}

3. Hent et nytt token fra Maskinporten når det utløper.

Eksempel med curl

# 1. Hent access token fra Maskinporten
curl -X POST https://maskinporten.no/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=<signert JWT grant>"

# 2. Kall FS GraphQL API med access_token fra svaret
curl -X POST https://api.fellesstudentsystem.no/graphql/ \
  -H "Authorization: Bearer <access_token fra Maskinporten>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}'

Feilhåndtering

Feilhåndtering

HTTP-status	Betydning
401 Unauthorized	Tokenet er ugyldig eller utgått, eller client_id er ikke registrert

Begrensninger

• Applikasjonen får bare tilgangene institusjonen har godkjent. Det er ikke mulig å begrense tilgang basert på sluttbruker.
• Uten tildelte tilganger ser applikasjonen bare det som er åpent for alle.
• Tokens fra test.maskinporten.no godtas bare i testmiljøene, aldri mot produksjonsdata.
• En client_id kan bare være registrert på én applikasjon.

---

Nyttige lenker

• Feide-dokumentasjon: Obtaining tokens
• Feide-dokumentasjon: JWT Token Exchange
• Feide Kundeportal
• Digdir-dokumentasjon: Maskinporten
• Tilgang til FS-APIer
• Tilgangsstyring med RAS
• Sudo i testmiljøene: opptre som en syntetisk bruker