Authorization API documentation

Authentication with your confidential client

This page describes how you can authenticate your client. There are different ways to do this, where one option is a bit safer than others.

There are two types of credentials that can be used with the OAuth 2.0 Server.

  • Through a JSON Web Token with asymetric key
  • Through a clientId and a clientSecret

JSON Web Token

A JSON Web Token can be put in the body of the request. These are the requirements of the token :

  • An asymmetric JSON Web Key that has been uploaded to your client on the website https://oauth.vlaanderen.be/admin/. We provide tooling to generate this JSON WebKey here.
  • A kid key identifier defined in the header of the JSON web token, this should be the certificate SHA1 thumbprint if the JSON Web Key itself is an X509 certificate
  • An iss claim containing the client_id of the OAuth Client in the payload of the JSON web token
  • A sub claim containing the client_id of the OAuth Client in the payload of the JSON web token
  • A jti claim in the form of a GUID that is generated randomly and is different for each token request in the payload of the JSON web token
  • An exp claim indicating the expiration time of the token in the payload of the JSON web token, it should not exceed ten minutes from iat
  • An iat claim indicating at which time the JWT was issued in the payload of the JSON web token
  • An aud claim containing the url endpoint you are calling without trailing slash in small case in the payload of the JSON web token
The authentication with a JSON Web Token is the preferred method. The JSON Web Key can be a certificate, or a generated asymmetric key.

JWT Valid example

Header

{
  "alg": "RS256",
  "kid": "j9sVk5OH5YNA-n1-4l7T3MwQRIQ",
  "typ": "JWT"
}

Payload

{
  "sub": "1234",
  "iss": "1234",
  "iat": 1552909601,
  "exp": 1552909700,
  "jti": "63233cd9-21b8-4fa1-8858-66b715f7a866",
  "aud": "https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token"
}

The audience will be different for revocation than for tokens and will be different for environments, check the audience requirements in the different flows for more information.

Incorporation of the JSON Web Token in the body of the request

The body must contain following items:

Parameter Values Description Required Example
client_assertion The JSON web token itself Contains a signed JSON web token with a private key with above fields required Yes ...&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imo5c1ZrNU9INVlOQS1uMS00bDdUM013UVJJUSJ9.eyJzdWIiOiIxMjM0IiwiaXNzIjoiMTIzNCIsImV4cCI6IjE1MTYyNDAwMjIiLCJpYXQiOiIxNTUyOTA5NjAxIiwianRpIjoiNjMyMzNjZDktMjFiOC00ZmExLTg4NTgtNjZiNzE1ZjdhODY2IiwiYXVkIjoiaHR0cHM6Ly9vYXV0aC52bGFhbmRlcmVuLmJlL2F1dGhvcml6YXRpb24vd3Mvb2F1dGgvdjIvYXV0aG9yaXphdGlvbiJ9.gDFW2QvJVPytiXD6mEieO-2Iyaf4DMhfKO7iP6bc9Ep9fjNcnykf0bdpNqA_F5wvDukQ6f4U9mRtbbIEWbNCMRXs1NqxYvLADmVAkJFKN6yw5WdQuAEBp3LwVxMGbmyWRYa4ZHZbFiC0928WEjhjewKX_VIDjXhk4476F_YrsB7BZIL-lqj0I6vxKbmBhiuzCT4SQtTMag4HvnHc3tvlaQUcfgMMwlX7X803Vyyg_-yPuirv_cAb15EOzPDl7ZJ0b-Z-wY92xcW1wxibokKZGn-jk8gvMM3KitWvXE62uJLQtv0APqsnu6uxL86ErU9VCTcbMi9-atrofJe7GtuhYg
client_assertion_type An assertion type, thus must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer This is the assertion type that must be provided for a jwt token Yes ...&client_assertion=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer

ClientId and ClientSecret

For legacy clients we allow clientId and clientSecret. The clientId and clientSecret can be placed in the header or in the body. This depends on the flow used.

ClientId and ClientSecret in the Authorization Header

The headers must contain following items:

Parameter Values Description Required Example
Authorization Basic clientId:clientSecret The clientId and clientsecret must be urlencoded.
The Basic scheme has to be used as defined in RFC-7617 In pseudocode you need to do this: Basic {Base64Code(UrlEncode(clientId)+":"+UrlEncode(clientSecret))}
Yes Authorization: Basic Nzg5NDU2OjI5OE1TR0hTSlk5MzI3MzI1M0dJREdJRFpOX1ZDWDJIJTNEJTNE
This translates to a clientId with value 789456 and a client secret with value 298MSGHSJY93273253GIDGIDZN_VCX2H== after base64 decoding and url decoding
Content-Type application/x-www-form-urlencoded This content-type must be used for the client credentials grant Yes

ClientId and ClientSecret in the body

Parameter Values Description Required Example
client_id integer Your client Identifier as found on https://https://oauth.vlaanderen.be/admin/ Yes ...&client_id=1234
client_secret URL encoding of the clientsecret Your client secret as found on https://https://oauth.vlaanderen.be/admin/ Yes ...&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw