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 lar kunden opprette 5 ulike typer av integrasjoner:

• ID-porten (kun innlogging)
• ID-porten (API-klient, for brukerstyrt-datadeling)
• Ansattporten
• Maskinporten
• Kontaktregisteret

I tilegg finnes det en integrasjonstype for eFormidling, som administreres internt av Digdir.

Det er viktig å være klar over at disse integrasjonstypene rent teknisk alle er standard Oauth2 klienter, som må registreres 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.
• 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, og integrasjonstype kan ikke endres i ettertid.

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.

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.

client_secret_basic bør unngås til fordel for client_secret_post. Ved rotering av client_secret vil gammel og ny hemmelighet virke i 30 minutter. Kun én gammel client_secret støttes ved rotering. Ved kompromittert hemmelighet bør det lages 2 nye hemmeligheter. Slik vil det gamle slutte å virke med det samme. Den første nye hemmeldigheten skal aldri benyttes.

Merk at eksisterende secret slettes med det samme 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 registerer forskjellige oauth2 scopes på sine klienter. Listen i selvbetjeningen viser scopes som virksomheten din har fått tilgang til.

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.

RS256, RS384 og RS512 støttes som algoritme.

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

Dersom man ønsker å “låse” integrasjonen til et spesifikt virksomhetssertifikat, 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": "digdir_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 client_id. Ut over enkle alfanumeriske tegn, er spesialtegnene ._- tillatt.

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:

*NB! Bruk av localhost er ikke tillatt i produksjonsmiljøet for andre enn native klienter. Skal du registrere en localhost uri i testmiljøet, må denne være http:// og ikke https://.

** Frontchannel logout uri må ha samme domene som en registrert redirect uri.

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:

Levetiden på authorization definerer maks levetid, mens refresh_token definerer inaktivitet. Som hovedregel bør klienten være registrert slik: access_token_lifetime < refresh_token_lifetime <= authorization_lifetime.

*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.