Identity Cloud et OAuth2

Mysoleas Identity Cloud est le service de gestion des utilisateurs de l’ecosysteme Mysoleas. Vous pouvez l’integrer dans votre site, votre application mobile ou votre SaaS pour gerer l’authentification, les sessions utilisateur et les profils sans reconstruire toute cette couche vous-meme. Concretement, votre application peut utiliser Mysoleas Identity Cloud pour:

afficher le bouton Se connecter avec Mysoleas;
authentifier un utilisateur avec OAuth2/OIDC;
recuperer un JWT utilisateur et les claims utilisateur;
lire le profil utilisateur avec userinfo;
deleguer la gestion de session et d’identite a Mysoleas;
se concentrer sur le metier propre de votre application.

Vous n’avez pas besoin d’appeler la gateway pour utiliser Identity Cloud. Identity Cloud ne doit pas etre presente comme le moyen principal de se connecter a l’ecosysteme metier Mysoleas: il gere vos utilisateurs. Si votre application consomme ensuite les endpoints gateway SoleasPay, creez une application dans SoleasPay et utilisez son client_id et son client_secret pour obtenir le token d’application attendu par x-sp-auth-token. Le service public d’authentification est:

https://account.mysoleas.com

La gateway publique est optionnelle dans un parcours purement identite:

https://api.mysoleas.com

Creer une application OAuth2

Avant d’utiliser OAuth2, vous devez creer une application dans le dashboard Mysoleas.

Creez ou utilisez un compte Mysoleas.
Connectez-vous au dashboard:

https://mysoleas.com

Ouvrez la section dediee aux applications OAuth2.
Creez une nouvelle application.
Configurez vos URLs de redirection autorisees.
Copiez le client_id et, si votre type d’application le permet, le client_secret.
Activez les scopes necessaires a votre integration.

Pour une application web ou mobile cote utilisateur, preferez authorization_code avec PKCE. Ne placez jamais un client_secret dans une application frontend.

Trois usages differents

Usage	Domaine	Credential obtenu	Header ensuite utilise
Authentifier vos utilisateurs uniquement	`account.mysoleas.com`	JWT utilisateur et claims	Votre session applicative
Appeler la gateway SoleasPay	Application creee dans SoleasPay puis `api.mysoleas.com`	Token obtenu depuis cette application	`x-sp-auth-token: Bearer <SOLEASEPAY_APP_TOKEN>`
Appel serveur a serveur vers vos propres backends	`account.mysoleas.com`	JWT application	Validation cote backend
Plugin Checkout v4 ou Button v4	`pay.soleaspay.com` ou `btn.soleaspay.com`	Aucun JWT	`apiKey` ou `data-apikey`

Si vous appelez la gateway Mysoleas pour des endpoints SoleasPay, les routes protegees n’attendent pas le JWT utilisateur Identity Cloud. Envoyez le token obtenu depuis l’application creee dans SoleasPay dans x-sp-auth-token.

Choisir le bon flow

Flow	Quand l’utiliser
`authorization_code` avec PKCE	Site web, application mobile ou application tierce qui affiche Se connecter avec Mysoleas
`client_credentials`	Obtention du token d’une application creee dans SoleasPay pour un backend, un worker ou une synchronisation de statut
`refresh_token`	Renouveler une session longue sans redemander les identifiants

Integrer Se connecter avec Mysoleas

Le flow recommande pour une application tierce est authorization_code avec PKCE. Votre bouton doit rediriger l’utilisateur vers l’endpoint d’autorisation Mysoleas avec les parametres OAuth2 de votre application.

https://account.mysoleas.com/oauth/v2/authorize

Parametres usuels:

Parametre	Description
`client_id`	Identifiant de votre application OAuth
`redirect_uri`	URL de retour autorisee dans Mysoleas
`response_type`	`code`
`scope`	Permissions demandees, par exemple `openid profile email payments`
`state`	Valeur aleatoire pour proteger le retour
`code_challenge`	Challenge PKCE
`code_challenge_method`	`S256`

