Obtaining an access token from the Social Security OAuth server
The access token request is made using the ’OAuth 2.0 Client Credentials’ protocol with the ’Client Assertion’ authentication method. You can find more information about the ’OAuth 2.0 Client Credentials’ protocol in RFC 6749. The ’Client Assertion’ authentication method is described in RFC 7521. To assist you in this integration, please find the relevant information from those RFC below.
access token request
The client credentials flow includes the following steps:
- The client authenticates with the authorization server and requests an access token from the token endpoint.
- The authorization server authenticates the client, and if valid, issues an access token.
The client authenticates by sending a signed JWT assertion to the token endpoint as described in section 4.2 of RFC 7521. The request is done by adding the following parameters using the ’application/x-www-form-urlencoded’ format with a character encoding of UTF-8 in the HTTP request entity-body:
| Parameter name | Req. level | Expected value |
|---|---|---|
| grant_type | REQUIRED | Value must be set to ’client_credentials’. |
| client_assertion_type | REQUIRED | Value must be set to ’urn:ietf:params:oauth:client-assertion-type:jwt-bearer’. |
| client_assertion | REQUIRED |
A signed JWT that authenticates the client with the authorization server as described in RFC 7519. The content of the JWT is described in section ’Client authentification’ below. |
| scope | OPTIONAL |
The scope of the access request. If omitted, your client's default scopes will be selected.
info
Recommendation: Do not provide this parameter unless you want to specifically restrict client access.
|
For example, the client makes the following HTTP request using transport-layer security:
POST /REST/oauth/v5/token HTTP/1.1
Host: services.socialsecurity.be
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi[...omitted for brevity...].cC4hiUPo[...omitted for brevity...]Client authentification
The client assertion is a signed JWT (JWS) that authenticates the client with the authorization server as described in RFC 7519. The claims attributes expected in the payload (content) of the JWT are described in the following table.
| Attribute name | Req. level | Value type | Expected value |
|---|---|---|---|
| jti | REQUIRED | string | The ’jti’ (JWT ID) claim provides a unique identifier for the JWT. |
| iss | REQUIRED | string or URI |
The ’iss’ (issuer) claim identifies the principal that issued the JWT.
info
The value must match the ’Client ID’ which was generated in Chaman.
|
| sub | REQUIRED | string or URI |
The ’sub’ (subject) claim identifies the principal that is the subject of the JWT.
info
The value must match the ’Client ID’ which was generated in Chaman.
|
| aud | REQUIRED | string or URI |
The ’aud’ (audience) claim identifies the recipients that the JWT is intended.
info
The value must be ’https://services.socialsecurity.be/REST/oauth/v5/token’.
|
| exp | REQUIRED | number (numeric date in seconds) |
The ’exp’ (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
info
The website https://unixtime.org/ could help you visualize the expected format (epochtime/unixtime)
|
| nbf | OPTIONAL | number (numeric date in seconds) | The ’nbf’ (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. |
| iat | OPTIONAL | number (numeric date in seconds) | The ’iat’ (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. |
The JWT should be signed according to the RFC 7515 specification. Please use one of the recommended algorithm according to section 3.1 of RFC 7518.
Access token response
If your client authentication succeeded, you should receive an access token response conforming to section 4.4.3 of RFC 6749.
Social Security access token have a 10 minutes validity period. As a client, you will need to manage the lifecycle of this access token and request another one when it is about to expire.
Please avoid renewing your access token unless the validity period is almost expired (less than 1 minute remaining).