S-money API

Third-party application registration

Hadassa — 2016-07-06T10:29:26Z

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

Introduction

Hadassa — 2016-07-05T18:18:20Z

S-money ID uses the OpenID Connect 1.0 protocol, which is an identification layer on the OAuth 2.0 protocol. It allows the third-party application to verify the identity of an S-money user based on the authentication performed by the S-money server and also to obtain basic information about the user.
S-money ID is available in the S-money users area, and also in the dedicated users area.
In the next section of the document, the S-money user indicates the user of the domain which (...)

- V1

Enregistrer l'application tierce

Axel — 2015-07-28T17:06:49Z

Afin de récupérer les éléments d'authentifications de l'application tierce, il faut enregistrer l'application tierce au sein du SI S-money.

Cet enregistrement par le back-office S-money fait suite à l'établissement d'une relation commerciale entre l'intermédiaire propriétaire de l'application tierce et S-money. Une application tierce est associée à un utilisateur de rôle intermédiaire.

Les informations à fournir lors de l'enregistrement de l'application sont :

Les fonctions utilisables par l'application tierce
L'url de retour des appels à l'API S-money

En retour, S-money fournit un identifiant unique d'application tierce et un secret propre à l'application tierce.

Cinématique générale

Le protocole S-money ID suit les étapes suivantes :

L'application tierce envoie une requête à S-money
S-money authentifie l'utilisateur et obtient l'autorisation
S-money répond à l'application tierce avec un jeton d'identification (ID Token) et un jeton d'accès (Access token)
L'application tierce peut alors demander les informations de l'utilisateur via l'accès à la ressource UserInfo
S-money retourne la ressource UserInfo avec les revendications (Claims) associées à l'utilisateur

Formulaire de demande d'autorisation

Quand l'application tierce souhaite authentifier l'utilisateur S-money ou déterminer si l'utilisateur S-money est déjà authentifié, elle prépare une requête d'authentification à envoyer au serveur S-money.

Une fois cette requête d'authentification préparée, l'application tierce l'envoie au serveur S-money en utilisant le protocole HTTPS.

En général cet envoi est réalisé via une réponse http 302 Redirect qui provoque l'envoi par le navigateur de la requête d'authentification vers le serveur S-money :

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

Requête d'authentification

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

Paramètres :

client_id : (obligatoire) Identifiant de l'application tierce.
redirect_uri : (obligatoire) Uri de redirection
response_type : (obligatoire) doit être à "code"
scope : (obligatoire) droits demandés. Il doit obligatoirement contenir au moins la valeur openid
state : (obligatoire) utilisé par le client pour maintenir l'état de son application entre la requête et le callback.

Réponse

Si l'utilisateur est correctement authentifié par S-money, il sera alors redirigé vers :
RETURN_URL ?code=AUTH_CODE&state=STATE

Paramètres :

code : le code d'autorisation
state : retourne la valeur exacte passée à l'appel du formulaire.

Ci-dessous un exemple de redirection de l'utilisateur suite à authentification par le serveur S-money :

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

Authentification de l'application tierce

Pour chaque appel au point de terminaison oauth/token, il faut passer le header HTTP Authorization en mode Basic dans la requête :

Authorization : Basic CHAINE_ENCODEE

La chaine à passer est la combinaison de l'identifiant de l'application cliente (exemple : "appidentifier") et son secret, combinée comme suit : "appidentifier:secret", encodée ensuite en Base64.

Echange du code d'autorisation (auth code) contre les jetons d'accès et d'identification

De manière à obtenir les jetons d'accès et d'identification, L'application tierce effectue une requête présentant le code d'autorisation obtenue précédemment.

Requête

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

Paramètres :

grant_type : Doit être à "authorization_code".
code : le code d'autorisation préalablement récupéré.

Réponse

{

"access_token":"ACCESS_TOKEN",

"token_type":"Bearer",

"expires_in":1799,

"refresh_token":"REFRESH_TOKEN",

“Id_token”:”……”

}

Paramètres :

access_token : Le jeton d'accès qui permet de faire des appels à l'API S-money.
token_type : bearer
expires_in : temps de validité du token (en secondes)
refresh_token : permet de l'échanger contre un jeton valide lorsque le jeton d'accès aura expiré. Un jeton d'actualisation n'est valable qu'une seule fois.
Id_token : jeton de sécurité qui contient des revendications (Claims) concernant l'authentification de l'utilisateur par S-money. L'id-token est représenté comme un JSON Web Token.

Format des erreurs

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

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

Codes d'erreur possibles :

"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.

Format du jeton d'identification

Le jeton d'identification contient les claims suivants :

iss : contient la valeur https://rest.s-money.fr
sub : identifiant interne S-money de l'utilisateur
aud : identifiant de l'application tierce
exp : date/heure d'expiration du jeton en nombre de secondes depuis 1970-01-01T0:0:0Z en UTC
iat : date/heure à laquelle le jeton a été émis représentée en nombre de secondes depuis 1970-01-01T0:0:0Z en UTC

Le jeton est représenté sous la forme d'un token JWT, selon le format suivant :

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

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

