Bestilling og implementering af token-klient

Indholdsfortegnelse

1. Formål
2. Bestilling af token klient
3. Implementering og brug af token klient
4. Sector9-Authorization Services
5. Authorization
6. Token
7. Logout

1. Formål

For at få udstedt en token til brug for Plandata's REST-API, kan Plandata's token klient (også kaldet OIDC klient) tilgås. Det er dog ikke hensigtmæssigt at benytte sig af Plandata's token klient hvis man ønsker et programmatisk flow for autentificering af brugere gennem MitID, da Plandata's token klient redirecter tilbage Plandata efter successfuldt login.

I stedet opfordres trejdeparter til at bestille og implementere sin egen token klient, således at den indloggede bruger kan redirectes tilbage til trejdepartssystemet og token kan gemmes for brugeres login for efterfølgende kald til Plandata's REST-API.

Denne vejledning beskriver hvad der skal bestilles for at kunne udvikle sin egen token klient samt hvordan en sådan bruges.

2. Bestilling af token-klient

Token-klient bestilles ved at sende en e-mail til support.plandata@plst.dk hvor der angives hvilket miljø klienten bestilles for med følgende oplysninger:

Attribut

Påkrævet

Krav

Anvendelse

Beskrivelse

Eksempel på attribut

client_id

PÅKRÆVET

For systemer fra eksterne organisationer er værdien:

external_<miljø>_<organisation>_<system>

hvor følgende erstattes:

  •  "<miljø>": erstattes med preprod/prod
  • "<organisation>": erstattes med organisationens navn
  • "<system>": erstattes med navnet på det eksterne system

Hvis man har brug for flere IdP'er for samme system i samme miljø, så oprettes alle klienter med følgende suffixes:

  • "_nemlogin" for NemLog-in IdP
  • "_eidasnatural" for eIDAS Natural IdP
  • "_eidaslegal" for eIDAS Legal IdP
  • "_ssi" for SSI IdP
  • "_tip" for TIP IdP

For PROD-klienter kan pt. kun benyttes nemlogin og ikke flere IdP'er.

Værdien skal benyttes som "client_id" parameteren ved kald til Authorization eller Token endepunkter.

Følger standarden OpenID Connect

 

System (fx. Planinfo) fra ekstern organisation (fx PLST):

  • PREPROD: external_preprod_plst_planinfo
  • PROD: external_prod_plst_planinfo

redirect_uris

PÅKRÆVET

Liste af en eller flere absolutte, HTTPS-baserede URL'er.

Vi anbefaler at path for redirect_uris er den samme i alle miljøer og at redirect_uris ikke går på tværs af miljøer.

En af værdierne skal benyttes som "redirect_uri" parameteren ved kald til Authorization eller Token endepunkter.
Følger standarden OpenID Connect

Som en del af OpenID Connect Authorization Code Flow, så skal klienter videresendes til et callback endpoint "redirect_uri" efter kald til Authorization endepunkt og URL til dette "redirect_uri" endpoint skal på forhånd være registreret i Sector9-Authorization for at sikre mod videresendelse til uauthoriserede endpoints.

Plandata eksempel:

post_logout_redirect_uris

ANBEFALES
(kan være tom liste)

Liste af 0, en eller flere absolutte, HTTPS-baserede URL'er.

En af værdierne kan benyttes som parameteren "post_logout_redirect_uri" ved kald til Logout endepunkt. 
Følger standarden OpenID Connect RP-Initiated Logout

Hvis klienten ikke angiver parameteren "post_logout_redirect_uri" ved kald til Logout endpoint, så sendes browseren til en 404 side, hvilket er en dårlig brugeroplevelse. Derfor bør systemet definere et (eller flere) endpoints hvor browseren kan sendes hen efter log ud. "post_logout_redirect_uris" skal være registreret i Sector9-Authorization for at sikre mod videresendelse til uauthoriserede endpoints.

Plandata eksempel:

sector9 realm

PÅKRÆVET

Navn på Sector9 realm, der ønskes anvendt. For PREPROD skal der vælges:

  • authDevtest4NemloginRealm (NemLog-in devtest4)

