Authentification API Partenaire : Authorization Code

Sommaire

1) Déroulement du flux Authorization Code
Étape 1 : Entrée côté partenaire et redirection vers Inqom
Étape 2 : Récupération du code dans l'URL de retour
Étape 3 : Echange du code contre les jetons
2) Gestion des erreurs
Erreur lors de la redirection
Erreur lors de l'échange du token

1) Déroulement du flux Authorization Code

Le flux Authorization Code est le mode d'authentification recommandé pour toutes les intégrations partenaires.

L'application partenaire s'authentifie avec ses propres identifiants (client_id et client_secret). L'utilisateur, quant à lui, se connecte directement sur Inqom afin de donner son consentement. À aucun moment le partenaire ne manipule les identifiants Inqom de l'utilisateur.

Le processus se déroule en trois étapes.

Étape 1 : Entrée côté partenaire et redirection vers Inqom

Lorsque l'utilisateur accède à votre page de connexion (par exemple https://partenaire-name.fr/login-from-inqom), votre application doit :

Générer un state cryptographiquement aléatoire (anti-CSRF), le stocker en session serveur, et le placer dans la requête.
(Optionnel mais recommandé) Générer un nonce pour l'id_token et le stocker également.
Rediriger l'utilisateur (HTTP 302)vers la page d'authentification d'Inqom :

GET https://auth.inqom.com/identity/connect/authorize
?response_type=code
&client_id=<client_id>
&redirect_uri=<redirect_uri>
&scope=<scope>
&state=<valeur_arbitraire>

Description des paramètres :

Paramètre	Description
`response_type=code`	Indique l'utilisation du flux Authorization Code.
`client_id`	Identifiant de votre application partenaire, fourni par Inqom lors de l'onboarding.
`redirect_uri`	URL de redirection autorisée (whitelistée) pour votre application. Par défaut : `http://localhost:8080/`. Des URL peuvent être ajoutées à la demande.
`scope`	Scopes demandés (cf. article)
`state`	Valeur arbitraire permettant de conserver le contexte de la requête et de se protéger contre les attaques CSRF.

Étape 2 : Récupération du code dans l'URL de retour

Une fois l'utilisateur authentifié (ou immédiatement si une session active est détectée), Inqom redirige le navigateur vers l'URL de redirection configurée, avec un code d'autorisation en paramètre :

<redirect_uri>?code=<authorization_code>&state=<state>

L'application doit extraire la valeur de code depuis la query string de cette URL de redirection.

Contrôles obligatoires côté partenaire avant de poursuivre :

Vérifier que le state reçu correspond exactement à celui stocké en session serveur. Sinon, rejeter la requête (HTTP 400, risque de CSRF).
Vérifier la présence du paramètre code
Vérifier qu'aucun paramètre error n'est présent (cf. gestion d'erreurs plus bas)

Le code est à usage unique et a une durée de vie courte (~60s) : l'échange contre un token doit être fait immédiatement.

Étape 3 : Échange du code contre les jetons

Le partenaire envoie une requête HTTP POST côté serveur (jamais depuis le navigateur) à l'endpoint token d'Inqom pour échanger le code contre des jetons.

Endpoints d'authentification :

Environnement	Endpoint
Production	`https://auth.inqom.com/identity/connect/token`
Staging	`https://auth-staging.inqom.com/identity/connect/token`

Exemple de requête :

POST https://auth.inqom.com/identity/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<code>
&redirect_uri=<redirect_uri>
&client_id=<client_id>
&client_secret=<client_secret>

Description des paramètres :

Paramètre	Description
`grant_type=authorization_code`	Indique l'utilisation du flux Authorization Code.
`code`	Code extrait de l'URL de redirection.
`redirect_uri`	URL de redirection autorisée (whitelistée) pour votre application. Par défaut : `http://localhost:8080/`. Des URL peuvent être ajoutées à la demande.
`client_id`	Identifiant de votre application partenaire, fourni par Inqom.
`client_secret`	Mot de passe de votre application partenaire, fourni par Inqom.

Exemples de réponses :

scope=openid apidata

{
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...",
"expires_in": 31104000, 
"token_type": "Bearer"
}

scope=openid apidata offline_access

{
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...",
"expires_in": 31104000, 
"token_type": "Bearer",
"refresh_token": "5fa4c22601386f6fe5f02a4..." 
}

Vous retrouverez le détail de l'utilisation du refresh token dans cet article.

Remarque :

Le jeton d'accès obtenu porte les droits de l'utilisateur Inqom ayant donné son consentement. Toutes les requêtes effectuées avec ce jeton sont donc soumises aux mêmes autorisations que celles de cet utilisateur.

Gestion des erreurs :

Erreurs lors de la redirection (Étape 2) :

Si l’autorisation échoue côté Inqom, l’utilisateur est redirigé vers le redirect_uri avec un paramètre error au lieu du paramètre code.

https://partenaire-name.fr/callback?error=access_denied&error_description=...&state=<state>

Liste des erreurs possibles :

Erreur	Cause probable	Action recommandée
`access_denied`	L’utilisateur a refusé le consentement	Afficher une page explicative et proposer de relancer le processus
`invalid_request`	Paramètre manquant ou mal formé	Corriger l’implémentation côté partenaire et logger l’erreur
`unauthorized_client`	`client_id` non autorisé pour ce flow	Vérifier la configuration avec Inqom
`invalid_scope`	Scope non autorisé	Ajuster les scopes demandés à l’étape d’autorisation
`server_error`	Erreur interne Inqom	Réessayer plus tard ou contacter le support Inqom

Erreurs lors de l’échange du token (Étape 3) :

En cas d’échec lors de l’appel au endpoint /token, Inqom retourne une réponse JSON contenant un champ error et un code HTTP 400 ou 401.

{
"error": "invalid_grant",
"error_description": "The provided authorization grant is invalid, expired, revoked..."
}