Signature :
HMAC SHA-256(Base64URL(Entête).Base64URL(corps),secret), secret étant le secret de l'application tierce.
L'encodage BAS64URL est un encodage BASE64URL SANS padding, c'est-à-dire sans l'éventuel ajout du caractère ‘='.

Validation du jeton d'identification

Décodage du token JWT

A la réception du token JWT, l'application tierce réalise les étapes suivantes pour décoder le token JWT :

Séparer la chaine de caractères selon le caractère ‘.' de manière à isoler les 3 segments :
Base64URL(entête)
Base64URL(corps)
Base64URL(signature)
Décoder les segments Base64URL(entête) et Base64URL(corps) de manière à obtenir :

Entête
Corps
Validation du token JWT
Une fois le token JWT décodé,
Vérifier que l'entête est du JSON valide
Vérifier que le corps est du JSON valide
Vérifier que le paramètre alg de l'entête est bien ‘HS256'
Calculer la signature tel que décrit dans la section 2.5
Si l'encodage en base64URL de la signature calculée est égal au segment Base64URL(signature) du token JWT reçu, alors le token JWT est valide.

Validation de l'id_token

Une fois le token JWT validé, il est possible de valider l'id_token contenu dans le corps. Pour cela, les étapes à suivre par l'application tierce sont les suivantes :
La valeur du paramètre iss doit être égale à « rest.s-money.fr »
La valeur du paramètre aud doit être égale à l'identifiant (‘client_id') de l'application tierce
L'heure actuelle doit être avant la valeur du paramètre exp
Si la valeur du paramètre iat est trop ancienne par rapport à l'heure actuelle, alors le jeton doit être rejeté
Une fois l'id_token validé par l'application tierce, celle-ci peut considérer l'utilisateur comme authentifié.

La ressource UserInfo

La ressource UserInfo permet d'obtenir des informations associées à l'utilisateur authentifié.
Le paramètre sub est toujours retourné dans la réponse de la ressource UserInfo. Pour se protéger contre les attaques basées sur la substitution de jeton, l'application tierce doit vérifier que la valeur du paramètre sub est égale à la valeur qui était présente dans le paramètre sub de l'id_token. Si elles ne sont pas égales la ressource UserInfo ne doit pas être utilisée (et un dispositif d'alerte mis en place permettant d'investiguer une éventuelle attaque).
Les informations inclues dans la réponse de la ressource UserInfo dépendent de la valeur du paramètre scope de la requête d'autorisation ayant permis d'obtenir les jetons d'accès et d'identification. Le tableau ci-dessous présente les valeurs possibles pour le paramètre scope.

openid	requis	Informe le serveur S-money que l'application tierce effectue une requête S-money ID
profile	Optionnel	Permet d'obtenir le prénom (name), le nom de famille (family_name), la date de naissance (birth_date) de l'utilisateur
email	Optionnel	Permet d'obtenir l'email de l'utilisateur (email) et/ou l'email vérifié de l'utilisateur (email_verified)
address	Optionnel	Permet d'obtenir l'adresse de l'utilisateur avec les informations suivantes : street_address, locality, postal_code, country
phone	Optionnel	Permet d'obtenir le téléphone mobile (phone) et/ou le téléphone mobile vérifié de l'utilisateur (phone_verified)
offline_access	Optionnel	Permet de demander un refresh token qui puisse être utilisé pour obtenir la ressource UserInfo même si l'utilisateur n'est pas connecté

Ci-dessous un exemple de scope :

scope=openid profile email phone

L'obtention de la ressource UserInfo se fait par l'application tierce de la manière suivante.

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

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

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

Gestion des sessions

Vérification de la session

Dans le but de vérifier la validité de la session, l'application tierce doit recommencer la demande d'autorisation en précisant les paramètres supplémentaires :

prompt	Requis	Défini l'interaction du serveur S-money avec l'utilisateur, obligatoirement valorisé à « none » dans ce cas
id_token_hint	Requis	id_token précédemment utilisé

Si la session n'est plus valide, l'erreur retournée sera « login_required ». Si la session est valide le scénario standard s'applique.

Fin de session

L'application tierce peut initier la fin de session de l'utilisateur, elle redirige alors l'utilisateur vers l'endpoint de fin de session.

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

Paramètres :
id_token_hint : (obligatoire) id_token courant récupéré à la requête d'authentification
post_logout_redirect_uri : (obligatoire) Uri de redirection
state : (obligatoire) utilisé par le client pour maintenir l'état de son application entre la requête et le callback.

L'utilisateur sera alors déconnecté et redirigé vers :
RETURN_URL ?code=AUTH_CODE&state=STATE

Introduction

Axel — 2015-07-28T17:05:58Z

S-money ID utilise le protocole OpenID Connect 1.0, qui est une couche d'identification sur le protocole OAuth 2.0. Il permet à l'application tierce de vérifier l'identité d'un utilisateur S-money basé sur l'authentification réalisée par le serveur S-money, ainsi que d'obtenir des informations basiques sur l'utilisateur.

S-money ID est disponible sur le domaine d'utilisateurs S-money ainsi que sur les domaines d'utilisateurs dédiés.

Dans la suite du document, l'utilisateur S-money désigne l'utilisateur du domaine avec lequel l'application tierce interagit.