OAuth 2.0 Authenticatie

TrackJack maakt gebruik van de meest gebruikte methode voor veilige gebruikersauthenticatie: Authorization Code Flow. Deze flow is speciaal ontworpen voor zowel vertrouwelijke als publieke clients die op een veilige manier tokens moeten verkrijgen. De flow werkt op basis van redirects en maakt het mogelijk voor de client om een kortdurende autorisatiecode om te wisselen voor tokens via het token-endpoint.

OAuth 2.0 en OpenID Connect definiëren een set standaardflows die door clientapplicaties (webapps, single-page apps, mobiele apps en backendservices) worden gebruikt om gebruikers te authenticeren of toegangstokens te verkrijgen. Deze gids beschrijft hoe clients communiceren met de provider via veelgebruikte flows zoals de Authorization Code Flow.

Om met behulp van OAuth te integreren, moet elke applicatie een unieke client ID en client secret hebben. Heb je deze nog niet? Dien dan een verzoek in bij ons team. Vermeld duidelijk om welke applicatie het gaat en hoe deze gebruik zal maken van onze API. Vergeet niet een redirect URI op te geven.

Clientintegratiegids voor Authorization- en Token-endpoints

Deze gids legt uit hoe een clientapplicatie zich kan authenticeren en autoriseren bij de TrackJack  OAuth- / OpenID Connect-provider met behulp van de Authorization Code Flow.

Belangrijke endpoints

• Authorization endpoint: /connect/authorize — wordt gebruikt om de login- en toestemmingsflow te starten.
• Token endpoint: /connect/token — wordt gebruikt om access tokens, ID tokens en refresh tokens op te halen.
• Discovery document: /.well-known/openid-configuration — bevat metadata over endpoints, scopes, signing keys, enzovoort.

1. Clientregistratie (aan de kant van de OAuth-provider)

Bij het registreren van een client worden de volgende instellingen geconfigureerd:

• Client ID: een unieke identifier voor jouw integratie.
• Client Secret: gedeeld geheim (indien je client vertrouwelijk is).
• Redirect URI(s): de URL waar de gebruiker na autorisatie terug naartoe wordt gestuurd
  (bijvoorbeeld: https://yourapp.com/oauth/callback).
• Grant Types: doorgaans authorization code (en eventueel refresh token).
• Scopes: bijvoorbeeld openid, profile.
• Opmerking: gebruik offline_access wanneer je gebruik wilt maken van refresh tokens.

Discovery / Metadata

Je client moet het discovery-document ophalen (of hiermee geconfigureerd worden):

GET https://login.trackjackeurope.com/.well-known/openid-configuration

Het discovery-document bevat onder andere:

• authorization_endpoint
• token_endpoint
• userinfo_endpoint (indien ondersteund)
• jwks_uri (publieke sleutels)
• Ondersteunde scopes en response_types

Authorization Code Flow (Gebruiker + Webapp)

Dit is de standaardflow voor webapplicaties of integraties waarbij een gebruiker jouw applicatie moet autoriseren.

Stap 1 — Redirect de gebruiker naar het Authorization Endpoint

Jouw client start de flow door de gebruiker te redirecten naar:

GET https://login.trackjackeurope.com/connect/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/oauth/callback
  &response_type=code
  &scope=openid profile email

Stap 2 — Gebruiker logt in + geeft toestemming

TrackJack toont een inlogscherm (als de gebruiker nog niet is ingelogd) en vraagt de gebruiker om toestemming voor de gevraagde scopes.

Stap 3 — Ontvang de Authorization Code

Na toestemming stuurt TrackJack de gebruiker terug naar jouw redirect_uri met:

https://yourapp.com/oauth/callback?code=AUTH_CODE

Stap 4 — Wissel de code om voor tokens

Jouw backend (of client) verstuurt een POST-request:

POST https://login.trackjackeurope.com/connect/token

Content-Type: application/x-www-form-urlencoded grant_type=authorization_code

Stap 5 — Ontvang de tokenresponse

Je ontvangt een JSON-object zoals:

Postman

Postman biedt een ingebouwde manier om de OAuth 2.0 Authorization Code Flow te simuleren.

Stappen:

1. Open Postman en selecteer de request die je wilt autoriseren.
2. Ga naar het tabblad Authorization.
3. Stel Type in op OAuth 2.0.
4. Klik op Get New Access Token.
5. Vul de volgende velden in:
   • Token Name: TrackJack Test Token
   • Grant Type: Authorization Code
   • Callback URL: https://oauth.pstmn.io/v1/browser-callback
   • Auth URL: https://login.trackjackeurope.com/connect/authorize
   • Access Token URL: https://login.trackjackeurope.com/connect/token
   • Client ID: jouw geregistreerde client ID
   • Client Secret: jouw geregistreerde client secret (bij vertrouwelijke clients)
   • Scope: openid profile email

6. Klik op Request Token en doorloop de login-/consentflow.

7. Postman ontvangt vervolgens automatisch het access token, dat je daarna kunt gebruiken in je requests.

Opmerking: Dit maakt het mogelijk om de OAuth-flow te testen zonder dat je eerst een volledige clientapplicatie hoeft te bouwen.

Using the Access Token

Authorization: Bearer <access_token> 

POST   https://login.trackjackeurope.com/connect/token

Content-Type: application/x-www-form-urlencoded

Scopes

OAuth scopes zijn toegangsrechten die een gebruiker aan een applicatie kan verlenen. Scopes zijn gekoppeld aan access tokens. Bij authorisatie  lees je hoe je applicatie gebruikers om toegang kan vragen.

Hier volgt een overzicht van alle scopes die door de TrackJack API worden gebruikt.

Vraag nooit meer scopes dan strikt noodzakelijk is voor het functioneren van jouw integratie.