Foire aux questions à l’attention des développeurs DocuSign – Administration générale et authentification

Foire aux questions à l’attention des développeurs DocuSign – Administration générale et authentification

Vous trouverez ci-dessous des réponses à quelques-unes des questions les plus fréquentes concernant l’administration générale et l’authentification. Si vous voulez consultez des foires aux questions destinées aux développeurs sur d’autres rubriques, reportez-vous à Foire aux questions à l’attention des développeurs DocuSign – Table des matières ou utilisez les liens se trouvant sous Références à la fin de cette page.


Administration générale


Authentification


Administration générale

Pourquoi est-ce que j’obtiens l’erreur « L’utilisateur ne dispose pas des autorisations requises » lorsque j’essaie de récupérer des données de formulaire par le biais de l’API REST eSignature ?

Cette erreur signifie que le paramètre « Allow the sender to download form data » (Autoriser l’expéditeur à télécharger les données de formulaire) est désactivé. Pour le configurer dans l’application web eSignature, allez à Paramètres > Paramètres de l’Espace Envoyer et activez le paramètre Allow sender to download form data.


Non. Le comportement de la fonctionnalité de divulgation légale peut être modifié uniquement dans l’application web eSignature, via Paramètres > Divulgation légale. Pour plus de détails, reportez-vous à ce guide.


Puis-je transférer des clés d’intégration entre les comptes ?

Oui, même si cela n’est pas nécessaire dans la plupart des cas. Une clé d’intégration est liée à un compte spécifique pour des raisons de gestion, mais cette clé peut être utilisée pour réaliser des appels API sur n’importe quel compte une fois qu’elle a été correctement authentifiée.

Si vous voulez transférer une clé d’intégration d’un compte à un autre, l’Assistance DocuSign peut s’en charger avec l’autorisation des administrateurs du compte en cours et du compte de destination. Si un utilisateur est administrateur des deux comptes, il peut signer pour les deux.

Pour demander un transfert de clé d’intégration, ouvrez une demande auprès de l’Assistance DocuSign et fournissez les informations suivantes :

  • Environnement (démo ou production) :
  • Clé d’intégration :
  • Identifiant du compte source :
  • Adresse e-mail de l’administrateur du compte source :
  • Identifiant du compte de destination :
  • Adresse e-mail de l’administrateur du compte de destination :

Le service d’assistance enverra une enveloppe demandant l’autorisation ; une fois la signature obtenue, la clé sera transférée. Remarque : Les clés ne sont pas « transférées » entre l’environnement de démo et de production ; si vous voulez qu’une clé soit activée dans l’environnement de production, elle devra suivre le processus de mise en ligne.


Comment fournir une plage de dates personnalisée lors de la création de rapports à l’aide de l’API REST ?

Lorsque vous utilisez l’API pour exécuter un rapport, il existe trois paramètres pertinents. Le paramètre DateRangeFilter doit être défini sur date_range_custom afin que la plage de dates puisse être appliquée. Lorsque ce paramètre est correctement défini, les paramètres FromDate etToDate peuvent être utilisés.

 

"dateRangeCustomFromDate": "01/01/2021",

"dateRangeCustomToDate": "01/07/2021",

"dateRangeFilter": "date_range_custom",

 


Authentification

Toutes les intégrations avec les API DocuSign doivent s’authentifier pour faire des appels API.


Quels types d’authentification API sont pris en charge ? Des exemples sont-ils disponibles ?

L’API eSignature REST DocuSign prend en charge les authentifications Octroi du code d’autorisation, Octroi implicite et Octroi du jeton web JSON (JWT) et des exemples de code.


Comment trouver mon identifiant utilisateur pour l’authentification ?

Bien que vous puissiez utiliser l’API pour rechercher l’identifiant utilisateur de n’importe quel membre de votre compte, vous avez besoin d’un identifiant utilisateur pour démarrer avec l’authentification JWT. Pour trouver votre propre ID utilisateur, accédez à Paramètres > Apps et Clés. Pour trouver l’ID utilisateur de tout autre membre du compte, accédez à Paramètres > Utilisateurs > Modifier.


