V1

Third-party application registration

In order to retrieve the authentication elements of the third-party application, it is necessary to register the third party application within the Si S-money.

This registration by the S-money back office follows the establishment of the commercial relationship between the intermediary owner of the third-party application and S-money. A third-party application is associated to an intermediary role user.

During the registration of the application, the following information must be provided :
- Functions usable by the third-party application
- The return url for requests sent to S-money API

In return, S-money provides a unique identifier of the third-party application and specific to the third-party application.

General kinematics

The S-money Id protocol follows such stages :

  • The third-party application sends an S-money request
  • S-money authenticates the user and obtains authorisation.
  • S-money replies to the third-party application with an identification token (ID token) and an access token (Access token)
  • The third-party application can ask for the user information via access to the UserInfo resource
  • S-money returns the UserInfo resource with claims associated to the user

Authorisation request form

When the third-party application wants to authenticate an S-money user or determine whether an S-money user is already authenticated, it prepares an authentication request to send to the S-money server.

Once such authentication request is prepared, the third-party application sends it to the S-money server using the HTTPS protocol.

Generally, this sending is made via http 302 Redirect response which provokes sending through the browser of the authentication request to the S-money server :

HTTP/1.1 302 Found
Location : https://rest.s-moneyfr/oauth/authorize?
response_type=code
&client_id=…
&redirect_uri=…
&scope=openid …
&state=…

Authentication request

https://rest.s-money.fr/oauth/Home/authorize ?
client_id=YOUR_APP_ID
&redirect_uri=RETURN_URL
&response_type=code
&scope=openid SCOPE
&state=STATE
&role=ROLE

Parameters :

  • client_id : (mandatory) Third-party application identifier.
  • redirect_uri : (mandatory) Uri of redirection
  • response_type :(mandatory) must be a "code"
  • scope  : (mandatory) requested rights. It must contain at least the openid value.
  • state  : (mandatory) used by the client in order to maintain the status of his/her application between the request and the callback.

Response

If the user is correctly authenticated by S-money, he/she will redirected to :
RETURN_URL ?code=AUTH_CODE&state=STATE

Parameters :

  • code : authorisation code
  • state  : return the exact value send to the form.

See the below example of the user redirection after authentication by the S-money server :

HTTP/1.1 302 Found
Location : https://client.example.org/cb ?
code=….
&state=…

Third-party application authentication

For each request at the token termination point, the HTTP Authorization header needs to be changed into the Basic mode in the request :

Authorization : Basic CHAINE_ENCODEE

The sequence to pass constitutes a combination of a client application identifier (example : "appidentifier") and his/her secret, combined as follows : "appidentifier:secret", later encoded in Base64.

Exchange of the authorisation code (auth code) against access tokens and identification

To obtain the access tokens and identification makes a request presenting an authorisation code received earlier.

Request

POST /oauth/token HTTP/1.1
Content-Type : application/x-www-form-urlencoded
Content-Length : 81
Authorization : Basic CHAINE_ENCODEE
grant_type=authorization_code&code=AUTH_CODE&redirect_uri=RETURN_URL

Parameters :

  • grant_type : Should be to "authorization_code".
  • code :the authorisation code retrieved beforehand.

Response

{
"access_token":"ACCESS_TOKEN",
"token_type":"Bearer",
"expires_in":1799,
"refresh_token":"REFRESH_TOKEN",
“Id_token”:”……”
}

Parameters :

  • access_token : Le jeton d’accès qui permet de faire des appels à l’API S-money.
  • token_type : bearer
  • expires_in : token validation time (in seconds)
  • refresh_token : allows to exchange a valid access token against an expired one. An actualisation token is valid only once.
  • Id_token : a security token which contains claims concerning the authentication of the user by S-money. The id-token is represented as a JSON Web Token.

Errors format

HTTP/1.1 400 Bad Request
Content-Type : application/json

"error" :"CODE_ERREUR",
"error_description" :"DESCRIPTION"

Possible error codes: :

  • "invalid_request" : The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
  • "invalid_client" : Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)
  • "unauthorized_client" : The client is not authorized to request an authorization code or access token using this method.
  • "access_denied" : The resource owner or authorization server denied the request.
  • "invalid_grant" : The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
  • "unsupported_grant_type" : The authorization grant type is not supported by the authorization server.
  • "unsupported_response_type" : The authorization server does not support obtaining an authorization code using this method.
  • "invalid_scope" : The requested scope is invalid, unknown, or malformed.
  • "server_error" : The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
  • "temporarily_unavailable" : The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

The identification token format

