Ga naar hoofdinhoud

Authenticatie

Authenticatie geschiedt op basis van JWT tokens. Na succesvol inloggen krijgt een gebruiker een Refresh token, waarmee hij een Access token kan opvragen dat toegang geeft tot de API.

Endpoints​

Login met username/password (geen 2FA in configuratie)​

Endpoint: /auth/knowledge

Argumenten:

  • loginName (verplicht)
  • password (verplicht)

Resultaat (in volgorde van als):

  • 401 Unauthorized als login niet juist is
  • 200 OK met de body:
{
  "accessToken": JWT token met Role=Access
  "refreshToken": JWT token met Role=Refresh
}

Login met username/password (2FA in configuratie)​

Endpoint: /auth/knowledge

Argumenten:

  • loginName (verplicht)
  • password (verplicht)
  • possessionToken (optioneel)

Resultaat (in volgorde van als):

  • 401 Unauthorized als login niet juist is
  • 200 OK als possessionToken geldig is met de body:
{
  "accessToken": JWT token met Role=Access,
  "refreshToken": JWT token met Role=Refresh
}
  • 200 OK met de body:
{
  "knowledgeToken": JWT token met Role=Knowledge,
  "seed": de seed,
  "challenge": de challenge,
  "channel": het medium waarmee de tweede factor wordt benaderd,
  "sequenceNumber": het volgnummer
}

Tweede factor​

Endpoint: /auth/possession

Argumenten:

  • seed (verplicht)
  • response (verplicht)
  • knowledgeToken (verplicht)

Resultaat (in volgorde van als):

  • 401 Unauthorized als knowledgeToken niet geldig is
  • 401 Unauthorized als seed + response niet geldig is
  • 200 OK met de body:
{
  "accessToken": JWT token met Role=Access,
  "refreshToken": JWT token met Role=Refresh,
  "possessionToken": JWT token met Role=Possession
}

Externe login (init)​

Endpoint: /auth/{identityProvider}/init

Resultaat (in volgorde van als):

  • 404 Not Found als identityProvider niet bekend is
  • 200 OK met de body:
{
  loginUrl: de login url,
  logoutUrl: de logout url
}

Externe login (verificatie)​

Endpoint: /auth/{identityProvider}/verify

Argumenten:

  • code (verplicht)

Resultaat (in volgorde van als):

  • 404 Not Found als identityProvider niet bekend is
  • 401 Unauthorized als code niet geldig is
  • 401 Unauthorized als code niet te vertalen is naar een gebruiker (op basis van loginnaam/e-mailadres)
  • 200 OK met de body:
{
  "accessToken": JWT token met Role=Access,
  "refreshToken": JWT token met Role=Refresh
}

Refresh​

Endpoint: /auth/refresh

Argumenten:

  • refreshToken (verplicht)

Resultaat (in volgorde van als):

  • 401 Unauthorized als refreshToken niet geldig is
  • 401 Unauthorized als gebruiker in refreshToken niet actief is
  • 200 OK met de body:
{
  "accessToken": JWT token met Role=Access,
  "refreshToken": JWT token met Role=Refresh
}

User flows​

Gebruiker logt in zonder 2FA​

  1. Logt in met username en password (knowledge)
  2. Onthoudt refresh+access tokens
  3. Gebruikt API tot access token is verlopen
  4. Verkrijgt nieuw refresh+access tokens (refresh)
  5. etc

Gebruiker logt in met 2FA (1e keer)​

  1. Logt in met username en password (knowledge)
  2. Stuurt response op challenge op (possession)
  3. Onthoudt refresh+access+possession tokens
  4. Gebruikt API tot access token is verlopen
  5. Verkrijgt nieuw refresh+access tokens (refresh)
  6. etc

Gebruiker logt in met 2FA (vorige 2FA is nog geldig)​

  1. Logt in met username en password en possessionToken (knowledge)
  2. Onthoudt refresh+access tokens
  3. Gebruikt API tot access token is verlopen
  4. Verkrijgt nieuw refresh+access tokens (refresh)
  5. etc

Gebruiker logt in met externe inlog (Microsoft/Google)​

  1. Verkrijgt URL om in te loggen ({identityProvider}/init)
  2. Wordt geredirect naar de URL en logt daar in
  3. Wordt geredirect terug met code
  4. Verifieert code ({identityProvider}/verify)
  5. Onthoudt refresh+access tokens
  6. Gebruikt API tot access token is verlopen
  7. Verkrijgt nieuw refresh+access tokens (refresh)
  8. etc