oAuth via een API-gateway

In het geval dat er voor de API een API-gateway aanwezig is, dan kan men de oAuth beveiliging en autorisatie laten afhandelen door de API-zelf. In dat geval treedt de API-gateway gewoon als reverse proxy op en dient de API alle oAuth logica zelf af te handelen.

Men kan de API-gateway echter ook configureren om alle oAuth logica af te handelen in combinatie met ACM IDP, waardoor de API Resource oAuth agnostisch opgezet kan worden.

Een bijkomend voordeel van een dergelijke setup is dat de API gateway een aantal policies kan valideren alvorens de gebruiker door te laten naar de toepassing. Om te voorkomen dat zowel de toepassing als de API gateway een introspection moeten doen van een token, wordt aan de response van het introspection endpoint een key “jwt” toegevoegd. Deze key bevat alle informatie die het introspection endpoint terug geeft, maar dan in JWT formaat, waarbij de toepassing de geldigheid kan valideren door de signature van de JWT te valideren (met één van de keys die op het keys endpoint worden gepubliceerd).

We onderscheiden 3 scenario’s:

1. API-gateway oAuth afhandeling voor Server-naar-server API
2. API-gateway oAuth afhandeling voor API namens een gebruiker
3. API-gateway voor toepassingen die een gebruikersinteractie vereisen

API-gateway oAuth afhandeling voor Server-naar-server API

Alle principes zoals beschreven in het oAuth Server-naar-server scenario zijn nog steeds geldig, maar de API-gateway voltooit de oAuth acties in de plaats van de API.

Voor de afnemer toepassing maakt dit uiteraard geen verschil en die vraagt een access token op voor het bevragen van de Resource API (via de Client Credential Grant).

Het is echter de API-gateway die zorgt voor:

• de validatie van het Access Token bij het Introspection Endpoint van ACM IDP (stap 4)
• het ophalen van de scopes (stap 5)
• optioneel: het valideren dat deze scopes geldig zijn voor het bevragen van deze API

In dit geval kan de API Resource dus volledig oAuth agnostisch opgezet worden. Of de API Resource nood heeft aan de meegestuurde scopes hangt uiteraard van de use case af. Afhankelijk van de use case kan de API-gateway dan ingesteld worden om ofwel geen scopes mee te sturen ofwel kunnen deze meegestuurd worden op de manier die af te stemmen is tussen API-gateway en de API Resource: bijvoorbeeld via een HTTP-header of de scopes toevoegen in de payload.

Men kan er ook voor kiezen om de “jwt” key die door het introspection endpoint wordt aangeboden door te sturen naar de API resource. De API resource kan de signature van deze JWT valideren (op basis van de keys van de OP) en kan er op die manier zeker van zijn dat de info afkomstig is van de OP en dat de waarden (zoals scopes, info omtrent de Client, etc) onderweg niet gemanipuleerd werden. De API resource hoeft zelf dan geen validatie op het introspection endpoint meer uit te voeren.

In sommige use cases zal men de confidentialiteit van de connectie tussen de API gateway en de API resource willen garanderen. Bijvoorbeeld als men beslist om de scopes via HTTP-headers mee te sturen of om de API resource af te schermen van een groot aantal onrechtmatige requests. Op welke manier dit kan gebeuren is ook af te stemmen met de API-gateway: bijvoorbeeld via mutual-TLS (mTLS), via een eigen datastroom of VPN.

De technische vereisten voor de API-gateway voor wat betreft oAuth staan beschreven in de flow voor oAuth Server-naar-server.

API-gateway oAuth afhandeling voor API namens een gebruiker

Alle principes zoals beschreven in het scnario voor oAuth REST-API namens een gebruiker zijn nog steeds geldig, maar de API-gateway voltooit de oAuth acties in de plaats van de API.

Voor de Frontend toepassing maakt dit uiteraard geen verschil en die vraagt een access token op voor het bevragen van de Resource API (via een Authorization Code Grant op basis van een Access Token van een eerdere authenticatie).

Het is echter de API-gateway die zorgt voor:

• de validatie van het Access Token bij het Introspection Endpoint van ACM IDP (stap 6)
• het ophalen van de scopes (stap 7)
• optioneel: het valideren dat deze scopes geldig zijn voor het bevragen van deze API

In dit geval kan de API Resource dus volledig oAuth agnostisch opgezet worden. Of de API Resource nood heeft aan de meegestuurde scopes hangt uiteraard van de use case af. Afhankelijk van de use case kan de API-gateway dan ingesteld worden om ofwel geen scopes mee te sturen ofwel kunnen deze meegestuurd worden op de manier die af te stemmen is tussn API-gateway en de API Resource: bijvoorbeeld via een HTTP-header of de scopes toevoegen in de payload.

Men kan er ook voor kiezen om de “jwt” key die door het introspection endpoint wordt aangeboden door te sturen naar de API resource. De API resource kan de signature van deze JWT valideren (op basis van de keys van de OP) en kan er op die manier zeker van zijn dat de info afkomstig is van de OP en dat de waarden (zoals scopes, info omtrent de aangemelde gebruiker, etc) onderweg niet gemanipuleerd werden. De API resource hoeft zelf dan geen validatie op het introspection endpoint meer uit te voeren.

In sommige use cases zal men de confidentialiteit van de connectie tussen de API gateway en de API resource willen garanderen. Bijvoorbeeld als men beslist om de scopes via HTTP-headers mee te sturen of om de API resource af te schermen van een groot aantal onrechtmatige requests. Op welke manier dit kan gebeuren is ook af te stemmen met de API-gateway: bijvoorbeeld via mutual-TLS (mTLS), via een eigen datastroom of VPN.

De technische vereisten voor de API-gateway voor wat betreft oAuth staan beschreven in de flow voor oAuth oAuth API namens een gebruiker.

API-gateway voor een toepassing die een gebruikersinteractie vereist

In dit scenario treedt de API-gateway in feite simpelweg op als een Client voor een OpenID Connect integratie of een oAuth integratie.

Net zoals in beide bovenstaande scenario’s kan de API zelf dan OpenID Connect- of oAuth-agnostisch opgezet worden.

API gateway introspection toe laten

In een scenario waarbij een API gateway voor een API wordt gepositioneerd om specifieke policies af te dwingen, zal deze API gateway introspection moeten doen van tokens die bedoeld zijn voor de API. Standaard zal dit niet mogelijk zijn omdat de audience van het token (onderwerp voor introspectie) de client_id van de API zal zijn. De client_id van de API gateway (= de client die zich authenticeert op het introspection endpoint) zal geen introspectie mogen doen omdat deze niet in de audience van het access token voor komt.

Om de introspectie in deze usecases toch te laten slagen, dient bij de onboarding van de API aangegeven te worden dat het de client_id van de API gateway is toegestaan om introspectie te doen.

Om in deze usecases ook de setbyapi_ claims belangrijk zijn, dient de API gateway gebruik te maken van de X-Forwarded-Audience request header. Zie setbyapi voor meer info.