Registrering av klienter

Bakgrunn

Det er kundens ansvar å sørge for at det faktiske bruksmønsteret er i samsvar med registreringen. Korrekt registrering er spesielt viktig for klienter som konsumerer APIer tilbudt av andre, og Digitaliseringsdirektoratets og API-tilbyders bruksavtaler regulerer dette ansvarsforholdet.

ID-portens integrasjoner

Selvbetjeningsløsningen håndterer 4 ulike typer av integrasjoner:

• ID-porten
• Kontaktregisteret
• Maskinporten
• API-klient innlogget bruker

Det er viktig å være klar over at disse integrasjonstypene rent teknisk alle er standard Oauth2 klienter, men med ulike egenskaper. Se detaljer lenger ned.

Vi har 3 måter du kan få registrert din integrasjon:

• Selvbetjening, ved å logge inn på [Selvbetjening på Samarbeidsportalen](https://minside-samarbeid.digdir.no.
• Selvbetjening, ved å bruke vårt selvbetjenings-API
• Manuelt, ved å sende epost til servicedesk@digdir.no (kun for ID-porten og Kontaktregisteret)

Integrasjonstyper

Du må registrere en integrasjonstype for å få fornuftige valg til klienten din i selvbetjeningsløsningen. Hvilken integrasjonstype du velger, vil legge føringer på hvilke scopes du kan bruke med klienten. En klient kan kun ha en integrasjonstype.

Det som støttes foreløpig er:

Det er ikke mulig å endre integrasjonstype etter opprettelse.

Du vil ikke være i stand til å legge på et scope på klienten din som er i konflikt med klienten’s integrasjonstype. F.eks du kan ikke legge til et scope som er begrenset til “maskinporten” på en ID-porten klient, og vice versa.

Leverandører

Dersom du er leverandør, er det noen av klient-egenskapene nedenfor som du må passe på å få registrert rett. Se egen leverandør-informasjon.

Oauth2-egenskaper

Dette avsnittet detaljerer noen viktige Oauth2 egenskaper som kategoriserer våre klienter. Se gjerne Oauth2 Dynamic Client Registration for mer informasjon (RFC7591).

I utgangspunktet kan du som kunde velge Oauth2-egenskaper fritt etter egen risikovurdering. De som konsumerer API tilbudt av andre må være oppmerksom på at API-tilbyder kan stille krav til spesifikke egenskaper. Validering av slike krav skjer som hovedregel kun run-time ved tokenutstedelse og ikke ved klient-registrering.

Klient-autentisering

Alt etter bruksområde, så tilbyr vi forskjellige metoder for autentisering av din klient. Dette blir styrt av attributtet token_endpoint_auth_method:

Digitaliseringsdirektoratet anbefaler bruk av asymetriske nøkler private_key_jwt til klientautentisering over statiske hemmeligheter. Enten å bruke virksomhetssertifikat, da prosedyren for utstedelsen av slike er grundig regulert i lovverk og gir derfor både Digitaliseringsdirektoratet og API-tilbydere en god og sikker identifisering av klienten. Dersom organisasjonen har høy modenhet, kan også egen-genererte asymmetriske nøkler anbefales. client_secret_basic bør unngås til fordel for client_secret_post eller helst client_secret_jwt.

Digitaliseringsdirektoratet forutsetter at API-tilbyder og API-konsument håndterer sertifikat og nøkler på en måte som sikrer at ikke uvedkommende kan misbruke disse.

Merk at eksisterende secret slettes dersom man endrer metoden til noe annet enn client_secret_*

Grant-typer

Et grant representerer brukerens samtykke til å hente et access token (som i sin tur brukes til hente den beskytta ressurs tilhørende brukeren, se Oauth2, kap 1.3 samt grant_types i DCR kap. 2 )

ID-porten støtter følgende grants:

Kun klienter som er registrert med refresh_token som tillatt grant-type, vil få utdelt refresh_token ved bruk av autorisasjonskode-grant.

Maskinporten-klienter skal alltid bruke jwt_bearer_token.

Vi støtter ikke implicit, password eller client-credentials grant.

Klient-typer

Klient-type (application_type) forteller hvilke type kjøretidsmiljø klienten kjører under. Oauth2 kap 2.1 lister opp hvilke valg som finnes. Valg av klient-type er en sikkerhetsvurdering kunden skal utføre.

Scopes

Kunden registere forskjellige oauth2 scopes på sine klienter. Se regler for scopes for fullstendige detaljer.

Oversikt over kombinasjonar

Tabellen under oppsummerer sammenhengen mellom de ulike egenskapene:

Bruk av asymmetrisk nøkkel

Man kan sende inn en JWKS-struktur (RFC7517), dvs. en array av flere (inntil 5) JWK-representasjoner.

Er modellert som egen ressurs under klient /clients/{client_id}/jwks

Kan ikke gjøre operasjoner på enkelt-nøkler, kun hele settet, dvs. både POST og PUT erstatter evt. eksisterende JWKS.

Kun RS256 støttes som algoritme.

Man må alltid sende inn nøkkeldefinisjonen (kty,alg,use,e,n).

Dersom man ønsker å “låse” integrasjonen til et spesifikt virksomhetifikat, må i tillegg inkludere sertifikatet (x5c). Da vil vi runtime validere revokasjon mot Buypass/commfides.

Eksempel på å legge inn en nøkkel:

POST /clients/{client_id}/jwks

{
  [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "jbi_min_noekkel",
      "alg": "RS256",
      "n": "lGc-dGnl9l9pCSb6eW5Mf23Aiss09q7Mxre9q9dazSiN9IjQJmkWDySpoYW3g_rSX2a74cg_q3iTSM0Co9iJ0LQp8gjoIi9I8syi6anBKK6fISr1adZbsGGrM1-zMRRNVsJ811snTdkbgx8ZxVRJM4F6D2KwL3TEnv0CRRVtphO0sRmimKBVVBdawPYQC64SQDvARy6xIlPhD-Da2n2Cl6vRQbVns7dYD8-C2TeYGgB_tAsrVSorx9GF5cZ-hlNHfIgg2qQYZzaljyfOWPPG5rybp9bAWg9vFllUFd_Y6vvZ0tqVfAyj67nFz_w4Rxy-MdRgERKHJcq81GkmVzq5fQ"
    }
  ]
}

