OneSpan Sign version 11.34 : Token API pour l'application client

La version 11.34 de OneSpan Sign a été récemment déployée dans l'environnement de prévisualisation et de sandbox. Dans cette nouvelle version, nous avons continuellement apporté de nouvelles fonctionnalités à l'expérience du nouveau signataire, comme l'aperçu des pièces jointes, la prise en charge de la signature en personne et l'amélioration du navigateur. En outre, les développeurs ont adopté des fonctionnalités intéressantes, comme la possibilité d'intégrer la page de modification de la transaction dans une iFrame et la deuxième méthode d'authentification pour les appels API, que nous décrirons dans ce blog

Vous pouvez trouver les dates de déploiement pour tous nos environnements sur notre page Trust Center.

Token API de l'application client

OneSpan Sign fournit des interfaces API simples et flexibles que votre application intégrée peut utiliser. Auparavant, chaque appel entrant devait fournir une clé API sécurisée pour s'authentifier auprès de l'API. Mais ce n'est plus le cas. Avec la version 11.34, OneSpan Sign propose désormais une méthode d'authentification alternative où vous pouvez enregistrer des paires d'identifiants et de secrets pour vos intégrations tierces. Ces paires peuvent à leur tour être utilisées pour générer un jeton d'API sécurisé mais de courte durée qui authentifie vos demandes d'API

Étape 1 : activer la fonction

Pour vérifier si la fonction a été activée sur votre compte, il vous suffit de vous connecter au portail de l'expéditeur de votre compte, de cliquer sur le menu déroulant "Admin" dans le menu supérieur et de sélectionner "Accès API". Dans la page d'accès à l'API, allez à la section "Client Apps" (voir la capture d'écran ci-dessous)

Remarque: si vous ne trouvez pas la section "Client Apps", contactez notre équipe d'assistance et nous activerons cette fonction pour votre compte

Étape 2 : S'inscrire à l'application client

L'étape suivante consiste à enregistrer une paire identifiant-client et secret pour votre système client. Si vous avez plusieurs applications intégrées, vous pouvez créer une paire individuelle pour chaque intégration, de sorte que le trafic API de chaque application cliente puisse être enregistré et surveillé séparément.

Maintenant, cliquez sur le bouton "Ajouter", et une barre latérale "Créer une application client" s'affichera.

L'ID et le secret du client sont utilisés pour récupérer le jeton d'API temporaire. Le secret n'apparaîtra qu'une seule fois, il est donc important de le sauvegarder dans un endroit sûr.

Étape 3 : Demande d'un jeton d'accès

Le couple identifiant-client et secret peut être utilisé ultérieurement pour demander un jeton d'accès de courte durée, en utilisant l'appel API ci-dessous :

Demande HTTP

POST /apitoken/clientApp/accessToken

En-têtes HTTP

Accept : application/json Content-Type : application/json

Charge utile de la demande

{ "clientId" : "your_client_id", "secret" : "your_client_secret", "type" : "OWNER" }

Les options disponibles pour le champ "type" sont "PROPRIÉTAIRE" et "EXPÉDITEUR". Dans ce dernier cas, le champ "email" est obligatoire :

{ "clientId" : " your_client_id ", "secret" : " your_client_secret ", "type" : "SENDER", "email" : "sender_email" }

En spécifiant le type et l'email, il détermine qui est l'utilisateur autorisé lorsque le jeton d'accès temporaire est utilisé ultérieurement pour effectuer des requêtes API.

Exemple de réponse

{ "accessToken" : "17270a2f8960e84937478a60013404", "expiresAt" : 1591029428203 }

Le jeton d'accès sera renvoyé par la réponse à l'API, ainsi que l'heure d'expiration représentée par un horodatage Linux

Étape 4 : Utilisez un jeton d'accès pour authentifier vos appels d'API

Avant que le jeton d'accès n'expire, vous pouvez toujours l'utiliser pour authentifier vos appels d'API. Comme pour l'utilisation de la clé API, vous devez définir l'en-tête HTTP "Authorization" comme "Bearer" suivi du jeton d'accès généré à l'étape 3. L'API de récupération des paquets est un bon exemple :

Demande HTTP

GET /api/packages/{packageId}

En-têtes HTTP

Accept : application/json ; esl-api-version=11.21 Authorization : Bearer 17270a2f8960e84937478a60013404

Support du SDK

Pour les intégrateurs SDK, les étapes 3 et 4 ci-dessus sont invoquées en interne, ce qui vous offre la même expérience transparente qu'auparavant lors de l'authentification avec la clé API. Une nouvelle signature de constructeur pour "EslClient" a été introduite et vous permet de spécifier les paramètres liés au jeton API

public EslClient(ApiTokenConfig apiTokenConfig, String baseURL, boolean allowAllSSLCertificates, ProxyConfiguration proxyConfiguration, boolean useSystemProperties, Map headers)

Essayons de l'utiliser dans la pratique :

String BASE_API_URL = "https://sandbox.esignlive.com" ; String CLIENT_APP_ID = "your_client_id" ; String CLIENT_APP_SECRET = "your_client_secret" ; EslClient eslClient = new EslClient(ApiTokenConfig .newBuilder() .clientAppId(CLIENT_APP_ID) .clientAppSecret(CLIENT_APP_SECRET) .baseUrl(BASE_API_URL) .tokenType(TokenType.OWNER) //.senderEmail("sender_email") //no need to specify sender email if type is OWNER .build() , BASE_API_URL + "/api", false, null, false, new HashMap()) ; String applicationVersion = eslClient.getSystemService().getApplicationVersion() ; System.out.println(applicationVersion) ;

Vous pouvez construire un objet EslClient et invoquer les fonctions du SDK aussi facilement que cela. Le SDK vous aidera à gérer le cycle de vie du jeton d'accès généré où le SDK récupérera un jeton d'API stocké dans l'objet EslClient. Ainsi, pour le même objet EslClient, le client interne Rest ne demandera pas un nouveau jeton API à moins que le jeton n'expire dans une minute.

Note :

• Assurez-vous que la version de votre SDK est égale ou supérieure à 11.34.
• Si vous migrez d'une clé API vers un jeton API, vous êtes peut-être plus familier avec l'autre signature de constructeur : "public EslClient(String apiKey, String baseURL)". Si vous ne savez pas quelles valeurs transmettre lors de la conversion vers le nouveau constructeur, reportez-vous à l'exemple ci-dessus où j'ai défini tous les paramètres d'entrée comme valeurs par défaut
• L'URL de base requise par le constructeur de "ApiTokenConfig" doit exclure "/api" dans le chemin
• Si un Token API est créé pour le propriétaire du compte, il n'est pas nécessaire de spécifier l'email de l'expéditeur.

Voilà. Après avoir lu le blog d'aujourd'hui, vous avez une meilleure idée de la façon d'enregistrer l'application client et de générer le jeton API pour authentifier vos demandes API.

Si vous avez des questions concernant ce blog ou toute autre chose concernant l'intégration de OneSpan Sign dans votre application, visitez les Forums communautairesdes développeurs . Vos commentaires sont importants pour nous!