Externe partij koppelen met Wise IAM

Implementeren OIDC-authenticatie

Inloggen met Keycloak werkt via het OIDC principe (OpenIDConnect), een authenticatieprotocol. Voor het implementeren van OIDC in je mobiele applicatie raden wij het gebruik aan van de AppAuth library van OpenID: https://github.com/openid
AppAuth is een uitgebreide library die gemakkelijk te gebruiken is en goed gedocumenteerd is. Het staat je uiteraard vrij om voor een andere oplossing te kiezen.

OIDC-principe

1. Wanneer een gebruiker probeert in te loggen bij een client-applicatie, wordt een authenticatieverzoek naar Wise-IAM (een identity broker) gestuurd.
2. Wise-IAM initieert het inlogproces door de gebruiker om hun inloggegevens te vragen.
3. Na succesvolle authenticatie genereert Wise-IAM tokens, waaronder een access token en refresh token en een id token. De tokens worden teruggestuurd naar de client-applicatie.
4. Met het geldige access token kan de client toegang krijgen tot beveiligde resources, zoals API's of andere services.
5. Als het access token verloopt, kan de client een nieuw access token aanvragen met het refresh token, mits het refresh token nog geldig is.

Als OIDC een nieuw concept voor je is, dan raden wij aan om lege Keycloak instantie te draaien in docker en daarmee verbinding te maken. Zo kun je een gevoel krijgen voor hoe het protocol verloopt. OCLC gebruikt Keycloak als identity broker.

Dynamisch clientId’s ophalen voor Wise-IAM

Omdat de bibliotheken hun klanten gefaseerd zullen migreren, zal de mobiele applicatie om moeten kunnen gaan met twee manieren van inloggen. Ons Wise-IAM systeem kan, op basis van een clientId, de beslissing maken welke login flow gevolgd wordt. Hij doet dit op basis van de clientId die meegegeven wordt in het authenticatieverzoek. Deze informatie zal constant veranderen naarmate er meer bibliotheken migreren, en zal daarom per login opgehaald moeten worden.

Los van de migratie, als de mobiele applicatie services levert aan meer dan 1 systeem, zal deze werkwijze blijven gelden, en kan een clientId niet hardcoded opgeslagen worden.

OCLC biedt een RESTapi endpoint aan om dit te faciliteren. Dit endpoint kan aangeroepen worden per systeem met de library_id als payload. Dit endpoint geeft terug waar Keycloak zich bevindt, welk realm (Wise systeem) van belang is en de juiste client_id (welke bepaald of voor die instantie de Wise of KB inlogflow gebruikt wordt).

Het pad om het endpoint te benaderen is als volgt:
{servername}/restapi/configuration/oidc-client?libraryId={library_id}

Dit endpoint geeft de juiste informatie terug op basis van de wise_key om het endpoint aan te roepen.

Benodigde informatie

Je moet een aantal variabelen weten om een authentication request naar Keycloak te sturen.

• CLIENT_ID
• AUTHORIZATION_SCOPE
• KEYCLOAK_URL
• REALM
• REDIRECT_URL
• END_SESSION_REDIRECT_URL

Op het moment dat je een applicatie wil laten authenticeren via de OCLC Keycloak server dien je contact op te nemen met OCLC, zodat OCLC de configuratie op de Keycloak server klaar kan maken en de bovengenoemde variabelen met je kan delen.

Verdere informatie, zoals het authorization endpoint, kun je opvragen via de discovery endpoint. De discovery uri bevindt zich in de industriestandaard locatie en is als volgt opgebouwd:

$KEYCLOAK_URL$/realms/$REALM$/.well-known/openid-configuration

Authenticeren

Je kan authenticeren door een authenticatie-verzoek te versturen naar Keycloak. Dit verzoek stuur je naar het authorization endpoint, die je hebt opgevraagd via de discovery endpoint.  Dit verzoek bouw je op met het CLIENT_ID, AUTHORIZATION_SCOPE en REDIRECT_URL.
Na een succesvolle authenticatie krijg je een access token, een refresh token en een id token terug. Het access token kan gebruikt worden om toegang te krijgen tot de beveiligde service. Het refresh token kan gebruikt worden om een nieuw access token op te vragen zodra de huidige het access token verlopen is. Het id token wordt gebruikt om een logout request te sturen.

Session expired

Een access token heeft maar een beperkte geldigheid, wanneer deze is verlopen zal de aangesproken service een 'Session Expired' signaal teruggeven aan de client. De client zal dan een nieuw access token moeten opvragen vanuit Keycloak. Hiervoor stuurt de client een token request, met het refresh token op. Als de refresh token ook niet langer geldig is dan zal er opnieuw geauthenticeerd moeten worden.

De levensduur van dit refresh token wordt door OCLC bepaald maar kan in overleg veranderd worden.

Logout request

Wanneer de client de gebruiker wil laten uitloggen, moet er een logout request worden verstuurd naar de Keycloak server. Voor dit verzoek heb je het id token nodig en optioneel de END_SESSION_REDIRECT_URL. De Keycloak server zorgt ervoor dat de uitgegeven access tokens en refresh tokens ongeldig worden gemaakt.

Wise token

De patronsystemuuid zit in het token welke teruggegeven wordt door Keycloak. Als er gebruikt wordt gemaakt van het uuid van de gebruiker zullen hier ook aanpassingen in gedaan moeten worden. Het token is een standaard JWT met RS256 encoding.

Beginnen met het aansluiten op Wise

Voor aansluiting op ons Keycloak systeem heeft OCLC de Redirect URL nodig voor terugkeer naar de applicatie na een inlogactie. Deze moeten wij allow-listen in ons systeem.