ETQ administrateur, je souhaite utiliser un jeton API Particulier sur une démarche à destinations des particuliers

[dzc34]

Actuellement

Pour les démarches à destinations des entreprises, administrations ou associations, grâce à API Entreprise et d'un numéro SIRET demandé à l'utilisateur, les informations sur la personne morale (raison sociale, adresse du siège, etc.) sont automatiquement renseignées. En fonction du jeton API Entreprise utilisé dans la démarche, il est aussi possible de récupérer des informations plus élaborées.

Pour les démarches à destinations des particuliers, la connexion via France-Connect permet de récupérer le nom, prénom et civilité de l'utilisateur. Il n'y a actuellement pas de moyen de récupérer automatiquement des informations plus élaborées (revenu fiscal de référence, quotient familial, statut d'étudiant ou de demandeur d'emploi).

Pour l'instance DS de l'ADULLACT, à destination des collectivités, nous avons identifiés des démarches (inscription à la cantine, à la piscine, ...), où des informations plus élaborées sont nécessaires (revenu fiscal de référence ou quotient familial, par exemple). Actuellement, pour ces démarches là, il est nécessaire de demander ces informations à l'utilisateur et aussi les justificatifs en pièces jointes.

Comportement attendu

À l'instar de ce qui existe déjà pour l'API Entreprise, nous souhaiterions ajouter le support de l'API Particulier lors de la création d'une démarche à destinations des particuliers.

Reprenons les exemples précédents (inscription à la cantine, à la piscine, ...), où des informations plus élaborées (revenu fiscal de référence ou quotient familial) sont nécessaires au traitement des dossiers ; Au lieu de demander l'information à l'utilisateur et aussi un justificatif en pièce jointe, le support d''API Particulier permet de récupérer ces informations directement à partir d'une ou plusieurs informations préalables (numéro d'allocataire pour la CAF, ...).

Contribution (à venir) pour API Particulier

• L'ADULLACT est intéressé pour proposer cette évolution sur son instance DS.
• Notre souhait est d'intégrer cette fonctionnalité sous forme
  de contribution au code source betagouv/demarches-simplifiees.fr.
• Nous avons mandaté le prestataire @synbioz pour développer cette fonctionnalité dans l'optique d'une contribution.
• Si c'est nécessaire, @akarzim, @Bounga et @jobygoude de @synbioz pourront interagir avec l'équipe betagouv sur ce ticket et sur les PRs (répondre aux commentaires, pousser des correctifs, ...).

NOTE :
Les copies d'écrans utilisées dans ce ticket sont des maquettes permettant de se projeter dans le parcours utilisateur.

---

Analyse fonctionnelle et technique

1. API Particulier
2. Relation entre DS, le jeton API Particulier, les données, une démarche et la collectivité
3. Pré-requis pour accéder aux données API Particulier
4. Sauvegarde en base des données récupérées

1 - API Particulier

API Particulier permet à une collectivité d'accéder à diverses informations relatives à ses citoyens.

Elles proviennent de quatre sources différences :