Une documentation détaillée sur le consentement des applications est disponible sur le Developer Center. Le consentement individuel est obtenu en dirigeant l’utilisateur vers un URI d’autorisation. Un administrateur d’organisation peut accorder un consentement général à une application via le module Organisation ; cependant, ce consentement général ne s’applique qu’aux utilisateurs possédant des adresses e-mail sous des domaines revendiqués par l’organisation.


Qu’est-ce qu’un jeton d’actualisation et comment est-il utilisé ?

Les jetons d’actualisation sont utilisés dans le workflow Attribution d’un code d’autorisation pour générer de nouveaux jetons d’autorisation sans nécessiter d’interaction avec l’utilisateur final. Les jetons d’actualisation standard durent 30 jours à compter de l’octroi de l’autorisation initiale. Si le champ d’application étendu a été accordée, de nouveaux jetons d’actualisation peuvent être générés tant que le jeton d’actualisation actuellement détenu a moins de 30 jours. La documentation complète est disponible dans le Centre développeur.


Puis-je utiliser la même clé d’intégration, les secrets clients ou les paires de clés RSA entre l’environnement sandbox pour développeur et les environnements de production ?

Non. Au cours du processus de mise en ligne, une clé d’intégration est transférée du sandbox pour développeur vers l’environnement de production. Bien que le GUID de la clé ne change pas, le sandbox du développeur et les environnements de production sont des instances distinctes, de nouveaux secrets client et paires de clés RSA doivent donc être générés.


Quelles étendues sont prises en charge dans l’API eSignature ?

Pour l’API eSignature REST, les étendues sont signature, extended et impersonation :
  • signature – permet à votre application de créer et d’envoyer des enveloppes et d’obtenir les liens pour démarrer des sessions de signature.
  • extended – sans cette étendue, un jeton d’actualisation durera 30 jours à compter de l’octroi de l’autorisation initiale. Avec cette étendue, de nouveaux jetons d’actualisation peuvent être générés indéfiniment. Cette étendue ne peut être utilisée que dans l’authentification d’octroi de l’autorisation initiale.
  • impersonation (usurpation d’identité) – permet à votre application d’accéder au compte d’un utilisateur et d’agir en son nom même lorsque cet utilisateur n’est pas présent. Cette étendue est uniquement utilisée par l’authentification d’octroi JWT.

Plusieurs étendues peuvent être demandées à la fois, séparées par des espaces dans l’URL d’autorisation.


La durée de vie d’un jeton d’accès OAuth peut-elle être modifiée ?

Non. Les jetons web JSON (JWT) ont une durée de vie fixe d’une heure et les jetons d’accès Octroi du code d’autorisation et Octroi implicite ont une durée de vie fixe de huit heures. Si votre application fait un appel API avec un jeton expiré, elle rencontrera une erreur d’échec d’autorisation et devra demander un nouveau jeton pour continuer.


DocuSign a-t-il des exemples de code OAuth ?

Oui. Vous pouvez trouver des exemples de code OAuth dans notre Centre développeur :


Une documentation détaillée sur le consentement spécifique à l’octroi JWT est disponible sur le Centre développeur.

Le consentement JWT ne peut être octroyé administrativement par l’administrateur système que si votre compte inclut la fonctionnalité Gestion des accès (précédemment connue sous le nom de fonctionnalité « org admin ») et que vous avez revendiqué le domaine de messagerie des adresses e-mail des utilisateurs empruntés.

Le consentement JWT peut aussi être accordé individuellement ; chaque utilisateur dont l’identité sera empruntée devra accorder lui-même l’autorisation.