For PROD-klienter kan pt. kun vælges:

  • authNemloginRealm

Bestemmer hvilken identity provider, der anvendesaf en klient.

Der vælges blot ét realm (dvs. én identity provider) pr. klient pr. miljø. Vi anbefaler at benytte authDevtest4NemloginRealm i PREPROD og authNemloginRealm i PROD.

Plandata eksempel:

  • PREPROD: authDevtest4NemloginRealm
  • PROD: authNemloginRealm

 

3. Implementering og brug af token-klient

Når en token klient er bestilt og godkendt, er det muligt at implementere sin egen token klient. Token klienten skal kommunikere med et system der hedder Sector9-Authorization for at få udstedt en token til brug for Plandata's REST API. Leverandøren af Sector9-Authorization anbefaler at TypeScript biblioteket https://github.com/authts/oidc-client-ts benyttes til dette. "oidc-client-ts" er et frontend (JavaScript) library til OpenID Connect 1.0 som er standard-compliant og nemt at anvende.

Nedenstående visualiserer hvad der opnås ved implementering af sin egen token klient.

 

4. Sector9-Authorization Services

Sector9-Authorization udstiller en række endepunkter der kan benyttes ifm. udvikling af sin applikation.

For nedenstående REST kald, erstattes [miljø] i URL med:

  • PREPROD: "preprod"
  • PROD: "" (tom)

5. Authorization

Endpointet implementerer "Authorization" endpoint for "Authorization Code Flow" fra standarderne OpenID Connect 1.0 og Proof Key for Code Exchange by OAuth Public Clients. Endpointets URL åbnes i browseren. Sector9-Authorization gør følgende:

  1. Validerer requestet.
    • Hvis ikke valid, så afbrydes flowet og browseren videresendes til "redirect_uri" endpointet eller fejler.
  1. Viderestiller til Identity Provider, som håndterer login eller sessionsfornyelse
  2. Genererer ny, unik Authorization Code.
  3. Gemmer data (fra Sector9 HTTP-headers) tilhørende Authorization Code og evt. "claims" parameter i Sector9's system.
  4. Videresender browseren til det angivne "redirect_uri" endpoint med Authorization Code som query parameter.

Request

URL

https://erst[miljø].virk.dk/auth/authorize

Type

HTTP GET (med request parametre i URL som query params) / HTTP POST (med request parametre i entity-body)

Content-Type

application/x-www-form-urlencoded

Infrastruktur beskyttelse

/auth/authorize er ikke beskyttet af sector9 og sector9 kaldes derfor kun som led i andre interne kald der anvendes i authorize flowet. Sector9-Authorization viderestiller altid browseren til login hos Identity Provider (NemLog-in i PROD/PREPROD, TIP i andre NON-PROD miljøer) og derefter videre til et internt endpoint /auth/nemLogin som får headers fra det pågældende realm i Sector9. Dermed får Sector9-Authorization de nødvendige oplysninger til, at loginflowet kan fortsætte.

openid-configuration nøgle

authorization_endpoint

Request parametre

Det er kun følgende request parametre der er understøttet.  Andre request parametre vil enten blive ignoreret eller få kaldet til at fejle jf. valideringer angivet i OpenID Connect 1.0 og Proof Key for Code Exchange by OAuth Public Clients.

Navn

Påkrævet

Format

Standard

Beskrivelse

Eksempel

scope

PÅKRÆVET

liste opdelt med mellemrum

OpenID Connect 1.0

Listen skal indeholde værdien "openid".

openid

response_type

PÅKRÆVET

liste opdelt med mellemrum

OpenID Connect 1.0

Listen må kun have en værdi og værdien skal være "code", da Sector9-Authorization kun understøtter Authorization Code Flow.

code

client_id

PÅKRÆVET

tekststreng

OpenID Connect 1.0

Skal matche client_id der blev brugt til bestilling af token klient.

external_prod_plst_planinfo

redirect_uri

PÅKRÆVET

tekststreng (URL)

OpenID Connect 1.0

