# DossierFacile Connect ## En quoi cela consiste ? DossierFacile Connect est la solution qui utilise la connexion SSO (single-sign-on) de DossierFacile pour permettre à un candidat de partager les informations de son dossier de location. Un bouton de connexion est intégré à votre site, il permet à l’utilisateur de se connecter à DossierFacile. Une fois connecté (ou inscrit), il lui est demandé de consentir à partager ses informations, la liaison entre son compte DossierFacile et votre plateforme est ensuite établie. La connexion ou l'inscription peut se faire de 2 manières : * via login email et mot de passe * via FranceConnect Si l'utilisateur n'a pas encore de compte DossierFacile, il aura la possibilité de le créer et le compléter une fois la connexion et le partage établi. #### Intégration technique * Etablissement d'une authentification OAuth2.0 * Appels API * Réception Webhook - optionnel ## Le parcours des usagers L'interface suivante : met en oeuvre une démonstration technique du parcours usager dans le cadre d'une intégration DFC avec un partenaire. Exemple d'implémentation de DFC : {% embed url="" %} ## Le bouton DossierFacile Connect Téléchargez le bouton à implémenter {% file src="" %} ![Aperçu du bouton DossierFacile Connect](https://1211770655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_uTTIpEw6lepwml8vT%2Fuploads%2Fgit-blob-ac0a71ada23b9566700f4191908eb0ee40bab498%2FXL.png?alt=media) Ajoutez le court texte de présentation suivant. {% hint style="info" %} DossierFacile est le dossier de location numérique de l'Etat. Entièrement gratuit, conforme et sécurisé, il protège les locataires et rassure les propriétaires. {% endhint %} ## Faire une demande d'accès Pour récupérer des identifiants de préproduction, écrivez à un membre de l'équipe pour être mis en relation avec un développeur. [echangez-avec-un-membre-de-lequipe](https://partenaire.dossierfacile.logement.gouv.fr/echangez-avec-un-membre-de-lequipe "mention") Pensez à bien indiquer dans le mail vos URLs de redirection et vos URLs de webhook si vous voulez utiliser les webhooks (voir[#5-optionnel-2-webhook](#5-optionnel-2-webhook "mention")). ## Testez DossierFacile Connect avec Postman DossierFacile Connect vous permettant de récupérer les informations du dossier de location d’un de vos utilisateurs directement sur votre plateforme. Il permet également de mettre en place un webhook vous indiquant quand le statut d’un dossier change. Ce tutoriel décrit les différentes étapes de l’utilisation avec Postman. L’objectif de base est de pouvoir appeler le *endpoint* `https://api-preprod.dossierfacile.fr/dfc/tenant/profile` qui contient les informations du dossier de location de l’utilisateur qui consent à partager ses informations. {% hint style="info" %} Pour vos tests d'intégration, nous vous invitons à contacter notre équipe qui vous fournira des identifiants nominatifs et adaptés à vos environnements sur notre plateforme de préproduction.\ Notamment les elements pour mettre en place les webhook et accéder aux API de DFC. {% endhint %} **Collections Postman** {% file src="" %} {% file src="" %} ### **1 - Création d’une requête dans Postman** Créez un endpoint `GET` sur l’URL `https://api-preprod.dossierfacile.fr/dfc/tenant/profile`
### **2 - Configuration de l’authentification dans Postman** Configurez l’authentification de Postman en Oauth 2.0 puis configurez un nouveau token avec les valeurs suivantes.
| | | | ----------------------- | ----------------------------------------------------------------------------------------------- | | Token Name | oauth2 keycloack | | Grant Type | Authorization Code | | Callback URL | | | Authorize using browser | non coché | | Auth URL | | | Access Token URL | | | Client ID | {{client\_id}} | | Client Secret | {{client\_secret}} | | Scope | openid | | State | | | Client Authentication |

Send as Basic Auth header