kid velges av kunde selv, og må være unik innenfor alle ID-porten/Maskinportens kunder.

Ved klient-autentisering mot /token-endepunktet, og ved bruk av JWT bearer grants, må klienter som har registrert en nøkkel bruke kid-parameteren i jwt-headeren istedenfor x5c.

NB! En nøkkel har MAKS 1 års levetid fra tidspunktet den blir postet på.

Ved bruk av selvbetjenings-API, må kunden passe på å sende konfigurasjoner som er kompatible med tabellen over, ellers risikerer man å ende opp med en ubrukelig klient.

Ved bruk av selvbetjening på Samarbeidsportalen er tilgjengelige valg avgrenset av valgt integrasjonstype.

Andre metadata

Vi forsøker å følge spec’en i så stor grad som mulig. Se gjerne Oauth2 Dynamic Client Registration for mer informasjon (RFC7591).

Basis-sett

Følgende metadata er felles for alle typer klienter:

Metadata for innloggings-klienter:

Klienter som skal innvolvere brukeren (altså brukerens browser) må ha følgende satt:

Metadata for klienter som konsumerer APIer

For klienter (både innlogging og maskin) som mottar access_token til API-sikring kan man registrere følgende:

*Merk at de fleste av egenskapene til access_token blir bestemt av API-tilbyder, og ikke som en del av klient-registreringen. En klient kan for eksempel ikke få token som har lengre levetid enn det API-tilbyder har satt som maks-grense.