Værdien skal være "redirect_uri" tilhørende ovenstående "client_id". Værdien er miljøspecifik.

"redirect_uri" er en absolut URL til frontend klientens callback endpoint som Sector9-Authorization videresender browseren til som svar på "/authorize" kaldet. "redirect_uri" må ikke begynde med "http://" (brug "https://" i stedet for) og skal være et valid skema.

https://indberetpreprod.plandata.dk/plandata-api/oidcClient/redirectAuthorize

state

ANBEFALET

tekststreng

OpenID Connect 1.0

Parameter der gør det muligt at overføre tilstand til "redirect_uri" endpointet. (Der bør som minimum anvendes en ny værdi (som ikke kan gættes) pr. request til at sikre mod Cross-Site Request Forgery (CSRF, XSRF) jf. OpenID Connect 1.0 standarden)

703ae579-3e80-426d-9222-9a051059a631

code_challenge

PÅKRÆVET

tekst, minimum 43 tegn, maksimum 128 tegn, kun tegnene a-Z0-9-._~

Proof Key for Code Exchange by OAuth Public Clients

SHA256 + Base64 hashet værdi af "code_verifier" parameteren som anvendes i "/token" endpointet. (Der bør som minimum anvendes en ny værdi (som ikke kan gættes) pr. request til at sikre mod at en angriber kan udnytte opsnappet Authorization Code)

eoRU5ZAiBIx3zaDN91rCu2puJpnUCYaRMY1fzA8w5UQ

code_challenge_method

PÅKRÆVET

tekststreng

Proof Key for Code Exchange by OAuth Public Clients

Værdien skal være "S256". Sector9-Authorization understøtter ikke værdien "plain", da det er en sikkerhedsrisiko jf. standarden og værdien er kun tilladt for bagudkompatabilitet i standarden hvilket ikke er nødvendigt med moderne browsere.

S256

claims

VALGFRI

JSON-objekt

OpenID Connect 1.0

Værdien skal være JSON-objekt, serialiseret til tekst. Hvis JSON-objektet er sat (forskellig fra null), så kan det indeholde nøglerne "userinfo" og "id_token", kun må bestå af maps.

