Web service /ws-jwt

Depuis la version 1.34, il existe une nouvelle route /ws-jwt sécurisée par JWT. Grâce au jwt, l'utilisateur signataire est authentifié, ce qui permet de signer directement le document que l'on upload.

Pour que cela fonctionne, il faut configurer l'adresse issuer du fournissuer de jeton (à l'université Rouen c'est CAS qui fourni les jetons) ici : Configuration#security

Lorsque le l'appel des web service de la route /ws-jwt, il faut transmettre le jwt soit via le header (bearer <token>), soit via un cookie nommé "jwt".

Sécurité des web services /ws

L'accès aux web services est filtré par IP. Pour autoriser l'accès il faut modifier la configuration en ajoutant l'IP de la machine concernée au niveau du paramètre ws-access-authorize-ips ici :

Configuration#security.1

Sécurisation par tokens

Depuis la version 1.29.x il est possible d'attribuer des tokens par workflows ou des tokens "wildcard" (donne accès à toutes les demandes). Mais si l'on utilise le système de tokens, il faut toujours autoriser L'IP du serveur distance dans ws-access-authorize-ips

Au niveau de l'interface admin il suffit d'ajouter des tokens dans "Token API": 

On donne un nom au token est on selectionne le/les circuit(s) concerné(s)

Ici on a deux type de token : "Tous les workflows" et un pour un circuit en particulier.

Lorsque d'un circuit est protégé par un token, l'IP ne suffit plus pour acceder aux demandes qu'il contient.

Il faut alors ajouter l'attribut X-API-Key contenant la clé, dans le header de la requête du client.

Voici un exemple de récupération d'une demande via curl:

curl --location --request GET 'http://dsi-7.univ-rouen.fr/ws/signrequests/23152' \
--header 'X-API-Key: ede824ef-7eea-4949-b9d3-427aa1b38baf'

Si vous utilisez une clé "wildcard", vous pourrez acceder à toutes les demandes quelque soit le circuit.

Tester les web services

Curl

Les web services d'esup-signature étant au format REST, il est possible de les tester à l'aide de commandes curl. Des exemples sont proposés dans cette documentation ainsi de dans la documentation swagger. De plus, il est possible de tester les web services directement depuis l'interface swagger. (Dans esup-signature Admin → APIs Doc)

Swagger

Il est possible de tester les web services directement depuis votre interface swagger https://<adresse esup signature>/swagger-ui.html . Pour cela il faut être admin et il faut modifier la valeur  supported-submit-methods dans application.yml

supported-submit-methods: ["get", "put", "post"]

Postman

Postman est très pratique pour tester l'envoi de fichier dans un circuit (multiples fichiers acceptés). Ex :

Fonctionnement général

La première étape pour utiliser les web services est de créer un circuit au niveau de l'administration.

En général, c'est à l'appel du web service que l'on va configurer les signataires, il faudra donc créer autant d'étapes que l'on souhaite en laissant la liste des participants vide (sauf dans le cas ou une des étapes possède un signataire fixe).

Voici comment est configurée ce type d'étape :

Dans l'onglet paramètres du circuit, vous n'avez pas besoin de configurer d'autorisation (le circuit ne sera pas visible sur la page d'accueil). Sur cette page, vous retrouvez l'id qu'il faudra utiliser au lancement du web service (ici 108) :

Une fois l'appel web service effectué, celui-ci vous retourne les identifiants des demandes (un par document envoyer) séparés par des virgules.

Ces identifiants doivent être conservés par l'application qui utilise le web service afin de permettre un suivi de l'avancement par celle-ci.

Pour récupérer l'état d'avancement de la demande de siganture du coté de l'application utilisatrice, il y a deux possibilité :

1. L'application métier, qui a poussé le document, vient régulièrement controler son statut en utilisant le web service /ws/signrequests/{id} avec l'id de la demande concernée (le retour peut etre pending, completed, refused, deleted ou  fully_deleted)
2. On peut configurer le circuit pour qu'il appelle un web service fourni par l'application métier. Dans ce cas il faut ajouter une destination au niveau des paramètres du circuit en y mettent l'url du web service de l'application metier. À chaque étape, esup-signature enverra un simple GET contenant les paramètres suivants, à l'adresse configurée :
   ?signRequestId=<id>&status=<statut>

Enfin l'application métier pourra supprimer le document en faisant une requete DELETE sur l'adresse /ws/signrequests/{id}. Les éléments de vérification de la signature sont conservés dans esup-signature.

Le paramètre stepsJsonString