| Cliquez ensuite sur Get New Access Token, une fenêtre d’identification DossierFacile va s’ouvrir. {% hint style="info" %} Il est possible de pré-remplir par défaut l'adresse e-mail du locataire en ajoutant `login_hint` en paramètre de l'Auth URL. {% endhint %} {% hint style="info" %} De même, il est possible d'empêcher partiellement le changement d'e-mail avec le paramètre `login_edit_disabled`en paramètre de l'Auth URL.\ Toutefois, ce comportement peut être by-passé en utilisant la connection FC ou en tapant un mot de passe erroné. {% endhint %} Renseignez les champs avec les identifiants d’un compte créé préalablement sur . ![](https://1211770655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_uTTIpEw6lepwml8vT%2Fuploads%2FGpDPzCnmNSYwPARy6enC%2Flogin.png?alt=media\&token=ee82131d-8422-4c29-bce4-19191c6b2139) Vous pouvez également utiliser la connexion FranceConnect en environnement de preproduction. Choisir le fournisseur d'identité "Démontration eIDAS faible" puis identifiant "test" et mot de passe "123". Cliquez ensuite sur Use Token
### **3 - Et enfin lancez la requête Postman**
### **4 - Optionnel 1 : utilisation du refresh token** Il existe dans la réponse à l’authentification un refresh token, qui permet de générer un nouveau token d’authentification afin d’accéder au endpoint `/dfc/tenant/profile` à nouveau sans demander à l’utilisateur de se reconnecter. ```bash curl --location --request POST https://sso-preprod.dossierfacile.fr/auth/realms/dossier-facile/protocol/openid-connect/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id={CLIENT ID VALUE}' \ --data-urlencode 'refresh_token={REFRESH TOKEN VALUE}'\ ``` ### **5 - Optionnel 2 : webhooks** {% hint style="info" %} Il est necessaire d'avoir votre identifiant de connexion pour tester cette fonctionnalité {% endhint %} Il est possible de configurer un webhook afin qu’une fois qu’un utilisateur de DossierFacile est associé à votre plateforme, vous receviez les changements de statuts de son dossier. Ainsi, vous recevez les modifications des statuts sur l'URL de callback. Cela s'opère dès lors que l'utilisateur effectue l'une des actions suivantes : * Complète son dossier `CREATED_ACCOUNT` * Supprime son compte `DELETED_ACCOUNT` * Révoque les droits d'accès à un partenaire `ACCESS_REVOKED` * Change son type d'application (Seul, En couple ou En colocation) `APPLICATION_TYPE_CHANGED` Ou lorsque le dossier est mis à jour par un opérateur ou par une tache planifiée: * Validé `VERIFIED_ACCOUNT` * Décliné `DENIED_ACCOUNT` * Supprimé `DELETED_ACCOUNT` * Archivé / Retour après inactivité\* `ARCHIVED_ACCOUNT/RETURNED_ACCOUNT` * Fusionné avec un autre compte `MERGED_ACCOUNT` {% hint style="warning" %} L'URL de votre webhook doit renvoyer un code de statut HTTP `200` ou `202` pour indiquer la bonne réception du message. Tout autre code de statut HTTP, notamment ceux de la catégorie `4XX` ou `5XX`, sera interprété par notre système comme une erreur de livraison du webhook. En cas d'erreur, notre système pourra effectuer de nouvelles tentatives de livraison (retry). {% endhint %} **Le format du callback** (certain attribut sont facultatifs selon l'état et le type de callback) : ``` Requête POST sur l'URL prédéfinie contenant le body JSON : A la validation { "id": 0, // Id de l'apartmentSharing "onTenantId": 1, // tenant duquel provient l'evenement "partnerCallBackType": "XXXXXXX", // type de CallBack: DELETED_ACCOUNT / ... "applicationType": "XXXX", // type d'application: COUPLE / ALONE / GROUP "dossierUrl": "url vers la page de résumé" // lorsque le compte est validé "dossierPdfDocumentStatus": "DELETED", // statut génération du document PDF : COMPLETED, ... "dossierPdfUrl": "url vers le path du pdf " // !POST pour génération avec GET // lorsque le compte est validé "status": "TO_PROCESS", // status de l'apartmentSharing : TO_PROCESS / VALIDATED / DECLINED / INCOMPLETE "tenants": ... ... } ``` **Téléchargez le JSON du callback ci-dessous :** :arrow\_heading\_down: {% file src="" %} ### **6 - Optionnel : API pour la synchronisation par endpoint** {% hint style="info" %} Il est nécessaire d'avoir votre identifiant de connexion pour tester cette fonctionnalité. {% endhint %} {% hint style="warning" %} Le token de service ne doit en aucun cas être partagé avec vos utilisateurs. {% endhint %} En plus de la récupération des données de l'utilisateur par connexion avec `{baseurl_API}/dfc/tenant/profile` et de la synchronisation par réception du webhook, DossierFacile permet également aux partenaires de récupérer la liste des utilisateurs DossierFacile qui sont associés à leur système et de récupérer leurs données. Pour appeler ces endpoints (`{baseurl_API}/dfc/api/v1/**`), il est nécessaire de réaliser une authentification OAuth2 du service via `{baseurl_SSO}/auth/realms/dossier-facile/protocol/openid-connect/token` Par mesure de sécurité, ces endpoints ne sont pas activés par défaut pour tous les partenaires. Rapprochez-vous de votre interlocuteur DossierFacile pour son activation.\ \ Pour plus d'information consulter la documentation Swagger [`https://api-preprod.dossierfacile.fr/swagger-ui`](https://api-preprod.dossierfacile.fr/swagger-ui/index.html?urls.primaryName=API%20DFC)

Example de connexion service sur la pré-prod pour la récupération de l'acces token

### 8 - Visualiser et modifier votre configuration Il est possible de visualiser et d'éditer certaines information de votre configuration. Vous devez vous connecter avec votre client et utiliser le endpoint suivant: `GET {{baseUrl}}/dfc/api/v1/settings` : Pour la visualisation `PATCH {baseurl}/dfc/api/v1/settings` : Pour l'edition des champs (tout les champs ne sont pas éligible à l'édition - ex: le nom du client) Ce endpoint vous permet notamment d'éditer: Votre version des API, l'URL de webhook et son x-api-key associé, l'email de contact technique. {% hint style="info" %} Pour rappel, pour obtenir un accessToken "service", il faut appeler le endpoint POST `{{baseUrlSSO}}/auth/realms/dossier-facile/protocol/openid-connect/token`avec dans le body (form) `grant_type=client_credentials, clientId=VotreClientId, clientSecret=VotreClientSecret` {% endhint %} ## **Prendre** rendez-vous pour plus d'informations {% content-ref url="../echangez-avec-un-membre-de-lequipe" %} [echangez-avec-un-membre-de-lequipe](https://partenaire.dossierfacile.logement.gouv.fr/echangez-avec-un-membre-de-lequipe) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://partenaire.dossierfacile.logement.gouv.fr/documentation-technique/dossierfacile-connect.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.