- OAuth2
Applicaties kunnen de OAuth2 authorizatie server gebruiken om a/m-profielen te laten authenticeren (authorization_code). Daarnaast ondersteunen we ook de mogelijkheid om applicaties te authenticeren (client_credentials).
Voor alle (web)applicaties raden we aan om gebruik te maken van OAuth2.
Indien jouw applicatie toch gebruik maakt van SAML kan dit alsnog opgezet worden. Gelieve hiervoor contact op te nemen met het APIe-team via Zendesk.
Op de API store kan je jouw eigen applicatie registreren. Deze dien je aan te maken in de organisatie waartoe de applicatie behoort.
Indien je jouw applicatie niet kan onderbrengen in een bestaande organisatie kan je zelf ook één aanmaken.
Voor iedere omgeving is er een aparte omgeving opgezet:
- DEV: https://api-store-o.antwerpen.be
- ACC: https://api-store-a.antwerpen.be
- PROD: https://api-store.antwerpen.be
(Links naar de API Store in deze readme gaan naar de ACC omgeving.)
Nadat je jouw applicatie aangemaakt hebt kan je een contract aanmaken met de databron van je login methode:
- M-Profiel (medewerkers)
- Shared Identity Data (burgers)
- [deprecated] A-Profiel (burgers)
Afhankelijk van je databron dien je gebruik te maken van Digipolis Authenticatie 1.0 of 2.0.
De OAuth2 client_id en client_secret kan je bij de detail gegevens van jouw applicatie vinden. Afhankelijk van de API is er nog een goedkeuring nodig van de beheerder van de API. Deze goedkeuringsflow verloopt geheel automatisch.
De OAuth2 tokens zijn geldig voor alle OAuth2 services waarvoor jouw applicatie een contract heeft.
Request:
curl -X POST -d "client_id={{CLIENT_ID}}&client_secret={{CLIENT_SECRET}}&grant_type=client_credentials" https://api-gw-p.antwerpen.be/{org}/{service}/{version}/oauth2/token
Response:
{"token_type":"bearer","access_token":"8c5b38ffee744ac6bd1e18eae5cbd406","expires_in":7200}
Request:
curl -v -H "Authorization: Bearer {{ACCESS_TOKEN_FROM_PREVIOUS_STEP}}" 'https://api-gw-p.antwerpen.be/{org}/{service}/{version}/me'
De OAuth2 authorizatie server kan je op volgende locatie vinden:
Een voorbeeld redirect naar de authorizatie applicatie ziet er zo uit:
https://api-oauth2.antwerpen.be/v1/authorize?
response_type=code
&service=astad.aprofiel.v1
&client_id=YOUR_CLIENT_ID
&scope=astad.aprofiel.v1.username%20astad.aprofiel.v1.name%20astad.aprofiel.v1.avatar%20astad.aprofiel.v1.email%20astad.aprofiel.v1.phone
&redirect_uri=YOUR_REDIRECT_URI
&state=thisParameterWillBeAddedToTheRedirectUri
&save_consent=true
Het authorize endpoint is beschikbaar in deze versies:
Authenticatie 1.0
Deze versie is bedoeld voor authenticatie van medewerkers in combinatie met de M-Profiel v1 API om het profiel op te halen.
Inloggen voor burgers met de A-Profiel v1 API is ook mogelijk maar is deprecated: gebruik Authenticatie 2.0 voor nieuwe toepassingen.
Authorize endpoint: /v1/authorize
Authenticatie 2.0
Digipolis Authenticatie 2.0 biedt enkele extra opties aan binnen het OAuth2 login mechanisme:
- Opvragen/beheren/herbruiken van sessies.
- Het concept van assurance levels: dit geeft aan hoe betrouwbaar de loginmethode is (
minimal_assurance_levelquerystring parameter). - Een login keuze scherm dat wordt opgebouwd op basis van toegestane login methodes / niveaus (
auth_methodsquerystring parameter).
Deze versie kan je gebruiken voor authenticatie van burgers in combinatie met de Shared Identity Data v1 API om het profiel op te halen.
Authorize endpoint: /v2/authorize
Documentatie: https://acpaas.digipolis.be/nl/docs/identiteit-authenticatie-en-autorisatie
| Parameter | v1 | v2 | Verplicht | Omschrijving |
|---|---|---|---|---|
| response_type | ✓ | ✓ | ✓ | Voor de authorization_code flow dien je hier 'code' te gebruiken . |
| client_id | ✓ | ✓ | ✓ | De client_id die je kan terugvinden bij jouw applicatie in de API store. |
| scope | ✓ | ✓ | ✓ | Een door komma's gescheiden lijst van scopes die de gebruiker dient goed te keuren. Zie Beschikbare scopes. |
| redirect_uri | ✓ | ✓ | ✓ | De redirect_uri die overeenkomt met diegene die is ingegeven in de API store voor jouw applicatie. |
| redirect_uri_lng | ✓ | ✓ | Als deze waarde op 'true' staat zal de redirect_uri een extra parameter 'lng' hebben wanneer de gebruiker de OAuth2 authorizatie applicatie verlaat. De waarde voor de 'lng' querystring parameter zal overeenkomen met de taal op de authorizatie applicatie. | |
| service | ✓ | ✓ | De service die je wil gebruiken om een gebruiker te authenticeren. Dit kan "astad.mprofiel.v1" of "astad.aprofiel.v1" [deprecated] zijn. | |
| auth_methods | ✓ | ✓ | De authenticatie methodes voor Digipolis Authenticatie 2.0 (komma gescheiden). Bv. "fas-hintedlogin-bmid,fas-hintedlogin-eid". Als er maar één methode wordt meegegeven zal het keuzescherm overgeslagen worden. Zie login methodes | |
| minimal_assurance_level | ✓ | ✓ | Het minimale authenticatie betrouwbaarheidsniveau, nl. hoe sterk een gebruiker zijn identiteit minimaal dient aan te tonen a.d.h.v. een bepaalde authenticatiemethode alvorens zich succesvol te kunnen aanmelden. Bv. "low". | |
| state | ✓ | ✓ | We raden aan om deze parameter te voorzien in de redirect naar de authorizatie applicatie met een referentie naar de sessie van de gebruiker. Aangezien de parameter opnieuw zal worden meegeven in de redirect_uri, kan jouw applicatie valideren of de autorisatie flow gestart is vanuit jouw applicatie. | |
| lng | ✓ | ✓ | De taal voor de authorizatie applicatie. Standaard staat deze op 'nl'. Beschikbare talen zijn nl, fr, en, de. | |
| force_auth | ✓ | ✓ | Als een gebruiker al een SSO (Single Sign-On) sessie heeft op de achterliggende IDP (IDentity Provider) kan je met deze parameter aangeven dat je de gebruiker verplicht opnieuw wil laten aanmelden. | |
| save_consent | ✓ | ✓ | Als je deze op 'true' zet, zal de authorizatie applicatie de gegeven consent onthouden voor jouw applicatie/gebruiker/scopes. |
De beschikbare scopes verschillen per service.
- M-Profiel (astad.mprofiel.v1): all
- Shared Identity Data (acpaas.sharedidentitydata.v1): zie documentatie
- [deprecated] A-Profiel (astad.aprofiel.v1): username, name, avatar, email, phone, address
De scopes kan je ook terugvinden in de API Store bij de API die bij de service hoort. De tooltip bij "OAuth2 Policy" onder tabblad "Plans & Policies" toont de beschikbare scopes.
| Naam | Level | Beschrijving |
|---|---|---|
| iam-aprofiel-userpass | low | A-Profiel met username en paswoord |
| fas-citizen-bmid | substantial | Belgian Mobile ID (bv. itsme) |
| fas-citizen-otp | substantial | One time password (bv. sms) |
| fas-citizen-totp | substantial | Time-based one time password (bv. Google Authenticator) |
| fas-citizen-eid | high | eID-kaart en pincode |
Als je medewerkers in je applicatie wilt laten inloggen en gegevens over deze gebruiker wenst op te halen moet de applicatie een geldig contract hebben met de MProfiel API.
Voor burgers is een contract nodig met de Shared Identity Data API (die achterliggend gebruik maakt van A-Profiel) of de AProfiel v1 API [deprecated].
Technische implementatie details en een werkende Node.js demo applicatie kan je hier vinden: https://github.com/digipolisantwerp/demo-oauth2-consumer_app_nodejs
Een authorization_code kan je bekomen door de gebruiker naar de OAuth2 authorizatie applicatie te redirecten.
Nadat de gebruiker is ingelogd en zijn goedkeuring(consent) heeft gegeven zal de gebruiker naar de redirect_uri geredirect worden die je hebt ingegeven in de details van uw applicatie op de API store;
Deze redirect_uri bevat een code querystring parameter als de authenticatie succesvol is. Bijvoorbeeld: https://domain.com/callback?code=123
Optioneel worden in deze redirect_uri ook de querystring parameters lng en state teruggegeven.
Request:
curl -X POST -d "client_id={{CLIENT_ID}}&client_secret={{CLIENT_SECRET}}&code={{CODE_FROM_PREV_STEP}}&grant_type=authorization_code" https://api-gw-p.antwerpen.be/{org}/{service}/{version}/oauth2/token
Response: {"refresh_token":"66f0c43c27a94ad4aa2d7574cf7b4465","token_type":"bearer","access_token":"a2824fb10b2a44b2b6f1a4aba382630a","expires_in":7200}
curl -v -H "Authorization: Bearer {{ACCESS_TOKEN_FROM_PREVIOUS_STEP}}" 'https://api-gw-p.antwerpen.be/{org}/{service}/{version}/resource'
Hoewel het "implicit" OAuth2 profiel beschikbaar is op de API gateway raden we aan om deze niet te gebruiken.
Voornamelijk omwille van onderstaande redenen:
- Access_tokens die zijn aangemaakt met de implicit/token flow zijn slechts 2 uur gelding en kunnen niet verlengd worden.
- Aangezien de client_secret niet gebruikt wordt om een access_token aan te vragen is dit OAuth2 profiel vatbaarder voor security issues.
De OAuth2 authorizatie server bevat ook de mogelijkheid om gebruikers centraal te laten uitloggen.
Om dit te bereiken moet je de gebruiker redirecten naar het redirect endpoint van de OAuth2 authorizatie server:
- Authenticatie 1.0:
/v1/logout/redirect/encrypted - Authenticatie 2.0:
/v2/logout/redirect/encrypted
Querystring parameters:
| Parameter | v1 | v2 | Verplicht | Omschrijving |
|---|---|---|---|---|
| client_id | ✓ | ✓ | ✓ | De client_id die je kan terugvinden bij jouw applicatie in de API store. |
| service | ✓ | ✓ | De service waarmee de gebruiker zich geauthenticeerd heeft, bv. "astad.aprofiel.v1" of 'astad.mprofiel.v1' zijn. | |
| authMethod | ✓ | ✓ | De authenticatie methode die werd gebruikt bij de login. Deze waarde krijg je terug via de "method" querystring parameter in de callback URL na het inloggen. | |
| data | ✓ | ✓ | ✓ | Een object met extra data ivm het uitloggen. Deze data is geëncrypteerd volgens sha1 op basis van de client_secret. |
| data.user_id | ✓ | ✓ | ✓ | De id van de gebruiker die wenst uit te loggen |
| data.access_token | ✓ | ✓ | ✓ | Het access_token van de gebruiker die wenst uit te loggen |
| data.redirect_uri | ✓ | ✓ | ✓ | De url op jouw applicatie naar waar de gebruiker geredirect moet worden nadat hij uitgelogd is. Het domein van deze redirect_uri moet overeenkomen met het domein van de redirect_uri (callback) die je in de API Store hebt ingegeven voor het aanlogproces |
Alvorens de gebruiker centraal uit te loggen (via bovenstaande redirect) moet je ook nog de gebruiker sessie in jouw applicatie beëindigen.
Telkens een gebruiker via bovenstaande OAuth applicatie uitgelogd is zal er een event op de EventHandler gepublished worden.
| Namespace | Event | Omschrijving |
|---|---|---|
| OAuth | astad.aprofiel.v1.loggedout | Waneer een aprofiel gebruiker uitgelogd is. |
| OAuth | astad.mprofiel.v1.loggedout | Waneer een mprofiel gebruiker uitgelogd is. |
Het bericht ziet er als volgt uit:
{
user: <user id>,
service: <de service waarmee de gebruiker aangemeld was>,
timestamp: <ISO datum en tijd>
}
De backend API-interface met onze OAuth2 provider (binnen Digipolis gekend als de consent app) is beschikbaar via de Consent API op de API Store.
Deze bevat de volgende mogelijkheden:
- De huidige sessie, niveau, loginmethode van een browser opvragen.
- Alle actieve sessies van een browser opvragen.
- De huidige sessie van een browser en applicatie opvragen.
- Login sessies van een gebruiker afsluiten.