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 fromiat
- 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
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 |