Depuis la version 1.28 vous pouvez passer une liste de "WorkflowStepDto" (https://github.com/EsupPortail/esup-signature/blob/master/src/main/java/org/esupportail/esupsignature/dto/WorkflowStepDto.java), dans tous les web services de création, pour configurer vos étapes.

Cela remplace les paramètres recipientEmails, signTypes, allSignToCompletes, etc., mais la rétrocompatibilité est maintenue.

Le JSON à transmettre doit représenter le même nombre d'étapes que celle présente dans le circuit configuré dans l'interface admin. La numérotation des steps (stepNumber) est obligatoire est démarre du chiffre 1.

Voici le format d'un step, compatible à partir la version 1.35.x

[
{
  "stepNumber": 1, 														# la numérotation des steps (stepNumber) est obligatoire est démarre du chiffre 1
  "description": "string",
  "recipientsCCEmails": [
    "string"
  ],
  "recipients": [
    {
      "email": "string",
      "phone": "string",
      "name": "string",
      "firstName": "string",
      "forceSms": boolean
    }
  ],
  "signResquestParam" : [
	{
       "xPos": int,														# coordonné x de la signature
       "yPos": int,													    # coordonné y de la signature
       "signPageNumber": int											# numéro de page de la signature (la première page est 1)
   	   "pdSignatureFieldName": "string", 								# nom du champ de signature (surcharge xPos, yPos, signPageNumber si le champ est présent dans le document)
    }
  ],
  "minSignLevel": "string",												# choix possibles : simple, advanced, qualified
  "maxSignLevel": "string",												# choix possibles : simple, advanced, qualified
  "signType": "string",													# choix possibles : hiddenVisa, visa, signature
  "repeatable": boolean,												# rend l'étape 'infinie'
  "repeatableSignType": "string",										# défini le type de signature de l'étape infinie
  "allSignToComplete": boolean,											# la signature de tous les participants est obligatoire
  "multiSign": boolean,													# indique s'il on peut déposer plusieurs image de signature à cette étape
  "forceAllSign": boolean,												# tous les documents de la demandes doivent être signés pour passer au statut "terminer" (à mettre seulement à l'étape 1)
  "comment": "string",													# ajoute un commentaire à la demande (à mettre seulement à l'étape 1)
  "attachmentRequire": boolean,											# interdire la signature s'il n'y a pas de pièce jointe
  "attachmentAlert": boolean 	                            			# alerter avant signature s'il n'y a pas de pièce jointe
}
]

Voici un exemple qui génère le cicuit suivant : 

• Étape 1 : visa caché avec obligation d'ajouter une piece jointe
• Étape 2 : visa visuel obligatoire des deux participants avec une alerte en cas de maque d'une piece jointe
• Étape 3 : signature d'un niveau minimun "avancée" pour un externet avec transmission des nom, prénom et numéro de mobile. La signature se fera dans le champ signature nommé 'signature2'

[
  {
    "stepNumber": 1,
    "description": "desc signature 1",
    "comment": "Merci de vérifier le document",
    "attachmentRequire": true,
    "recipients": [
      {
        "email": "user.interne@univ-ville.fr"
      }
    ],
    "signType": "hiddenVisa"
  },
  {
    "stepNumber": 2,
    "description": "desc signature 2",
    "attachmentAlert": true,
    "recipients": [
      {
        "email": "user.interne2@univ-ville.fr"
      },
      {
        "email": "user.interne3@univ-ville.fr"
      }
    ],
    "minSignLevel": "simple",
    "maxSignLevel": "simple",
    "signType": "visa",
    "allSignToComplete": true
  },
    {
    "stepNumber": 3,
    "description": "desc signature 3",
    "recipients": [
      {
        "email": "test.externe@yopmail.fr",
        "name" : "Test",
        "firstName" : "Test",
        "phone" : "+33123456789"
      }
    ],
     "signResquestParam" : [{
      "pdSignatureFieldName": "signature2"
      }
    ], 
    "minSignLevel": "advanced",
    "maxSignLevel": "qualified",
    "signType": "signature",
    "allSignToComplete": false
  }
]

Exemples

Démarrer un formulaire

Accès : https://<votre adresse>/ws/forms/{id}/new

Description : Ce web service va créer une nouvelle instance du formulaire désigné pas le paramètre "id" de l'url d'accès.

Attributs : 

Exemple de commande curl :

curl --location --request POST 'http://dsi-7.univ-rouen.fr/ws/signrequests/new' \
--form 'multipartFiles=@"/home/lemaida3/Documents/sample.pdf"' \
--form 'createByEppn="test@univ-ville.fr"' \
--form 'stepsJsonString="[{\"signType\":\"pdfImageStamp\", \"recipients\": [{\"email\": \"david.lemaignent@univ-rouen.fr\"}, {\"email\": \"demo.esup@inv.univ-rouen.fr\"}]},
{\"recipients\": [{\"email\": \"david.lemaignent@univ-rouen.fr\"}, {\"email\": \"demo.esup@inv.univ-rouen.fr\"}]}]"'

Envoyer un document dans un circuit existant

Accès : https://<votre adresse>/ws/workflows/{id}/new

Description : Ce web service va déposer d'un document dans une nouvelle instance d'un circuit

Attributs : 

Exemple de commande curl :

curl --location --request POST 'https://esup-signature.univ-rouen.fr/ws/workflows/999999/new' \
--form 'createByEppn="test@univ-rouen.fr"' \
--form 'title="TITRE"' \
--form 'multipartFiles=@"/home/lemaida3/Documents/esup-signature/sample.pdf"' \
--form 'recipientsJsonString="[{\"signType\":\"pdfImageStamp\", \"recipients\": [{\"email\": \"test.test@univ-ville.fr\"}, {\"email\": \"test2.test2@univ-ville.fr\"}]},
{\"signType\":\"certSign\", \"recipients\": [{\"email\": \"test.test@univ-ville.fr\"}, {\"email\": \"test2.test2@univ-ville.fr\"}]}]";type=application/json'