Pour accorder le consentement individuellement, utilisez le même processus de consentement que l’attribution d’un code d’autorisation à quelques exceptions près :

  • Les étendues doivent inclure la signature et l’emprunt d’identité (et peut-être aussi d’autres étendues, selon l’API que vous utiliserez).
  • N’utilisez pas le code d’autorisation renvoyé pour demander un jeton. Ignorez-le simplement : l’effet secondaire important est que l’utilisateur a donné son consentement à votre clé d’intégration.
  • Le consentement est stocké sur les serveurs DocuSign jusqu’à ce qu’il soit révoqué par un utilisateur. Par conséquent, vous n’avez généralement besoin d’obtenir le consentement de l’utilisateur qu’une seule fois.

Lorsque j’utilise l’authentification JWT, comment puis-je diagnostiquer un invalid_grant ou d’autres erreurs ?

L’erreur invalid_grant est une réponse d’erreur générique qui signifie que quelque chose est incorrect dans l’assertion JWT. Pour de déterminer ce qui ne fonctionne pas, reportez-vous au paramètre error_description dans la réponse. Si error_description n’est pas rapidement disponible dans votre application, nous vous recommandons de configurer la journalisation des erreurs qui capture la réponse d’erreur complète.

Réponses d’erreur d’authentification :

  • consent_required : si vous utilisez le consentement individuel, assurez-vous que le consentement a été accordé pour les étendues souhaitées. L’étendue signature impersonation est le minimum requis pour l’authentification JWT, mais d’autres étendues peuvent être nécessaires pour les fonctionnalités Rooms ou Admin.
  • invalid_subject or user_not_found : quelque chose ne va probablement pas avec la valeur sub (objet) dans l’assertion. Confirmez que la valeur est un GUID identifiant utilisateur valide (et non une adresse e-mail) d’un utilisateur actif dans l’environnement concerné.
  • Issuer_not_found : la clé d’intégration dans le paramètre iss (émetteur) n’est pas disponible dans l’environnement actuel. Cela peut aussi signifier un décalage dans la valeur aud (audience) et l’environnement touché : par exemple, en utilisant une valeur aud de account.docusign.com tout en demandant un jeton à https://account-d.docusign.com/oauth/token.
  • no_valid_keys_or_signatures : cette erreur couvre plusieurs cas :
    • Il y a un problème avec la clé privée utilisée pour signer l’assertion (par exemple, en utilisant une clé de démonstration dans l’environnement de production).
    • Il manque un paramètre exp (expiration) à l’assertion
    • Le paramètre aud (audience) n’est pas valide - confirmez que la valeur d’audience est exactement account.docusign.com ou account-d.docusign.com sans le préfixe https:// ou barre oblique (/).
    • Un paramètre nbf (non valide avant) est défini et cette heure n’a pas encore été atteinte. Le paramètre nbf est facultatif et peut être retiré de l’assertion, mais s’il est présent, il doit être d’une date antérieure.
  • expired_grant : l’assertion a expiré. Le paramètre exp (Expiration) doit être une date future.

Le consentement administratif nécessite un domaine de messagerie revendiqué et s’applique uniquement aux utilisateurs disposant d’une adresse e-mail dans ce domaine. Ainsi, pour accorder le consentement d’administrateur à agir en tant qu’utilisateur@exemple.fr, le domaine exemple.fr doit être revendiqué dans votre organisation et les étendues d’emprunt de signature doivent être accordées sous l’onglet Applications de DocuSign Administration (et non DocuSign eSignature Administration).

Une fois la revendication de domaine confirmée, un délai de quelques minutes peut s’écouler avant qu’elle ne soit reconnue par DocuSign. Si l’erreur persiste après cela, nous vous recommandons de vider le cache de votre navigateur.


Pourquoi est-ce que j’obtiens UserNotFound lorsque je passe un appel UserInfo avec un jeton valide ?