Utiliser Identity Cloud sans gateway

Si votre application veut seulement deleguer l’authentification a Mysoleas, le flux s’arrete apres la validation du JWT et la lecture de userinfo. Votre backend peut alors:

creer ou retrouver l’utilisateur local correspondant au claim sub;
rattacher l’utilisateur a une organisation, un espace de travail ou un tenant de votre application;
ouvrir une session applicative;
appliquer vos propres roles et permissions;
continuer a utiliser vos propres APIs metier sans passer par api.mysoleas.com.

Dans ce mode, Mysoleas Identity Cloud remplace la brique identite de votre application. Il ne vous oblige pas a utiliser la gateway.

Demander un token utilisateur

Apres le retour OAuth2, votre backend echange le code contre un token utilisateur.

curl -X POST "https://account.mysoleas.com/oauth/v2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "code_verifier": "PKCE_CODE_VERIFIER",
    "redirect_uri": "https://yourdomain.com/oauth/callback"
  }'

La reponse suit le format OAuth.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ..."
}

Appeler la gateway SoleasPay

Si votre application consomme les endpoints SoleasPay via la gateway, utilisez les credentials de l’application creee dans SoleasPay.

curl -X POST "https://account.mysoleas.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "sp_client_id": "YOUR_SOLEASEPAY_APP_CLIENT_ID",
    "sp_client_secret": "YOUR_SOLEASEPAY_APP_CLIENT_SECRET"
  }'

Toutes les routes gateway protegees attendent ensuite ce jeton dans x-sp-auth-token.

curl "https://api.mysoleas.com/service/list" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Utiliser les headers de contexte

Ces headers sont utiles pour les integrations multi-pays, les environnements separes et le debogage.

Header	Description
`x-sp-auth-token`	Token Bearer obtenu depuis une application creee dans SoleasPay
`X-Request-Id`	Trace id cree par votre systeme
`X-Idempotency-Key`	Cle d’idempotence externe quand l’endpoint la supporte
`X-SP-Country`	Pays actif, par exemple `CMR`
`X-SP-Environment`	`prod` ou `dev`

Decouverte OAuth

Vous pouvez lire les metadonnees OAuth et OIDC.

curl "https://account.mysoleas.com/.well-known/openid-configuration"

Cette route indique les endpoints officiels de token, introspection, revocation, JWKS et userinfo.

Bonnes pratiques

Ne mettez jamais client_secret dans le navigateur.
Renouvelez le token avant expiration.
Stockez les tokens en memoire ou dans un coffre adapte a votre backend.
Utilisez une cle d’idempotence stable pour toute operation qui peut etre rejouee apres timeout.
Loggez transaction_reference, invoice_reference et X-Request-Id ensemble.

Demarrer

Paiements

Catalogue

Identity Cloud et OAuth2

Creer une application OAuth2

Trois usages differents

Choisir le bon flow

Integrer Se connecter avec Mysoleas

Utiliser Identity Cloud sans gateway

Demander un token utilisateur

Appeler la gateway SoleasPay

Utiliser les headers de contexte

Decouverte OAuth

Bonnes pratiques

​Creer une application OAuth2

​Trois usages differents

​Choisir le bon flow

​Integrer Se connecter avec Mysoleas

​Utiliser Identity Cloud sans gateway

​Demander un token utilisateur

​Appeler la gateway SoleasPay

​Utiliser les headers de contexte

​Decouverte OAuth

​Bonnes pratiques

Creer une application OAuth2

Trois usages differents

Choisir le bon flow

Integrer Se connecter avec Mysoleas

Utiliser Identity Cloud sans gateway

Demander un token utilisateur

Appeler la gateway SoleasPay

Utiliser les headers de contexte

Decouverte OAuth

Bonnes pratiques