• La DGFIP (Direction Générale des Finances Publiques)
• La CAF (Caisse d'allocation Familiale)
• Pôle Emploi
• le statut Étudiant

Chacune de ces sources donne accès à bon nombre d'informations.

• Exemple côté CAF : le quotient familial.
• Exemple côté DGFIP : avis d'imposition et toutes les informations associées (revenu fiscal de référence ou le nombre de parts).

La documentation d'API particulier présente des exemples de réponses.

Lors de la demande de jeton pour API Particulier, la collectivité sélectionne les informations pour lesquelles elle demande accès. Dit autrement, c'est le jeton qui définit à quelles données la collectivité a accès.

2 - Relation entre DS, le jeton API Particulier, les données, une démarche et la collectivité

• API Particulier est une API soumise à habilitation.
• Une collectivité doit demander son jeton pour en profiter.
• Chaque jeton est dédié à une démarche précise.
• L'administrateur doit ainsi saisir son jeton au niveau de la démarche.

3 - Pré-requis pour accéder aux données API Particulier

Le citoyen doit fournir une ou plusieurs informations préalables.

Elles varient selon la source de données :

• DGFIP :
  • Numéro fiscal
  • Référence de l'avis fiscal
• CAF :
  • Numéro d'allocataire
  • Code postal
• Pôle Emploi
  • Identifiant Pôle Emploi
• Statut Étudiant :
  • Identifiant unique de l'étudiant (INE)

Selon ce qui a été demandé à la création du jeton API Particulier, ces pré-requis peuvent se cumuler.

3.1 - Expérience Utilisateur (UX) pour le citoyen

Ces pré-requis ont une conséquence sur le parcours utilisateur :
ces informations doivent être demandées au citoyen dès le début de la démarche.

L'idée serait de suivre le même modèle que les démarches s'adressant aux organismes, démarches qui demandent (avant même d'accéder au formulaire) de saisir un numéro de SIRET. En l'espèce, une démarche utilisant API Particulier doit présenter au citoyen un écran demandant de saisir les pré-requis. Cela se fera dès le premier écran, lors de l'identification, juste avant le formulaire proprement dit de la démarche.

Un écran intermédiaire récapitulera les données récupérées au travers de l'API Particulier.

4 - Sauvegarde en base des données récupérées

Les informations récupérées au travers d'API Particulier seront sauvegardées dans la base des données.

NOTE :

• Il n'est pas possible de savoir pour un jeton donné à quelles sources de données il a accès.
• Nous devons donc demander à l'administrateur à quelles informations il a demandé à avoir accès.

4.1 - Expérience Utilisateur (UX) pour l'administrateur

Lors de la création de la démarche, l'administrateur devra donc saisir :

• son jeton API Particulier,
• cocher les cases correspondantes aux sources de données qu'il a choisies.

NOTE :
Les écrans ci-dessous sont des maquettes permettant de se projeter dans le parcours utilisateur, nullement les rendus finaux.

4.2 - Conformité au RGPD

Le RGPD demande à ce que la quantité de données demandée soit minimale
(cf Chapitre II, Article 5 : Principes relatifs au traitement des données à caractère personnel).

• Pour chacune des sources de données d'API Particulier, nous listerons précisément les données à disposition.
• Ainsi DS demandera à l'administrateur une liste fine et précise des données à stocker en base.

4.3 - Considérations techniques

Procédures

La table procedures se verra augmentée de deux champs supplémentaires :

• api_particulier_token (string)
• api_particulier_sources (jsonb)

Dans le champ api_particulier_sources seront stockées les sources sélectionnées, ainsi que la liste précise des informations à persister pour chacune d'entre-elles.

Dossiers

Le fonctionnement sera très similaire à ce qui se fait avec l'API Entreprise.

À la sauvegarde de l'étape d'identification d'un dossier, conditionné par la saisie des informations requises par l'API Particulier, un appel au service APIParticulierService sera fait. Cela déclenchera la création d'une instance d'une nouvelle classe nommée Particulier et des requêtes asynchrones seront effectuées sur l'API Particulier pour y stocker les données concernant cet usager. Cette instance de la classe Particulier sera rattachée au dossier et à l'usager.

Remarques et questions

• Nous sommes preneurs de vos retours et commentaires sur cette nouvelle fonctionnalité.
• Vous préférez 4 PRs ou une seule PR consolidée ? (voir ci-dessous le message du prestataire)

Nous avons actuellement découpé cela en 4 PRs :

• 1/4 : mise en place de la lib pour consommer l’API Particulier
• 2/4 : Créer une procédure (côté admin)
• 3/4 : Gestion fine des sources de données (côté admin)
• 4/4 : Créer un dossier (côté usager)

Vous préférez 4 PRs ou une seule PR consolidée ?>
Nous vous communiquerons aussi quelques PRs permettant de corriger des effets de bords qui existaient sur les tests.

Ci-dessous, le résumé de @mfaure de l'échange avec @LeSim :

• importance de s'inspirer de ce qui a été fait sur API Entreprise.
• Pour les appels réseaux à l'API en tant que telle, utiliser des appels asynchrones et de ne pas oublier les retry. Dans la même veine, bien respecter le "rate limit" pour éviter d'être black-listé par api.gouv.fr. C'est d'autant plus vrai que le nombre d'appels réseau augmente avec le nombre de dossiers.
• évoqué la question du chiffrement des jetons (1 jeton = 1 mot de passe, donc ne pas le stocker en clair). Je ne sais pas ce qui a été fait côté API Entreprise sur ce point.
• évoqué la question du test de validité d'un jeton, afin de vérifier que le texte saisi par l'administrateur est bien un jeton et pas la chaîne "test test", et aussi borner d'éventuelles erreurs de copier/coller. Je ne sais pas si cette question a été adressée côté API Entreprise.

---

voir : PR #6245 / @adullact

---

trackingAdullactContrib

[dzc34]

Bonjour,

Question posée par @jobygoude de @synbioz (prestataire de l'ADULLACT pour API Particulier) :

La gestion du service asynchrone delayed_job se réalise via un process system et nous aimerions savoir si une configuration (non versionnée) existe pour ce service ou si cela tourne sur un seul worker (par défaut) ?

Auriez-vous des précisions à nous apporter sur ce point ? (en privé par mail ou en public ici)

---

Détails complémentaires de la question :

Dans l'application, les tâches asynchrones sont actuellement gérées par le service delayed_job (https://github.com/collectiveidea/delayed_job) avec le backend active_record (https://github.com/collectiveidea/delayed_job/wiki/Backends) .

D’après la codebase il semblerait que l'application soit déployée via Capistrano.
La configuration de ce déploiement se trouve dans le fichier config/deploy.rb.

La gestion du service asynchrone se réalise via un process system et nous aimerions savoir si une configuration (non versionné existe pour ce service).

Effectivement le code responsable du restart de ce service est:

  desc "Restart delayed_job"
  task :restart_delayed_job do
    worker_file_path = File.join(deploy_to, 'shared', SHARED_WORKER_FILE_NAME)

    command %{
        echo "-----> Restarting delayed_job service"
        #{echo_cmd %[test -f #{worker_file_path} && echo 'it is a worker marchine, restarting delayed_job']}
        #{echo_cmd %[test -f #{worker_file_path} && sudo systemctl restart delayed_job]}
        #{echo_cmd %[test -f #{worker_file_path} || echo "it is not a worker marchine, #{worker_file_path} is absent"]}
    }
  end
end

S'il n'y a pas de configuration particulière, cela signifie que le service est lancé avec un seul worker.
Autrement dit un seul traitement simultané.

Dans notre cas comme nous utilisons des queues différentes pour l'api entreprise et particulier, il serait bon de configurer une priorité et un nombre worker spécifique pour chaque queue.

Cela pour améliorer les performances et gérer la concurrence des appels à l'API (pour le rate limit)

[LeSim]

Merci pour l'issue superbement rédigée. C'est notre nouveau standard pour les relations avec les forks :) .

Questions à API Particulier

• Y'a-t-il un moyen de vérifier le token et ces scopes ? J'ai bien vu /introspect qui permet de faire un premier niveau de vérification. Pour voir les droits plus finement (quotient familial, ...) et éviter d'empiler des jobs en erreurs, doit on faire un appel de vérification à tous les endpoints avec des ids spéciaux ?

introspect va te donner toutes les infos sur un jeton, tu auras la validité et les scopes associés (donc ça descend au niveau QF, allocataires etc)

Doit-on obliger un usager à passer par vos services pour obtenir vos informations (par exemple le quotient familial) ou recommandez-vous d'ajouter une méthode alternative pour renseigner ces données (par ex: upload de document) ?

nous recommandons de toujours laisser l'alternative papier en plus de l'API, donc oui il vaut mieux avoir une méthode alternative d'upload de justificatif

Pouvons-nous afficher les données aux usagers ou uniquement aux agents ? J'ai en tête le cas classique ou un vil pirate voudrait se servir de ds pour obtenir des informations sur un usager à partir de son numéro fiscal et de son avis de référence

pour l'affichage c'est comme vous le souhaitez, il sera toujours de la responsabilité de la démarche de vérifier que les bonnes personnes font les bonnes demandes. Si la démarche n'est pas authentifiée, autant ne pas afficher la valeur des données en effet

Évolution plus long terme de l'interface de DS

Nous souhaitons faire sauter (un jour) la première page d'authentification par personne physique ou moral pour les remplacer par des champs dans le formulaire. En effet, il y a trop de cas ou cette distinction ne fonctionne pas.

Conséquences

Je vous propose de réaliser un nouveau type de champ : par exemple coefficient familial. Il aurait pour entrées, soit les identifiants nécessaires pour l'api, soit une pièce à joindre. A défaut d'avoir une validation immédiate des identifiants (car job asynchrone) ça serait chouette si on pouvait avoir une vérification du format. On ne présenterait pas les résultats des appels aux usagers mais juste la nature des éléments récupérés.
De cette manière, on

• ne rajoute pas un champ à la page d'identification qui va disparaître
• permet aux usagers d'utiliser une méthode alternative pour transmettre leurs documents
• ne fuite pas de données.

Réalisation et découpage

D'habitude on essaye de découper nos pr pour apporter de la valeur progressivement aux utilisateurs. Ici j'ai l'impression que vous désirez apporter toutes les données d'api particulier d'un coup :).

Je vous proposerai bien plutôt un découpage en ciblant d'abord une donnée, par exemple le coef familial :
(le tout sous feature flag)

• pr pour ajouter la partie admin d'ajout du token et sa vérification.
• pr pour ajouter le type de champs correspondant (et ses exports ?)
• pr pour le traitement asynchrose

c'est à la louche, j'espère que vous voyez l'idée. Une fois que vous avez fait tout ça ... déjà bravo, et ensuite on dégage le feature flag et on attaque une autre source de donnée.

Vous en pensez quoi ?

cc @dzc34 @tchak @kemenaran @krichtof

[LeSim]

voici les parties intéressantes du fichier service systemd.

ExecStart=/bin/sh -c "/home/ds/.rbenv/shims/ruby /home/ds/current/bin/delayed_job --pool=active_storage_analysis:20 --pool=mailers:8 --pool=exports:8 --pool=api_entreprise:2 --pool=cron:4 --pool=webhooks_v1:2 --pool=active_storage_purge:1 --pool=default:4 start"
ExecStop=/bin/sh -c "/home/ds/.rbenv/shims/ruby /home/ds/current/bin/delayed_job --pool=active_storage_analysis:20 --pool=mailers:8 --pool=exports:8 --pool=api_entreprise:2 --pool=cron:4 --pool=webhooks_v1:2 --pool=active_storage_purge:1 --pool=default:4 stop"

Faire une queue dédiée est une super idée. Pour ce qui est du rate limiting, on fait ça pour l'instant en utilisant un (touss touss) sleep qu'on ajuste pour rester dans les limites imposées : https://github.com/betagouv/demarches-simplifiees.fr/blob/7edce745eb2a07e9e7343fa121e15df8653d5dd5/app/lib/api_entreprise/api.rb#L65-L71

Pourriez-vous utiliser le mm mécanisme ? Et si vous avez une meilleure idée on prend :) .

PS : on utilise pour l'instant mina pour déployer.

[mfaure]

Excellent ! Merci beaucoup @LeSim pour toutes ces informations ! On a une belle matière. Je plussoie le découpage des PR par périmètre fonctionnel restreint :)

PS: on est une autre instance de DS (surtout pas un fork) et la contribution fait sens pour nous :)

[dzc34]

Bonjour,

@LeSim, une revue fonctionnelle est en cours chez nous.
Une PR (en draft, éventuellement) sera faite prochainement.