{"userinfo":{name: null}},"id_token":{"dk:gov:virk:role": "{...}}}

Response

Scenarie

HTTP-status

Content-Type

Svar (følger redirects)

Ingen fejl

302

N/A

"Location" HTTP-header er udfyldt med "redirect_uri", hvor følgende query parameters er tilføjet:

  • code: indeholder Authorization Code som Sector9-Authorization har genereret til brug for /token endpointet
  • state: indeholder værdien af "state" request query parameteren, hvis den er sat

Manglende / ukendt / ikke matchende "client_id" eller "redirect_uri" / ugyldig JSON i claims parameter

400

text/html;charset=utf-8

"Location" HTTP-header er ikke sat og response payload indeholder en fejlbesked

Fejl som kan videresendes

302

N/A

"Location" HTTP-header er udfyldt med "redirect_uri", hvor følgende query parameters er tilføjet:

6. Token

Beskrives i standarderne OpenID Connect 1.0 og Proof Key for Code Exchange by OAuth Public Clients. Endpointet kaldes af systemers frontendklient efter at Sector9-Authorization har videresendt til "redirect_uri" endpointet (med Authorization Code fra query parameter) i forbindelse med Authorization endepunkt kald. Sector9-Authorization gør følgende:

  1. Henter data i Sector9's system ud fra Authorization Code.
  2. Validerer requestet.
    • Hvis ikke valid, så afbrydes flowet med en fejl
  1. Genererer nyt Access Token og ID-token ud fra Authorization oplysninger.
  2. Gemmer data i Sector9 med Access Token som nøgle.
  3. Fjerner eksisterende data i Sector9 med Authorization Code som nøgle.
  4. Svarer med Access Token og ID-token i JSON struktur.

Request

URL

https://erst[miljø].virk.dk/auth/token

Type

HTTP POST med request parametre i entity-body (HTTP GET er ikke tilladt, da det er en sikkerhedsrisiko at eksponere Authorization Code som query parameter i URL'en)

Content-Type

application/x-www-form-urlencoded

Infrastruktur beskyttelse

Endpointet er ikke beskyttet af Sector9 (loadbalanceren kalder udenom Sector9).

Ved Client Credentials Flow kaldes dog videre til internt endepunkt /auth/basicAuthentication, som er beskyttet bag Sector9 i basic authentication realm.

openid-configuration nøgle

token_endpoint

Request headers

Navn

Påkrævet

Format

Relevante flows

Standard

Beskrivelse

Eksempel

authorization

PÅKRÆVET

tekststreng

Client Credentials Flow

OAuth 2.0

Basic Authentication credentials som veksles til Access Token for Client Credentials Flow

Basic ZmFnc3lzdGVtX3N5c3RlbV9icnVnZXI6bWVnZXRIZW1tZWxpZ3RQYXNzd29yZA==

Request parametre

Det er kun følgende request parametre der er understøttet.  Andre request parametre vil enten blive ignoreret eller få kaldet til at fejle jf. valideringer angivet i OpenID Connect 1.0 og Proof Key for Code Exchange by OAuth Public Clients.

Navn

Påkrævet

Format

Relevante flows

Standard

Beskrivelse

Eksempel

code

PÅKRÆVET

tekststreng

Authorization Code Flow

OpenID Connect 1.0

Authorization Code som frontend klienten modtog som query parameter for "redirect_uri" endpointet efter videresendelse fra Authorization endepunkt.

e6365d07-1027-4992-8d67-7db76d5b741b

client_id

PÅKRÆVET

tekststreng

Authorization Code Flow

OpenID Connect 1.0

Værdien skal være den samme som "client_id" parameteren der blev anvendt ved kaldet til Authorization endepunkt, hvor ovenstående "code" parameter blev udstedt og videresendt som "code" query parameter for "redirect_uri".

AAIABj4O53Q4wE0qnhQAr3gWSTI

redirect_uri

PÅKRÆVET

tekststreng (URL)

Authorization Code Flow

OpenID Connect 1.0

Værdien skal være den samme som "redirect_uri" parameteren der blev anvendt ved kaldet til Authorization endepunkt, hvor ovenstående "code" parameter blev udstedt og videresendt som "code" query parameter for "redirect_uri".

https://indberetpreprod.plandata.dk/plandata-api/oidcClient/redirectAuthorize

grant_type

PÅKRÆVET

tekststreng

Alle

OpenID Connect 1.0, OAuth 2.0

Typen af respons fra Token endpointet. Skal være "authorization_code" eller "client_credentials".

authorization_code

code_verifier

PÅKRÆVET

streng, minimum 43 tegn, maksimum 128 tegn, kun tegnene a-Z0-9-._~

Authorization Code Flow

Proof Key for Code Exchange by OAuth Public Clients

Tilfældig værdi som benyttes til at beregne code_challenge til Authorization endepunkt kaldet. (Der bør som minimum anvendes en ny værdi (som ikke kan gættes) pr. request til at sikre mod at en angriber kan udnytte opsnappet Authorization Code)

7CwHL3u0QNdIHT~MBmkHCg4d2QzLF-LpBRy9NcxmjJvRAuy~Yfg5A78oYK6uoztdLqvkTWBQd2ANbwbhl6MO4ODp8l0RYL5bEHoUJ.I3iOnWoCDDbElbBdr9lM3Y3CjE

 

Response

Scenarie

HTTP-status

Content-Type

Svar (følger redirects)

Ingen fejl

200

application/json;charset=UTF-8

JSON payload med felterne:

  • access_token: tekststreng - JWT Access Token streng udstedt af Sector9-Authorization. 
  • token_type: tekststreng - Bearer
  • expires_in: heltal - antal sekunder til SAML-sessionen udløber (max 3600)
  • id_token: tekststreng - JWT ID-token streng udstedt af Sector9-Authorization. 

Valideringsfejl

400

application/json;charset=UTF-8

JSON payload med felterne:

error: fejlkode fra standarden OpenID Connect 1.0 og OAuth 2.0

error_description: fejlbesked

7. Logout

Endpointet implementerer "Logout" endpoint fra standarden OpenID Connect RP-Initiated Logout 1.0 - draft 01. Endpointets URL åbnes i browseren. Sector9-Authorization validerer requestet og hvis valid, så videresendes browseren til Sector9-Gateway's logout endpoint for det realm som Sector9-Authorization benytter, hvilket videresender browseren til SingleLogOut endpoint hos dertilhørende Identity Provider hvor brugeren logges ud. Efterfølgende videresendes browseren til post_logout_redirect_uri, hvis angivet.

Request

URL

https://erst[miljø].virk.dk/auth/logout

Method

HTTP GET (med request parametre i URL som query params) / HTTP POST (med request parametre i entity-body). Da ID-token kan sendes med som "post_logout_redirect_uri" parameter og denne kan indeholde fortrolige oplysninger, så bør klienter kalde dette endpoint med POST så ID-token ikke eksponeres i URL'en som query parameter.

Content-Type

application/x-www-form-urlencoded

Infrastruktur beskyttelse

Endpointet benytter eksisterende Sector9-login vha. sessioncookie S9SESSIONID. Browseren redirectes ikke til login (NemLog-in i PROD/PREPROD, TIP i andre NON-PROD miljøer), hvis brugeren ikke er logget ind i forvejen.

openid-configuration nøgle

end_session_endpoint

Request parametre

Det er kun følgende request parametre der er understøttet.  Andre request parametre vil enten blive ignoreret eller få kaldet til at fejle jf. valideringer angivet i OpenID Connect 1.0 og Proof Key for Code Exchange by OAuth Public Clients.

Navn

Påkrævet

Format

Standard

Beskrivelse

Eksempel

id_token_hint

ANBEFALET
(PÅKRÆVET hvis post_logout_redirect_uri er sat)

tekststreng

OpenID Connect RP-Initiated Logout 1.0 - draft 01.

ID-token for brugeren der er logget ind - skal være udstedt af Sector9-Authorization i samme miljø.

 

post_logout_redirect_uri

ANBEFALET

tekststreng (URL)

OpenID Connect RP-Initiated Logout 1.0 - draft 01.

Hvis værdien er angivet, så skal den være indeholdt i "post_logout_redirect_uris" der er konfigureret i Sector9-Authorization for "client_id" der matcher "aud" claim for ID-token der findes i ovenstående "id_token_hint" parameter. Værdien er miljøspecifik. 

"post_logout_redirect_uri" er en absolut URL (typisk til frontend klientens callback endpoint) som Sector9-Authorization videresender browseren til efter Single Logout er foretaget hos Identity Provideren. "post_logout_redirect_uri" må ikke begynde med "http://" (brug "https://" i stedet for) og skal være et valid skema.

Denne parameter bør altid være sat, da browseren ellers sendes til en side som ikke findes (https://erst[miljø].virk.dk) hvilket er forvirrende.

https://indberetpreprod.plandata.dk/plandata-api/oidcClient/index 

state

VALGFRI

tekststreng

OpenID Connect RP-Initiated Logout 1.0 - draft 01.

Parameter der gør det muligt at overføre tilstand til "post_logout_redirect_uri" endpointet.

703ae579-3e80-426d-9222-9a051059a631

Response

Scenarie

HTTP-status

Content-Type

Svar (følger redirects)

Ingen fejl

302

N/A

"Location" HTTP-header er:

  • udfyldt med "post_logout_redirect_uri" hvis "post_logout_redirect_uri" er sat. Hvis "state" er sat, så tilføjes den som query parameter.
  • udfyldt med "https://erst[miljø].virk.dk" hvis "post_logout_redirect_uri" ikke er sat. "state" tilføjes ikke som query parameter, uanset om den er sat eller ej.

Valideringsfejl

400

text/html;charset=utf-8

"Location" HTTP-header er ikke sat og response payload indeholder en fejlbesked

Alle andre fejl

500

text/html;charset=utf-8

"Location" HTTP-header er ikke sat og response payload indeholder en fejlbesked