The identification token contains the following claims :

  • iss : contains the value https://rest.s-money.fr
  • sub : S-money internal identifier of the user
  • aud : third-party application identifier
  • exp : expiry date/hour of a token with a number of seconds from 1970-01-01T0:0:0Z in UTC
  • iat : date/hour at which a token was issued represented in a number of seconds from 1970-01-01T0:0:0Z in UTC

The token is presented in the form of a JWT token, according to the following format :

Base64URL(Entête).Base64URL(corps).Base64URL(signature)
Avec :
 Header :
"type" :"JWT",
"alg" :"HS256"

Body :

"iss" : "https://rest.s-money.fr",
"sub" : "…",
"aud" : "…",
"exp" : …,
"iat" : …

Signature :
HMAC SHA-256(Base64URL(header).Base64URL(body),secret), where secret is the secret key of the third-party application. .
The BAS64URL encoding is a BASE64URL encoding without padding, which means without adding the ‘=’ character.

Token identification validation

JWT token decoding

Upon receipt of the JWT token, the third-party application follows the following stages to decode the JWT token :

Separate the character sequence according to the ‘.’ character in order to isolate the 3 segments :
Base64URL(header)
Base64URL(body)
Base64URL(signature)
Decode the Base64URL (header) and Base64URL(body) segments in order to obtain :

Header
Body
JWT token validation
Once the JWT token is decoded,
Check if the header is JSON valid
Check if the body is JSON valid
Check if the alg parameter of the header is ‘HS256’
Calculate the signature as described in the 2.5 section
If the base64URL decoding of the signature calculated equals the Base64URL segment (signature) of the JWT token, then the JWT token is valid.

ID token validation

Once the JWT token is validated, it is possible to validate the id_token included in the body. In order to do it, the following stages need to be completed :
The iss parameter value needs to equal to « rest.s-money.fr »
The aud parameter value needs to equal to the identifier (‘client_id’) of the third-party application
The current hour needs to be before the exp parameter value
If the iat parameter value is too old in relation to the current hour, then the token needs to be rejected.
Once the id_token is validated by the third-party application, then the user can can be considered as authenticated.

UserInfo resource

The UserInfo resource allows to obtain the information associated to the authenticated user.

The sub parameter is always returned in the response of the UserInfo resource. To prevent attacks based on token substitution, the third-party application needs to verify that the sub parameter value equals to the value that was presented in the sub parameter of the id_token. If they do not equal the Userinfo resource should not be used (and an alert disposition needs to be established allowing to investigate the potential attack).

The information included in the response of the UserInfo resource depends on the scope parameter value of the authorisation request which allows to obtain access and identification tokens. The table below presents the possible values for the scope parameter.

openid required Informs the S-money server that the third-party application makes an S-money ID request
profile Optional Allows to obtain the name (name), the family name (family_name), the date of birth (birth_date) of the user
email Optional Allows to obtain the user’s e-mail (email) and/or user’s verified e-mail (email_verified)
address Optional Allows to obtain the user’s address with the following information : street_address, locality, postal_code, country
phone Optional Allows to obtain the mobile number (phone) and/or the verified mobile phone of the user (phone_verified)
offline_access Optional Allows to request a refresh token that can be used to obtain the resource UserInfo, even if the user is not connected

Below a scope example :

scope=openid profile email phone

Obtaining the UserInfo resource through the third-party application involves the following steps.

Request :

GET /api/[domaine]/UserInfo HTTP/1.1
Accept : application/vnd.s-money.v1+json
Authorization : Bearer ACCESS_TOKEN

Response :
HTTP/1.1 200 OK
Content-Type : application/vnd.s-money.v1+json

sub : “…”,
family_name :”…”,
name :”…”,
birthdate :”….”,

Session management

Session verification

In order to verify the validity of the session, the third-party application should restart the authorisation request specifying additional parameters :

prompt Required Define the S-money interaction with the user, always set to « none » in such a case
id_token_hint Required id_token previously used

If the session is no longer valid, the returned error will be « login_required ». If the session is valid, the standard scenario will apply.

End of session

The third-party application can initiate to end a user’s session, it redirects the user towards the endpoint of the session end.

https://rest.s-money.fr/oauth/connect/endsession ?
Id_token_hint=ID_TOKEN
&post_logout_redirect_uri=RETURN_URL
&state=STATE

Parameters :
id_token_hint : (mandatory) current id_token retrieved at the authentication request
post_logout_redirect_uri  : (mandatory) redirection Uri
state  : mandatory) used by the client to maintain the application state between the request and the callback.

The user will be then disconnected and redirected towards :
RETURN_URL ?code=AUTH_CODE&state=STATE