Ceci est dû à un problème connu : API - Pour un utilisateur valide spécifique pour un utilisateur spécifique. Notez que, bien que cet article fasse référence à une réponse UserInfo vide, la réponse UserNotFound / « L’utilisateur n’est pas trouvé dans DocuSign » est due au même comportement sous-jacent et la résolution est la même. Veuillez ouvrir un ticket sur l’assistance DocuSign faisant référence à cet article et fournissant les informations pertinentes.


Comment corriger une erreur lors de l’obtention d’un jeton d’authentification à l’aide du flux JWT ?

Message d’erreur : DocuSign.eSign.Client.ApiException : « Erreur lors d’une demande au serveur, réception d’une erreur de code HTTP non réussi avec le corps de la réponse : »

L’un des trois défauts suivants est souvent accompagné de cette erreur :

  • {Consent_Required}
    • Le consentement a été révoqué
    • Le consentement n’a jamais été fourni
    • L’état de l’utilisateur/du consentement est incorrect, doit être supprimé/réappliqué

Veuillez consulter ce qui suit pour en savoir plus sur comment Obtenir un consentement.

  • {Invalid_Grant}
    • La description de l’erreur révèle souvent la source :
      • L’IAT (heure à laquelle le jeton est émis) est définie plus d’une heure avant la demande
      • La valeur Exp (expiration) est située dans le passé ou avant l’heure IAT
    • La clé RSA est non valide
      • -----DÉBUT PAIRE DE CLÉS RSA----- / Lignes de fin supprimées
      • Le fichier PEM est corrompu
      • La clé RSA n’est plus correctement enregistrée dans DocuSign et doit à nouveau être émise
      • La ligne AUD renvoie vers Démo plutôt que Prod ou inversement.
  • {Internal_Server_Error}
    • Assertion JWT non valide
    • La clé RSA est non valide
    • La valeur du paramètre AUD est non valide – cette valeur doit spécifiquement être account.docusign.com pour Production, account-d.docusign.com pour Démo. Ces valeurs ne peuvent pas contenir http:// ou https:// au début, ou / à la fin.
    • Par exemple :
      • account-d.docusign.com = oui
      • https://account-d.docusign.com = non
      • account-d.docusign.com/ = non
      • ApiClient apiClient = nouvelle ApiClient(« https://demo.docusign.net/restapi ») ;
      • Les appels du client API utilisé doivent renvoyer vers {endpoint}.docusign.net/restapi

Veuillez consulter les informations suivantes sur la mise en œuvre du flux et de l’assertion JWT. Appelez le point de terminaison UserInfo (Informations d’utilisateur) pour déterminer l’URI de base et les informations de compte pour interagir avec le service d’API DocuSign.


Lorsqu’un utilisateur accorde un consentement OAuth individuel ou qu’un administrateur d’organisation accorde un consentement OAuth à l’échelle de l’organisation pour votre application, le délai n’expire jamais. Cependant, le consentement peut être révoqué. Le jeton d’accès renvoyé par DocuSign à partir d’un flux JWT expire au bout d’une heure. Tenter de définir une expiration plus longue dans l’assertion JWT n’aura aucun effet sur la durée de vie du jeton. Si votre application utilise le jeton d’accès pour plusieurs appels, vous devrez indiquer une durée d’expiration et vérifier la durée avant d’effectuer des appels API. Les fonctions CheckToken() dans nos exemples de code l’illustrent.


Les jetons OAuth peuvent-ils être révoqués ?

Les jetons DocuSign OAuth ne peuvent pas être révoqués. Le fait de révoquer le consentement de l’application empêchera la génération de nouveaux jetons mais n’aura aucun effet sur la validité des jetons existants.


Pourquoi mon authentification d’en-tête héritée échoue-t-elle lors de l’activation de l’authentification à deux facteurs ?

Cela est tout à fait normal. L’authentification d’en-tête héritée et l’authentification à deux facteurs ne peuvent être utilisées en même temps. Si l’authentification à deux facteurs est activée, vous pouvez utiliser un flux d’authentification OAuth.


Même si le consentement administratif vous permet d’éviter que chaque personne ait à fournir son consentement, il y a quelques prérequis à respecter si vous voulez emprunter l’identité d’un utilisateur :

  1. Le domaine d’e-mail de l’utilisateur en question doit être revendiqué par votre organisation pour que le consentement administratif puisse s’appliquer. Les sous-domaines sont considérés comme des entités distinctes ; si un utilisateur dispose d’une adresse @mail.example.com, vous devrez revendiquer ce sous-domaine même si vous avez déjà revendiqué le domaine @example.com.
  2. Les champs d’application appropriés doivent être octroyés. L’emprunt d’identité est requis pour l’authentification JWT, la signature couvre l’API REST eSignature standard et d’autres champs d’application correspondent à d’autres fonctions.
  3. Le consentement administratif requiert l’accès à la fonctionnalité Organisation. Si votre forfait de compte ne l’inclut pas, contactez l’équipe de votre compte pour en discuter. Pour connaître la marche à suivre pour revendiquer un domaine, reportez-vous à ce guide.

L’API Rest DocuSign prend-elle en charge l’authentification MASSL ?

Non, DocuSign ne prend pas en charge l’authentification MASSL.

SSL prise en charge par DocuSign


Pourquoi est-ce que j’obtiens l’erreur « l’URI de redirection n’est pas correctement enregistré avec DocuSign » ?

Si vous obtenez cette erreur, cela signifie que l’un des critères suivants n’est pas respecté :

  1. Vous devez définir au minimum un URI de redirection pour mettre en œuvre un scénario d’authentification dans la configuration de votre clé d’intégration.
  2. Dans l’URL de demande, la valeur de redirect_uri doit correspondre exactement à l’une des valeurs définies dans la configuration de la clé d’intégration.
  3. L’URI de redirection doit inclure le chemin d’accès complet vers l’hôte, protocole y compris. Exemple : https://localhost:8080
  4. Les URI nouvellement sauvegardés peuvent nécessiter jusqu’à cinq minutes pour prendre effet.
  5. Les indicateurs de fragments (#) ne sont pas autorisés dans l’URI comme indiqué dans les critères OAuth.

Comment corriger cette erreur avec l’authentification par jeton web JSON ? "api_client.request_jwt_user_token return error could not deserialize key data"

Cette erreur indique qu’un problème s’est produit avec la clé RSA privée utilisée. Vérifiez la configuration pour vous assurer que le fichier PEM n’a pas été modifié. La bonne structure est :

(Données devant être traitées)

----Commencer la génération de la Clé RSA privée----

Données clés

----Fin de la clé RSA privée ----

Norme RFC : https://tools.ietf.org/html/rfc7468

Si vous continuez à recevoir cette erreur après avoir vérifié votre clé privée, vous devrez peut-être générer une nouvelle paire de clés RSA.


Comment obliger les signataires à utiliser l’authentification SMS dans l’API REST eSignature ?

L’authentification du destinataire est définie dans le cadre de l’objet Destinataires lorsque vous définissez les destinataires de votre enveloppe. Voir Comment faire une demande d’authentification SMS pour un destinataire | API REST pour plus de détails.


Pourquoi je vois « Error: USER_LACKS_MEMBERSHIP » lors de l’obtention d’une liste d’enveloppes du compte ?

Si vous avez confirmé que vous êtes authentifié à l’aide de l’ID utilisateur et de l’ID de compte corrects mais que vous recevez toujours cette erreur, vous vous connectez probablement au mauvais serveur d’applications. Par exemple, vous cliquez peut-être sur https://www.docusign.net alors que votre compte est sur le serveur CS. Pour trouver le bon serveur pour votre compte, vous pouvez soit faire un appel UserInfo, soit vous connecter à la console web et accéder à Paramètres > Apps et clés > URL de base du compte.

A screenshot of the Accounts Base URI user interface in DocuSign Settings.

Références