Using OAuth 2.0 for B2B with the client credentials grant
This flow (Client Credentials Grant) is used in scenarios where a server needs to make secured calls to an API, without user interaction or consent. It can only be used by confidential clients who are in possession of a client secret, and where the resource owner of the API is the same as the client itself. If you are not writing your client for your own organisation then you should look at the B2B with authorization code grant scenario.
In B2B scenario’s, for example batch applications, these processes do not have the interactive capabilities to ask consent of the user to access an API on behalf of the user. This document describes how you can obtain OAUth2.0 access tokens to an API in a B2B scenario with the client credentials grant
Obtaining the client
As in all OAuth 2.0 scenarios, you will first need to register your client with Digitaal Vlaanderen. In order to register your client contact the Digitaal Vlaanderen Security team.
To register a B2B client we need the following information:
- A descriptive name of your client.
- A contact with a valid Digitaal Vlaanderen account. You can register at https://oauth.vlaanderen.be
- The scopes your client needs, to access the API (consult the documentation of the API)
- Your scenario that you chose, in this case Client Credentials Grant
After successful registration the contact will receive an e-mail containing a link to a page to manage his registered client(s).
On this page the contact can:
- upload a JSON Web Key for client authentication
- upload a certificate for client authentication that will be wrapped in a JSON Web Key
- obtain the client id and client secret.
- regenerate the client secret.
- Invalidate the tokens
Overview Flow
Step 1
The client authenticates with the authorization server and requests an access token from the token endpoint at https://oauth.vlaanderen.be/ws/oauth/v2/token/
Step 2
The client receives an access token response
Obtaining access tokens
After you have the client ID and client secret or JSON Web Key, you can send an HTTP POST to the OAuth 2.0 token endpoint at https://https://oauth.vlaanderen.be/authorization//ws/oauth/v2/token/.
| Endpoint | Description | Method |
|---|---|---|
| https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ | This endpoint is the target of the initial request to exchange an authorization code for an access token. | HTTP-POST |
The body is composed of the following parameters.
| Parameter | Values | Description | Required |
|---|---|---|---|
grant_type |
client_credentials | Value MUST be set to "client_credentials". | Yes |
scope |
The scope of the access request. | One or more of the scope values available for the specified client. See the OAuth administration site for available scopes. Multiple scopes must be space seperated. | No (if a default scope is defined for the specified client, otherwise Yes) |
Client Authentication values
You also need to authenticate the client, you can find information in client authentication
The client authentication methods that are allowed are:
If you use a JSON Web Token the audience for this call in the JWT token must be:
-
https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token
Examples
POST https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: oauth.vlaanderen.be
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&scope=MapRequestInitiator
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imo5c1ZrNU9INVlOQS1uMS00bDdUM013UVJJUSJ9.eyJzdWIiOiI3ODk0NTYiLCJpc3MiOiI3ODk0NTYiLCJleHAiOiIxNTE2MjQwMDIyIiwiaWF0IjoiMTU1MjkwOTYwMSIsImp0aSI6IjYzMjMzY2Q5LTIxYjgtNGZhMS04ODU4LTY2YjcxNWY3YTg2NiIsImF1ZCI6Imh0dHBzOi8vb2F1dGgudmxhYW5kZXJlbi5iZS9hdXRob3JpemF0aW9uL3dzL29hdXRoL3YyL2F1dGhvcml6YXRpb24ifQ.dPWB45Fe-ctNq5Q5bwGSVfFjbVoGMd6mrKzd3V9Xaq136vnAABYstr9v0E-rTz_VjoHJOpS23336-3ooDEl-bahfVJhpsjTW2_8X8eU9Jdyznl5VWpLKfAmHW9ycWupMf3jeCGfbLe5e1Nj1AmMuvufwawpb8-c9XuRoJoK6y232gRa-xfBQxJMcaS8L9qxYVLecPeqQjnjAs0qDOzrRzyIDLC9fBUG0UeC4sd_rEMSgBSj_N5uMbg4hyV6HB6-WuJy0R_MWFRq_fgqa3vRqDd9D0epLc-_QugfeGgdryKer57WLtbYfDXWoXEgsKmqToHyZx2G96ohuIqws3ytxxg
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
POST https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: oauth.vlaanderen.be
Authorization: Basic Nzg5NDU2OjI5OE1TR0hTSlk5MzI3MzI1M0dJREdJRFpOX1ZDWDJIJTNEJTNE
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&scope=MapRequestInitiator
The body only contains extra newlines for readability. Be sure to url-encode the clientId and the clientsecret before encoding it in base64.
Handling the response
The OAuth 2.0 Authorization Server returns an access token to the client if it successfully authenticates the client. The body of the response is a json result.
| Property | Values | Description |
|---|---|---|
access_token |
A string representing the access token issued by the OAuth 2.0 Authorization Server | The access token issued by the OAuth 2.0 Authorization Server |
token_type |
bearer | The access token is a bearer token. |
expires_in |
A numeric value | The lifetime of the access token in seconds starting from the time the token was issued. |
scope |
Space delimited set of scopes the resource owner granted the client. | The scopes specified can be different from the requested scopes when the resource owner doesn't or can't grant all of the requested scopes. |
Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"MOB1ZkyrqdSay4-xm39Z6A==",
"token_type":"bearer",
"expires_in":3600
}
Upon receipt of this response, your application may use the access token in API requests.
Access tokens have a limited lifetime. The client should cache the access token for the validity of the token, and only request a new token when this access token is expired. Throttling may apply if too many requests for the same clientId reaches the OAuth 2.0 authorization server.
Handling an error
The OAuth 2.0 Authorization Server returns an error as a json result to the client if the request parameters are not correct or an access token could not be issued.
| Property | Value | Description |
|---|---|---|
error |
invalid_client |
Client authentication failed |
unsupported_grant_type |
The OAuth 2.0 Authorization Server does not support obtaining an access token of the specified grant type using this method. | |
invalid_scope |
The requested scope is invalid, unknown, or malformed. | |
unauthorized_client |
The client is not authorized to request an access token using this method. | |
invalid_request |
The request is missing required parameters or is malformed. | |
error_description |
Descriptive text to provide additional information about the error. | |
Example
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
Calling an API
When your application has received an access token, you can access an API by including the access token in the Authorization HTTP Header using the Bearer scheme.
For example a call to an API using the access_token Authorization: Bearer HTTP header looks as follows:
GET https://api.vlaanderen.be/ws/klip/v1/maprequest HTTP/1.1
Authorization: Bearer LTgaAik7F-smmQ65_nVfag==
Host: api.agiv.be
When HTTP Header operations are not possible, for example when using the url in an image src attribute, the access token can be incuded as a query string parameter.
For example, a call to the API using the access_token query string parameter looks like the following:
GET https://api.vlaanderen.be/ws/klip/v1/maprequest?access_token=LTgaAik7F-smmQ65_nVfag== HTTP/1.1