Démarche APIsation

Une étude sur la démarche d'APIsation menée par Wavestone pour le ministère de l'agriculture en 2018.

Transcript

1. 13/06/2018 Ministère de l’Agriculture Démarche APIsation Préconisations Ce document est la propriété exclusive du Ministère de l'Agriculture et de l'Alimentation (MAA). Il est extrait d'un livrable d'une prestation de conseil exécutée par la société Wavestone pour le compte du MAA.
2. © WAVESTONE 2 Présentation du document INTRODUCTION Dans le cadre de la démarche d’APIsation du MAA, qui s’inscrit dans une démarche interministérielle favorisant l’OpenData, un ensemble de préconisations a été établit respectant l’état de l’art et le contexte préexistant du MAA. Ce document décrit l’ensemble de ces préconisations et sert de base de référence pour les équipes en charge de la gouvernance des APIs. Il comporte 4 parties : A destination des architectes, elle doit donner l’orientation en termes de stratégie d’API Management (nombre et configuration des API Gateway, cas d’usages justifiant de consommer en direct, etc…) Architecture Design A destination des développeurs, elle représente les règles qui doivent être suivies lors du développement afin de garantir la cohérence de l’écosystème API Sécurité Elle compile l’ensemble des mesures de sécurité, nécessaires ou additionnelles, qu’il est possible de mettre en place afin de garantir la sécurité des APIs, à destination des architectes et des développeurs Elle décrit les structures de gouvernance, et notamment les responsabilités dont les porteurs doivent clairement être identifiés, nécessaires à la réussite d’une démarche d’APIsation Gouvernance
3. © WAVESTONE 3 AGENDA Architecture Design Sécurité Gouvernance Page 4 Page 71 Page 52 Page 39 /1 /2 /3 /4 Annexes Page 95 /5
4. Architecture /1
5. © WAVESTONE 5 Canal Traditionnel Canal Traditionnel Canal Digital Canal Digital Vision métier d’une API ARCHITECTURE Donn ées Donn ées Fonct ions Fonct ions API API API Store API Store Distributeur Transformation des produits bruts Restaurant Applications mobile / sites web / serveur applicatif Producteur / Fabricant Fournisseur de l’API Produits bruts Bases de données / Applications Client final Définition métier • Par analogie, on peut comparer une API à un distributeur (Hypermarchés...) • Une API est un canal de distribution permettant de diffuser (et éventuellement vendre) les données (produits bruts ou transformés) de l’entreprise à des clients finaux via des applications (applications mobiles, site web etc…) Supermarché
6. © WAVESTONE 6 Vision technique d’une API ARCHITECTURE Définition technique API (« Application Programming Interface ») désigne : • Un ensemble de fonctions qui sert d’interface par laquelle un système logiciel (Producteur) propose des services à des applications (Consommateurs). • Un contrat décrivant comment se servir des fonctions (opérations, entrées, sorties et types). Il n’est pas forcément technique et peut être simplement de la documentation. Définition technique API (« Application Programming Interface ») désigne : • Un ensemble de fonctions qui sert d’interface par laquelle un système logiciel (Producteur) propose des services à des applications (Consommateurs). • Un contrat décrivant comment se servir des fonctions (opérations, entrées, sorties et types). Il n’est pas forcément technique et peut être simplement de la documentation. Contrat + Système logiciel Interface Producteur Producteur Consommateurs Consommateurs Don née s Don née s Application / utilisateur Application / utilisateur HTTP(s) HTTP(s) Inter face du servi ce web Application / utilisateur Application / utilisateur Fonc tions Fonc tions Google Maps fournit les villes et leurs emplacements Google Maps fournit les villes et leurs emplacements Google Maps donne le trajet entre 2 villes Google Maps donne le trajet entre 2 villes Exposition de données Exposition de données Exposition de services Exposition de services HTTP(s) HTTP(s) Approche ressource Approche service
7. © WAVESTONE 7 Intérêts et limites des APIs ARCHITECTURE Les APIs sont devenues la norme sur Internet, portées par les géants de web (Amazon, Google, Facebook …). Il n’est pas surprenant de voir l’état français s’engager dans la même direction à travers la stratégie « état plateforme ». Une API ne peut pas être consommée directement par un utilisateur sans une interface intermédiaire, consommant l’API d’un côté, et restituant les données sous forme « lisible » à l’utilisateur de l’autre côté. Il peut être nécessaire dans certains cas de développer ces interfaces intermédiaires en plus des APIs si les services tiers ne sont pas satisfaisants ou existants. Les APIs permettent d’exposer des données d’une manière moderne et standardisée, facilitant la consommation par les tiers, mais également à l’intérieur de l'organisation. Les APIs permettent l’émergence de services à valeur ajoutée, qui peuvent orchestrer l’accès à plusieurs API et apporter un traitement supplémentaire aux données dans l’intérêt de l’utilisateur et au finale l’image de l'organisation.
8. © WAVESTONE 8 ARCHITECTURE Les cas d’usages d’APIs (1/2) Exposition de données métiers Ces données métiers peuvent provenir de différents systèmes (métiers, référentielles, consolidées, orchestrées …) API de services métiers Consolider des données brutes, souvent complexes, et y apporte des traitements métiers adaptés pour produire des données exploitables par les clients API de données référentielles Centraliser des données référentielles API de données métiers Partager les données métiers produites par un domaine métier particulier Il s’agit ici d’APIs produites par l'organisation. Elles peuvent être consommées en interne, des partenaires ou le public. Elles peuvent également orchestrer des appels vers d’autres API (internes ou externes). Il s’agit ici d’APIs produites par l'organisation. Elles peuvent être consommées en interne, des partenaires ou le public. Elles peuvent également orchestrer des appels vers d’autres API (internes ou externes). Exposer des interfaces legacy (difficile à réécrire / adapter) via des API REST dédiées Exemples : webservices SOAP existants API de façade
9. © WAVESTONE 9 ARCHITECTURE Les cas d’usages d’APIs (2/2) Il s’agit ici d’APIs produites par l'organisation ou appartenant à un produit utilisé par l'organisation. Elles sont consommées uniquement en interne. Il s’agit ici d’APIs produites par l'organisation ou appartenant à un produit utilisé par l'organisation. Elles sont consommées uniquement en interne. API de services techniques Centraliser l’utilisation d’une plateforme transverse à plusieurs applications clientes API intra- application Permettre la communication des données entre le front-end et le back- end d’une même application / infrastructure API d’un produit Accéder à des fonctionnalités (principalement techniques) propres à des produits (progiciels …) Il s’agit ici d’APIs produites par des tiers et consommées à l’extérieur de l'organisation. Il s’agit ici d’APIs produites par des tiers et consommées à l’extérieur de l'organisation. API externes Consommer des APIs externes par des applications internes au SI ou externes mais maitrisées par l'organisation (app mobile …). Exemples : data.gouv.fr, INSEE, SGMAP
10. © WAVESTONE 10 ARCHITECTURE Vision d’une architecture « API-sée » Plateforme d’API Plateforme d’API API manager API manager Identity Access Management Identity Access Management Serveur d’application Serveur d’application Passerelle d’API Passerelle d’API Magasin d’API Magasin d’API API 1 API 1 API 2 API 2 API 3 API 3 Bases d’identifiants utilisateurs Bases d’identifiants utilisateurs Données métier Données métier Applications "legacy" Applications "legacy" Applications web Applications web Applications mobile Applications mobile Autres applications internes Autres applications internes Serveur d’application Héberge les applications métier (qui exposent une API) et simplifie l’accès aux sources de données du SI. Questions typiques : • Quel serveur(s) d’application (Tomcat, Nginx, …) ? • Quelle infrastructure de développement (Jersey, Spring, …) ? • Quelles sources de données (mainframe (DB2, transactions CICS), web services, bases mySQL/Oracle, …) Serveur d’application Héberge les applications métier (qui exposent une API) et simplifie l’accès aux sources de données du SI. Questions typiques : • Quel serveur(s) d’application (Tomcat, Nginx, …) ? • Quelle infrastructure de développement (Jersey, Spring, …) ? • Quelles sources de données (mainframe (DB2, transactions CICS), web services, bases mySQL/Oracle, …) Identity Access Management Assure les fonctionnalités d’identification, authentification et autorisation adapté à une architecture API (cad. par jeton) : Questions typiques : • Quel framework (Oauth2/OIDC est le plus répandu) ? • Quelle solution (OpenAM, ISAM, Ping, CAS … ou dev custom) ? • Quel format de jeton (JWT vs UID simple) ? Identity Access Management Assure les fonctionnalités d’identification, authentification et autorisation adapté à une architecture API (cad. par jeton) : Questions typiques : • Quel framework (Oauth2/OIDC est le plus répandu) ? • Quelle solution (OpenAM, ISAM, Ping, CAS … ou dev custom) ? • Quel format de jeton (JWT vs UID simple) ? API manager Assure l’agrégation des API, le contrôle des flux (sécurité, volume, …) et l’interface avec les consommateurs (souscription, documentation, monétisation, …) Questions typiques : • Quelle solution (WSO2, SoftwareAG, CA, IBM, Tyk, …) ? • Quels contrôles pour quelles API ? • API manager pour les appels internes aux API ? API manager Assure l’agrégation des API, le contrôle des flux (sécurité, volume, …) et l’interface avec les consommateurs (souscription, documentation, monétisation, …) Questions typiques : • Quelle solution (WSO2, SoftwareAG, CA, IBM, Tyk, …) ? • Quels contrôles pour quelles API ? • API manager pour les appels internes aux API ? Éditeur d’API Éditeur d’API Une architecture API-sée met en relation les applications « clientes » avec les serveurs qui leur fournissent la donnée qu’elle « consomme ». Une architecture API-sée met en relation les applications « clientes » avec les serveurs qui leur fournissent la donnée qu’elle « consomme ».
11. © WAVESTONE 11 Les fonctionnalités d’un API Manager : passerelle, magasin et éditeur ARCHITECTURE Ressources / Données Ressources / Données API Manager API Manager Passerelle d’API Passerelle d’API Magasin d’API Magasin d’API Éditeur d’API Éditeur d’API Découverte Découverte Souscription Souscription Dashboard Dashboard Gouvernance Gouvernance Facturation Facturation Monitoring Monitoring Authorisation Authorisation Exécution des polices Exécution des polices Exposition de resources Exposition de resources Intrusion prévention Intrusion prévention Regulation du traffic Regulation du traffic Fabriquant d’API Fabriquant d’API Développeur Développeur 1 1 2 2 3 3 Le fabriquant d’API publie son API Le fabriquant d’API publie son API Le développeur d’applications souscrit à l’API Le développeur d’applications souscrit à l’API L’application envoie des requêtes à l’API L’application envoie des requêtes à l’API Ca nau x Ca nau x Int erc on nex ion de l’éc osy stè me Int erc on nex ion de l’éc osy stè me Ser vic es Ser vic es L’API management permet d’industrialiser et dématérialiser la gestion de la relation entre les consommateurs et les producteurs de l’API. L’API management permet d’industrialiser et dématérialiser la gestion de la relation entre les consommateurs et les producteurs de l’API. Passerelle d’API (API Gateway) • Sécurisation API: Filtrage des messages (attaques XML/JSON), chiffrement • Exposition des services/ressources: Transformation et rupture de protocole, virtualisation, orchestration simple… • Quotas et seuils : limitation nombre appels/seconde… • Vérification des identités des consommateurs: support jeton JWT, protocole OIDC et Oauth2 etc. Passerelle d’API (API Gateway) • Sécurisation API: Filtrage des messages (attaques XML/JSON), chiffrement • Exposition des services/ressources: Transformation et rupture de protocole, virtualisation, orchestration simple… • Quotas et seuils : limitation nombre appels/seconde… • Vérification des identités des consommateurs: support jeton JWT, protocole OIDC et Oauth2 etc. Magasin d’API (API Store) • Publication des API: Fourniture des point d’accès, de la doc et des exemples aux développeurs • Souscription aux API: Enregistrement de l’identité des développeurs • Tableau de bord développeurs: Obtention de statistiques d’usage… Magasin d’API (API Store) • Publication des API: Fourniture des point d’accès, de la doc et des exemples aux développeurs • Souscription aux API: Enregistrement de l’identité des développeurs • Tableau de bord développeurs: Obtention de statistiques d’usage… Éditeur d’API (API Publisher) • Gouvernance de l’API: Cycles de vie, versioning… • Gestion des droits, rôles et SLA(s) pour appeler les service et l’accès à l’API Store • Facturation des consommateurs • Supervision de l’API • Tableau de bord administrateur: Statistiques d’usage des APIs par application, par développeur, etc. Éditeur d’API (API Publisher) • Gouvernance de l’API: Cycles de vie, versioning… • Gestion des droits, rôles et SLA(s) pour appeler les service et l’accès à l’API Store • Facturation des consommateurs • Supervision de l’API • Tableau de bord administrateur: Statistiques d’usage des APIs par application, par développeur, etc. API API
12. © WAVESTONE 12 Le marché des solutions d’API Management 1/3 Axway est une solution d’API management déployée chez de nombreux clients en France (Total, iCDC, Fortis, BPCE). Elle a prouvé sa robustesse et sa performance dans des cas d’usages réels. Elle fournit des fonctionnalités sécurité avancées (couplage à un anti virus, lutte contre les injections de code, etc.). Axway est une solution d’API management déployée chez de nombreux clients en France (Total, iCDC, Fortis, BPCE). Elle a prouvé sa robustesse et sa performance dans des cas d’usages réels. Elle fournit des fonctionnalités sécurité avancées (couplage à un anti virus, lutte contre les injections de code, etc.). WSO2 est la solution opensource d’APIM leader. Elle est mise en prod et/ou reconnue comme solution cible chez plusieurs de nos clients (Crédit Agricole, Société Générale IBFS, …). Elle bénéficie également d’une communauté active. A noter qu’une nouvelle version entièrement révisée est prévue pour début 2018. WSO2 est la solution opensource d’APIM leader. Elle est mise en prod et/ou reconnue comme solution cible chez plusieurs de nos clients (Crédit Agricole, Société Générale IBFS, …). Elle bénéficie également d’une communauté active. A noter qu’une nouvelle version entièrement révisée est prévue pour début 2018. La solution de CA est largement reconnue. Elle a été retenue notamment par la BNPP (ITG). C’est une solution complète, qui propose de nombreuses fonctionnalités de médiation et qui assure également une protection contre les failles du TOP 10 OWASP. Néanmoins son administration (via un client lourd) est datée et complexe. La solution de CA est largement reconnue. Elle a été retenue notamment par la BNPP (ITG). C’est une solution complète, qui propose de nombreuses fonctionnalités de médiation et qui assure également une protection contre les failles du TOP 10 OWASP. Néanmoins son administration (via un client lourd) est datée et complexe. IBM était en clairement en retard sur le marché, plombé par la gamme Datapower qui a toujours rencontré un succès commercial mitigé. Cette année, sa solution API connect a entièrement été refondue et semble prometteuse. Elle a notamment été adoptées par PSA. La solution est cloud hybride, et supporte les websocket. IBM était en clairement en retard sur le marché, plombé par la gamme Datapower qui a toujours rencontré un succès commercial mitigé. Cette année, sa solution API connect a entièrement été refondue et semble prometteuse. Elle a notamment été adoptées par PSA. La solution est cloud hybride, et supporte les websocket. TIBCO est un leader sur le marché des produits middleware. Ils ont racheté et intégré à leur offre le produit Mashery, leader et pure player du marché, initialement détenu par INTEL. Nous n’avons pas de REX client sur ce produit mais beaucoup de REX positifs sur l’EAI/ESB de TIBCO et les bus de messages(PMU, AG2RLM, etc.). TIBCO est un leader sur le marché des produits middleware. Ils ont racheté et intégré à leur offre le produit Mashery, leader et pure player du marché, initialement détenu par INTEL. Nous n’avons pas de REX client sur ce produit mais beaucoup de REX positifs sur l’EAI/ESB de TIBCO et les bus de messages(PMU, AG2RLM, etc.). Software AG est un leader historique des middlewares SOA avec son produit phare : WebMethods (ESB). Leur solution d’API Management actuelle est clairement en retrait et peu mature par rapport aux autres éditeurs. Cependant, leur produit est en cours de refonte complète. Software AG est un leader historique des middlewares SOA avec son produit phare : WebMethods (ESB). Leur solution d’API Management actuelle est clairement en retrait et peu mature par rapport aux autres éditeurs. Cependant, leur produit est en cours de refonte complète. Les solutions historiques Généralement issues de solutions ESB, réactualisées et transformée pour la gestion d’API REST. On y trouve des solutions très complètes mais souvent assez lourdes et complexes. Les éditeurs fournissent un niveau de support élevé en lien avec leur taille. ARCHITECTURE
13. © WAVESTONE 13 Le marché des solutions d’API Management 2/3 Solution publiée en 2010 et rachetée en 2016 par Google, Apigee Edge est un API Manager cloud et on-premise récent mais à la politique commerciale très agressive sur le marché européen. La solution est à l’étude chez Malakoff Médéric. Solution publiée en 2010 et rachetée en 2016 par Google, Apigee Edge est un API Manager cloud et on-premise récent mais à la politique commerciale très agressive sur le marché européen. La solution est à l’étude chez Malakoff Médéric. Salesforce a racheté la solution de Mulesoft, qui est historiquement une solution purement cloud, et s’est récemment enrichie d’une édition “on-premise”. Celle-ci est complexe à mettre en place et moins aboutie que la version cloud. Par ailleurs, nous n’avons pas connaissance de références significative. Salesforce a racheté la solution de Mulesoft, qui est historiquement une solution purement cloud, et s’est récemment enrichie d’une édition “on-premise”. Celle-ci est complexe à mettre en place et moins aboutie que la version cloud. Par ailleurs, nous n’avons pas connaissance de références significative. 3scale est une Solution initialement full cloud et récemment enrichie d’une offre partiellement on-premise lors de son rachat par Red Hat. 3scale est une Solution initialement full cloud et récemment enrichie d’une offre partiellement on-premise lors de son rachat par Red Hat. Anciennement Mashape, Kong a été écrit en 2009 en C/Lua et est basé sur Nginx. L’API Gateway fonctionne sur un principe de plugin pour implémenter ses fonctionnalités. Les fonctionnalités d’API Store et de monitoring sont fournies par les solutions (cloud, payantes) Gelato et Galileo. La solution est étudiée par Nexity. Anciennement Mashape, Kong a été écrit en 2009 en C/Lua et est basé sur Nginx. L’API Gateway fonctionne sur un principe de plugin pour implémenter ses fonctionnalités. Les fonctionnalités d’API Store et de monitoring sont fournies par les solutions (cloud, payantes) Gelato et Galileo. La solution est étudiée par Nexity. Tyk est un API Manager léger et relativement récent (2014) écrit en Go. Peu de référence à date sur cette solution. Tyk est un API Manager léger et relativement récent (2014) écrit en Go. Peu de référence à date sur cette solution. Les nouvelles solutions Plus récentes, et créées directement pour la gestion d’API. Ces solutions, majoritairement open-source sont parfois plus limitées en fonctionnalités mais plus légère et moins couteuses. APIMan est une solution full on-premise de RedHat. Celle-ci va certainement être fusionnée avec 3scale dans un futur proche. APIMan est une solution full on-premise de RedHat. Celle-ci va certainement être fusionnée avec 3scale dans un futur proche. ARCHITECTURE
14. © WAVESTONE 14 Le marché des solutions d’API Management 3/3 Solution d’API Gateway uniquement, mis à disposition sur le cloud AWS. La solution est simple à mettre en place, mais le coût à la consommation est élevé. Euler Hermes envisage son utilisation. Solution d’API Gateway uniquement, mis à disposition sur le cloud AWS. La solution est simple à mettre en place, mais le coût à la consommation est élevé. Euler Hermes envisage son utilisation. Solution d’API Gateway fournie sur Google Cloud Platform. Peu de retour d’expérience car peu d’utilisateurs de GCP parmi nos clients. Solution d’API Gateway fournie sur Google Cloud Platform. Peu de retour d’expérience car peu d’utilisateurs de GCP parmi nos clients. Les outsiders Ce sont des solutions originellement non prévue pour de l’API Management, mais dont l’intégration dans un écosystème à coté d’autres outils peut permettre de couvrir les fonctionnalités attendues. Zuul est une solution open-source publiée par Netflix au sein de sa stack OSS. Ce produit est beaucoup moins complet que les autres dans cette liste et fournit avant tout des fonctionnalités d’API Gateway (reverse- proxy avancé avec des capacités de routage). Elle ne gère pas par exemple l’authentification. Zuul est une solution open-source publiée par Netflix au sein de sa stack OSS. Ce produit est beaucoup moins complet que les autres dans cette liste et fournit avant tout des fonctionnalités d’API Gateway (reverse- proxy avancé avec des capacités de routage). Elle ne gère pas par exemple l’authentification. Google Cloud Endpoint AWS API Gateway ARCHITECTURE
15. © WAVESTONE 15 Détail des fonctionnalités de l’API Manager ARCHITECTURE Mise en cache Mise en cache Mise en cache d’une partie des résultats des appels aux API (standards HTTP) Mise en cache d’une partie des résultats des appels aux API (standards HTTP) Authen/autor des accès Authen/autor des accès Vérification des jetons de sécurité et de l’autorisation d’accès à la maille API Vérification des jetons de sécurité et de l’autorisation d’accès à la maille API Médiation et interopérabilité Médiation et interopérabilité Médiation protocolaire et forçage de certains standards d’interopérabilité Médiation protocolaire et forçage de certains standards d’interopérabilité Catalogue et documentation Catalogue et documentation Catalogue d’API éligibles et documentation (compatible avec le format Swagger/OpenAPI) Catalogue d’API éligibles et documentation (compatible avec le format Swagger/OpenAPI) Bac à sable Bac à sable Outils de test des API (bouchons) par les développeurs d’applications Outils de test des API (bouchons) par les développeurs d’applications Gestion de quotas Gestion de quotas Attribution de quotas sur la consommation des API (globaux et spécifiques aux comptes) Attribution de quotas sur la consommation des API (globaux et spécifiques aux comptes) Cycle de vie Cycle de vie Gestion du cycle de vie des API (définition, test, publication, mise à jour, décommissionnement) Gestion du cycle de vie des API (définition, test, publication, mise à jour, décommissionnement) Niveaux de service Niveaux de service Différents niveaux de service pour les différentes API Différents niveaux de service pour les différentes API Routage Routage Découverte des services et routage des échanges Découverte des services et routage des échanges Équilibrage de charge Équilibrage de charge Répartition de la charge entre les nœuds d’une même API Répartition de la charge entre les nœuds d’une même API Compteur d’API Compteur d’API Mesure de la consommation de chaque application consommatrice (par API, par jour, ...) Mesure de la consommation de chaque application consommatrice (par API, par jour, ...) Souscription au service Souscription au service Gestion de la visibilité Gestion de la visibilité Quel développeur d’application peut accéder à quelles API ? Quel développeur d’application peut accéder à quelles API ? Gestion des droits Gestion des droits Règles de Facturation Règles de Facturation Mécanismes de facturation de l’utilisation des API (nombre d’appels, SLA souscrit …) Mécanismes de facturation de l’utilisation des API (nombre d’appels, SLA souscrit …) Passerelle d’API Magasin d’API Éditeur d’API Suivi de la consommation Suivi de la consommation Centre d’alerte Centre d’alerte Sur atteinte des quotas ou évènement de sécurité Sur atteinte des quotas ou évènement de sécurité Limitation d’usage Limitation d’usage Limitation de la consommation pour une application (ex: 10k appels / jour pour API A) Limitation de la consommation pour une application (ex: 10k appels / jour pour API A) Gestion de son compte développeur et souscription aux API sous réserve d’éligibilité Gestion de son compte développeur et souscription aux API sous réserve d’éligibilité Portail de suivi des souscription, de la consommation et de la facturation Portail de suivi des souscription, de la consommation et de la facturation Gestion de droits d’accès des utilisateurs et systèmes (pour magasin & passerelle d’API) Gestion de droits d’accès des utilisateurs et systèmes (pour magasin & passerelle d’API) TYK peut implémenter certaines de ces fonctionnalités dans une autre brique, voire pas l’implémenter. Wavestone ne dispose pas de retours d’expériences sur cette solution pour contextualisée ce tableau par rapport à TYK.
16. © WAVESTONE 16 APIs qui sont accessibles par tout le monde APIs qui sont seulement accessibles par les partenaires du fournisseur de l’API. APIs qui sont utilisées en interne pour faciliter l’intégration de différents systèmes et applications. Trois types d’API associées à plusieurs cas d’usages ARCHITECTURE Privées Partenaires Ouvertes Open data / Nouveaux modèle d’affaire Partage de services avec les partenaires Backend modulaire et à évolution rapide Cas d’usages
17. © WAVESTONE 17 Détail des fonctionnalités par type d’API ARCHITECTURE Passerelle d’API Magasin d’API Éditeur d’API Mise en cache Mise en cache Authen/autor des accès Authen/autor des accès Médiation et interopérabilité Médiation et interopérabilité Catalogue et documentation Catalogue et documentation Bac à sable Bac à sable Gestion de quotas Gestion de quotas Cycle de vie Cycle de vie Niveaux de service Niveaux de service Routage Routage Équilibrage de charge Équilibrage de charge Compteur d’API Compteur d’API Souscription au service Souscription au service Gestion de la visibilité Gestion de la visibilité Gestion des droits Gestion des droits Facturation Facturation Suivi de la consommation Suivi de la consommation Centre d’alerte Centre d’alerte Limitation d’usage Limitation d’usage Mise en cache Mise en cache Authen/autor des accès Authen/autor des accès Médiation et interopérabilité Médiation et interopérabilité Catalogue et documentation Catalogue et documentation Bac à sable Bac à sable Gestion de quotas Gestion de quotas Cycle de vie Cycle de vie Niveaux de service Niveaux de service Routage Routage Équilibrage de charge Équilibrage de charge Compteur d’API Compteur d’API Souscription au service Souscription au service Gestion de la visibilité Gestion de la visibilité Gestion des droits Gestion des droits Facturation Facturation Suivi de la consommation Suivi de la consommation Centre d’alerte Centre d’alerte Limitation d’usage Limitation d’usage Mise en cache Mise en cache Authen/autor des accès Authen/autor des accès Médiation et interopérabilité Médiation et interopérabilité Catalogue et documentation Catalogue et documentation Bac à sable Bac à sable Gestion de quotas Gestion de quotas Cycle de vie Cycle de vie Niveaux de service Niveaux de service Routage Routage Équilibrage de charge Équilibrage de charge Compteur d’API Compteur d’API Souscription au service Souscription au service Gestion de la visibilité Gestion de la visibilité Gestion des droits Gestion des droits Facturation Facturation Suivi de la consommation Suivi de la consommation Centre d’alerte Centre d’alerte Limitation d’usage Limitation d’usage xxx xxx xxx xxx xxx xxx Obligatoire Pas nécessaire Utile mais non obligatoire Privées Partenaires Ouvertes
18. © WAVESTONE 18 Consommateurs Consommateurs SI Interne SI Interne Exposer les APIs à l’extérieur via l’API Gateway ARCHITECTURE L’API Gateway est la porte d’entrée du SI. Tous les flux API venant d’Internet et des partenaires doivent passer par l’API Gateway, y compris ceux provenant d’applications maitrisées par l'organisation. L’API Gateway est la porte d’entrée du SI. Tous les flux API venant d’Internet et des partenaires doivent passer par l’API Gateway, y compris ceux provenant d’applications maitrisées par l'organisation. Clients Clients APIs APIs Internet / RIE Internet / RIE Application s mobiles Application s mobiles Partenaires Partenaires Applications maitrisées par l'organisation Applications maitrisées par l'organisation API GW API GW A1 … …
19. © WAVESTONE 19 En interne, consommer les APIs en passant par la Gateway, sauf exception ARCHITECTURE A2 La consommation interne d’APIs internes doit passer par l’API Gateway pour avoir une bonne visibilité sur l’ensemble des flux de consommation. En exception, il est possible de consommer en direct. La consommation interne d’APIs internes doit passer par l’API Gateway pour avoir une bonne visibilité sur l’ensemble des flux de consommation. En exception, il est possible de consommer en direct. SI interne SI interne Consommateurs internes Consommateurs internes APIs APIs API GW API GW SI interne SI interne Consommateurs internes Consommateurs internes APIs APIs Cas nominal Cas en exception (développement, débug, API intra-application)
20. © WAVESTONE 20 ARCHITECTURE Publier les APIs externes dans l’API Gateway pour une consommation en interne A3 En interne, consommer les APIs externes via l’API Gateway en les publiant dessus par réécriture DNS, pour maitriser les flux sortants. En interne, consommer les APIs externes via l’API Gateway en les publiant dessus par réécriture DNS, pour maitriser les flux sortants. SI Interne SI Interne APIs externes APIs externes Internet / RIE Internet / RIE API GW API GW Consommateurs internes Consommateurs internes Le consommateur requête une url interne (ex: https://intranet/accounts/v1/curr entAccounts/76873) Publication de l’API externe sur l’API GW par réécriture DNS (ex: https://partenaire- principal.fr/accounts/v1/currentA ccounts/76873) Afin d’éviter les collisions entre des APIs d’origines différentes, qui peuvent porter le même nom, il est possible de réécrire totalement l’URL, et pas uniquement le nom de domaine. Afin d’éviter les collisions entre des APIs d’origines différentes, qui peuvent porter le même nom, il est possible de réécrire totalement l’URL, et pas uniquement le nom de domaine. Faisabilité technique décrite ici : https://tyk.io/docs/transform-traffic/url-rewriting/
21. © WAVESTONE 21 ARCHITECTURE Pour une application externe maitrisée par l'organisation, consommer les APIs externes en direct, sauf exception A4 Pour une application externe maitrisée par l'organisation (par ex app sur mobile), consommer les APIs externes en direct pour de meilleures performances, sauf si le passage par l’API GW de l'organisation présente un intérêt. Pour une application externe maitrisée par l'organisation (par ex app sur mobile), consommer les APIs externes en direct pour de meilleures performances, sauf si le passage par l’API GW de l'organisation présente un intérêt. Consommateurs Consommateurs SI interne SI interne APIs externes APIs externes Internet Internet Applications externes maitrisées par l'organisation Applications externes maitrisées par l'organisation API GW API GW Cas nominal Cas en exception, s’il y a un besoin particulier en termes de sécurité, facturation, filtrage des consommateurs … APIs externes APIs externes Consommateurs Consommateurs Applications externes maitrisées par l'organisation Applications externes maitrisées par l'organisation
22. © WAVESTONE 22 ARCHITECTURE En résumé … RIE / Partenaires / Internet SI interne API interne Consommateurs internes (API, application, service …) API Gateway Consommateurs non maitrisés (partenaires, publiques …) Consommateurs maitrisés (application web, application mobile …) API externe Exposer les API à l’extérieur via l’API GW En exception, se permettre de consommer en direct Exposer les API externe sur l’API GW pour la consommation interne En externe, consommer les API externes en direct Exposer les API à l’extérieur via l’API GW Passer par l’API Gateway pour la consommation interne En exception, passer par l’API GW si elle apporte une valeur ajoutée Pour les API nécessitant un passage par l’API Gateway, un filtrage réseau peut être mis en place pour empêcher la consommation en direct.
23. © WAVESTONE 23 Contexte : organisation du MAA en QSI ARCHITECTURE Le SI du MAA est structuré autour de plusieurs quartiers technico-fonctionnels (QSI) Par souci de simplification, nous représenterons dans les slides suivants les différents QSI avec des numéros. Le SI du MAA est structuré autour de plusieurs quartiers technico-fonctionnels (QSI) Par souci de simplification, nous représenterons dans les slides suivants les différents QSI avec des numéros.
24. © WAVESTONE 24 SI interne SI interne QSI 1 QSI 1 QSI 11 QSI 11 CU.A1 : API Store / API Publisher uniques API Store API Store API Publisher API Publisher … Pour quelles raisons adopter cette architecture ? ⁄ Simplicité ⁄ Harmonisation des usages ⁄ Point d’entrée unique pour les consommateurs Pour quelles raisons éviter cette architecture ? ⁄ Gouvernance ne permettant pas de gérer de manière centralisée et transverse ces deux composants d’infrastructure ARCHITECTURE Il s’agit de l’architecture à adopter, et observée chez nos clients, dès lors que la gouvernance le permet. Il s’agit de l’architecture à adopter, et observée chez nos clients, dès lors que la gouvernance le permet. A5 La mise en place d’un centre de contrôle des API (cf partie gouvernance) peut contribuer à adopter cette architecture transverse. Tyk expose les services API Store et API Publisher via des API, qui peuvent être utilisées pour mutualiser ces services en 1 seul point d'accès si plusieurs briques doivent être mises en place. Tyk expose les services API Store et API Publisher via des API, qui peuvent être utilisées pour mutualiser ces services en 1 seul point d'accès si plusieurs briques doivent être mises en place.
25. © WAVESTONE 25 SI interne SI interne CU.A2 : API Store / API Publisher multiples ARCHITECTURE API Store 1 API Store 1 API Publisher 1 API Publisher 1 Pour quelles raisons adopter cette architecture ? ⁄ Contraintes de gouvernance ⁄ Volonté de ségréger les types de consommateurs et d’API (internes, RIE, partenaires, publiques …) Pour quelles raisons éviter cette architecture ? ⁄ Complexité et surcoût de mise en place et maintien en condition opérationnelle ⁄ Multiples points d’entrées pour les consommateurs avec potentiellement des difficultés à savoir où est publiée chaque API à utiliser API Store n API Store n API Publisher n API Publisher n QSI 1 QSI 1 QSI 11 QSI 11 … QSI 2 QSI 2 … A défaut de mettre en place une seule instance de ces 2 briques d’infrastructure, il est possible d’en mettre plusieurs pour satisfaire des contraintes de gouvernance. Cette architecture est très peu observée chez nos clients et même chez les géants d’Internet (GAFA …). A défaut de mettre en place une seule instance de ces 2 briques d’infrastructure, il est possible d’en mettre plusieurs pour satisfaire des contraintes de gouvernance. Cette architecture est très peu observée chez nos clients et même chez les géants d’Internet (GAFA …).
26. © WAVESTONE 26 SI interne SI interne QSI 1 QSI 1 QSI 11 QSI 11 CU.B1 : API Gateway unique et transverse ARCHITECTURE API Gateway API Gateway … Pour quelles raisons adopter cette architecture ? ⁄ Mettre en place cette architecture pour des environnements de tests Pour quelles raisons éviter cette architecture ? ⁄ Cette architecture n’est pas adaptée pour des environnements de production, elle n’offre aucune scalabilité Il s’agit d’une architecture simpliste adaptée principalement pour des environnements de tests. Il s’agit d’une architecture simpliste adaptée principalement pour des environnements de tests.
27. © WAVESTONE 27 SI interne SI interne QSI 1 QSI 1 QSI 11 QSI 11 CU.B2 : API Gateway dupliquées et transverses ARCHITECTURE API Gateway API Gateway … Pour quelles raisons adopter cette architecture ? ⁄ Simplicité ⁄ Harmonisation des usages au sein des QSI ⁄ Besoin d’une haute disponibilité Pour quelles raisons éviter cette architecture ? ⁄ Cette architecture ne permet pas de cloisonner les accès aux API, cela peut s’avérer nécessaire pour des raisons de sécurité (sensibilité des données à exposer), des raisons de gouvernance (domaines métiers), etc. API Gateway API Gateway QSI 2 QSI 2 Load Balancer Load Balancer Cette architecture est adaptée pour garantir une haute disponibilité des API sans besoin de cloisonnement des accès. Cette architecture est adaptée pour garantir une haute disponibilité des API sans besoin de cloisonnement des accès.
28. © WAVESTONE 28 SI interne SI interne QSI 1 QSI 1 QSI 11 QSI 11 CU.B3 : API Gateway dédiées par type d’accès ARCHITECTURE API Gateway 1 API Gateway 1 … Pour quelles raisons adopter cette architecture ? ⁄ Harmonisation des usages au sein des QSI ⁄ Besoin d’une haute disponibilité ⁄ Besoin de cloisonner les accès aux API pour diverses raisons :  Aspect sécurité (niveau de confidentialité des données, type d’accès : public/privé)  Aspect fonctionnel (détection, enrichissement, perception, action)  Aspect utilisation (volumétrie, facturation, quota)  Contraintes réglementaire (par ex DSP2 (non applicable au ministère)) Pour quelles raisons éviter cette architecture ? ⁄ Eviter de démultiplier les API Gateway si le cloisonnement des accès n’est pas nécessaire API Gateway x API Gateway x API type 1 API type 1 API type 1 API type 1 API type x API type x API type x API type x Routeur Routeur Note : chaque instance d’API Gateway peut être dupliquée pour garantir la haute disponibilité Pour simplifier le schéma, la duplication des API Gateway n’est pas représentée API Gateway 2 API Gateway 2 API type 2 API type 2 API type 2 API type 2 Il s’agit de l’architecture état de l’art, rencontrée chez la plupart des acteurs : elle est adaptée pour répondre à des besoins de cloisonnement des accès aux API, quand une harmonisation des usages et la mise en place d’une gouvernance transverse est possible au sein de l’organisation. Il s’agit de l’architecture état de l’art, rencontrée chez la plupart des acteurs : elle est adaptée pour répondre à des besoins de cloisonnement des accès aux API, quand une harmonisation des usages et la mise en place d’une gouvernance transverse est possible au sein de l’organisation. … … … La même API peut être publiée à travers plusieurs API GW pour cloisonner ses accès
29. © WAVESTONE 29 SI interne SI interne QSI 1 QSI 1 QSI 11 QSI 11 CU.B4 : API Gateway dédiées par ensemble de QSI ARCHITECTURE API Gateway 1 API Gateway 1 … Pour quelles raisons adopter cette architecture ? ⁄ Besoin de cloisonner les accès aux API par QSI ⁄ Pas besoin de cloisonner les accès aux API à l’intérieur de chaque QSI ⁄ Besoin d’une haute disponibilité Pour quelles raisons éviter cette architecture ? ⁄ Cette architecture ne permet pas de cloisonner les accès aux API pour des raisons de sécurité (sensibilité des données à exposer), etc. API Gateway 9 API Gateway 9 QSI 2 QSI 2 API type 1 API type 1 API type 1 API type 1 API type y API type y API type z API type z API type 1 API type 1 API type x API type x Routeur Routeur API Gateway 2 API Gateway 2 … Note : chaque instance d’API Gateway peut être dupliquée pour garantir la haute disponibilité Pour simplifier le schéma, la duplication des API Gateway n’est pas représentée Cette architecture est à privilégier lorsque chaque QSI a des besoins spécifiques nécessitant le cloisonnement des accès par rapport aux autres QSI, mais pas à l’intérieur des QSI. Cette architecture est à privilégier lorsque chaque QSI a des besoins spécifiques nécessitant le cloisonnement des accès par rapport aux autres QSI, mais pas à l’intérieur des QSI. … … …
30. © WAVESTONE 30 SI interne SI interne QSI 1 QSI 1 QSI 11 QSI 11 CU.B5 : API Gateway dédiées par ensemble de QSI et par type d’accès ARCHITECTURE API Gw 1.1 API Gw 1.1 … Pour quelles raisons adopter cette architecture ? ⁄ Besoin de cloisonner l’accès aux API par QSI ⁄ Besoin de cloisonner les accès aux API pour diverses raisons :  Aspect sécurité (niveau de confidentialité des données, type d’accès : public/privé)  Aspect fonctionnel (détection, enrichissement, perception, action)  Aspect utilisation (volumétrie, facturation, quota)  Contraintes réglementaire (par ex DSP2 (non applicable au ministère)) Pour quelles raisons éviter cette architecture ? ⁄ Complexification du SI avec prolifération des instances d’API Gateway API GW 11.2 API GW 11.2 API 1.1 API 1.1 API 11.2 API 11.2 API 11.1 API 11.1 API 11.y API 11.y API 1.x API 1.x API 1.2 API 1.2 Routeur Routeur API GW 1.2 API GW 1.2 API GW 11.y API GW 11.y API Gw 1.x API Gw 1.x API GW 11.1 API GW 11.1 Note : chaque instance d’API Gateway peut être dupliquée pour garantir la haute disponibilité Pour simplifier le schéma, la duplication des API Gateway n’est pas représentée Cette architecture est à mettre en place uniquement s’il est nécessaire de cloisonner les accès à la fois par QSI et par type d’accès, car le nombre d’instances d’API Gateway à prévoir sera très important. Cette architecture est à mettre en place uniquement s’il est nécessaire de cloisonner les accès à la fois par QSI et par type d’accès, car le nombre d’instances d’API Gateway à prévoir sera très important. … … … … …
31. © WAVESTONE 31 SI interne SI interne EH 1 EH 1 EH y EH y Préconisation Wavestone : API Gateway dédiées par type d’accès au sein d’ensembles homogènes pour en limiter le nombre ARCHITECTURE API Gateway 1 API Gateway 1 … Pour quelles raisons adopter cette architecture ? ⁄ Harmonisation des usages au sein des ensembles homogènes ⁄ Besoin d’une haute disponibilité ⁄ Besoin de cloisonner les accès aux API pour diverses raisons :  Aspect sécurité (niveau de confidentialité des données, type d’accès : public/privé)  Aspect fonctionnel (détection, enrichissement, perception, action)  Aspect utilisation (volumétrie, facturation, quota) ⁄ Capacité d’adaptation à un contexte cloisonné au niveau technico-fonctionnel en termes de gouvernance Pour quelles raisons éviter cette architecture ? ⁄ Complexification du SI avec prolifération des instances d’API Gateway API Gateway x API Gateway x API type 1 API type 1 API type 1 API type 1 API type x API type x API type x API type x Routeur Routeur Note : chaque instance d’API Gateway peut être dupliquée pour garantir la haute disponibilité Pour simplifier le schéma, la duplication des API Gateway n’est pas représentée API Gateway 2 API Gateway 2 API type 2 API type 2 API type 2 API type 2 Cette architecture est un compromis entre l’état de l’art et un contexte cloisonné au niveau technico- fonctionnel. Un maximum de mutualisation reste la cible, à l’intérieur d’ensembles homogènes, en mesure de mettre en place une gouvernance transverse. Cette architecture est un compromis entre l’état de l’art et un contexte cloisonné au niveau technico- fonctionnel. Un maximum de mutualisation reste la cible, à l’intérieur d’ensembles homogènes, en mesure de mettre en place une gouvernance transverse. A6 … … … La même API peut être publiée à travers plusieurs API GW pour cloisonner ses accès
32. © WAVESTONE 32 Pattern de composition / transformation d’API ARCHITECTURE L’API Gateway ne doit pas être utilisée pour faire des orchestrations, compositions ou transformations métiers complexes d’API. Préférer les patterns 1 ou 2. L’API Gateway ne doit pas être utilisée pour faire des orchestrations, compositions ou transformations métiers complexes d’API. Préférer les patterns 1 ou 2. Backend Backend Interface (sous resp. backend peut être de l'ESB) Interface (sous resp. backend peut être de l'ESB) Consommateurs Consommateurs Interface non adaptée Interface non adaptée Interface non adaptée Interface non adaptée API GW API GW API de façade API de façade Exposer une API de façade qui fait de la rupture et la translation protocolaires Exposer une API de façade qui fait de la rupture et la translation protocolaires 2 Backend Backend Consommateurs Consommateurs Interface non adaptée Interface non adaptée API adapté e API adapté e API GW API GW Réécrire l’API dans le backend Réécrire l’API dans le backend 1 Backend Backend Consommateurs Consommateurs Interface non adaptée Interface non adaptée Faire la translation protocolaire par l’API Gateway Faire la translation protocolaire par l’API Gateway 3 API GW API GW A7 Dans certains cas, il est plus pertinent de ne pas forcément exposer des API REST, mais rester sur des interfaces non adaptées, types SOAP. C’est souvent le cas lorsque le consommateur (interne ou externe) ne peut pas migrer facilement, que le fonctionnement legacy est satisfaisant ou quand certains besoins sont plus faciles à adresser avec SOAP (WS-Security …).
33. © WAVESTONE 33 Protocoles d’échanges B2C ARCHITECTURE Le protocole HTTP/JSON est à privilégier pour les communications, sauf cas d’usage spécifiques. Le protocole HTTP/JSON est à privilégier pour les communications, sauf cas d’usage spécifiques. Pour les échanges monodirectionnels (Pull) Sur sollicitation par le client Pour les échanges monodirectionnels (Pull) Sur sollicitation par le client HTTPs / JSON HTTPs / JSON Client Client Serveur Serveur API API Pour les échanges bidirectionnels et/ou à fréquence élevée* (Pull & Push) A l’initiative du client ou du serveur Pour les échanges bidirectionnels et/ou à fréquence élevée* (Pull & Push) A l’initiative du client ou du serveur Secure WebSockets Secure WebSockets Client Client Serveur Serveur API API * l’ouverture initiale de la connexion est à l’initiative du client qui « s’abonne au serveur » Ex: récupération des données d’un client, création d’un compte, etc. Ex: récupération des données d’un client, création d’un compte, etc. Ex: cas d’usage conversationnels (chat), données de monitoring temps réel, etc. Ex: cas d’usage conversationnels (chat), données de monitoring temps réel, etc. A8
34. © WAVESTONE 34 Protocoles d’échanges B2B ARCHITECTURE Pour les échanges monodirectionnels (Pull) Sur sollicitation par le client Pour les échanges monodirectionnels (Pull) Sur sollicitation par le client HTTPs / JSON HTTPs / JSON Serveur Serveur Serveur Serveur API API Pour les échanges bidirectionnels et/ou à fréquence élevée (Pull & Push) A l’initiative du client ou du serveur Pour les échanges bidirectionnels et/ou à fréquence élevée (Pull & Push) A l’initiative du client ou du serveur Secure WebSockets* AMQP ou JMS Kafka** Secure WebSockets* AMQP ou JMS Kafka** Serveur Serveur Serveur Serveur API API * l’usage des WebSockets entre deux applications est à éviter car cela revient à faire du point à point entre les deux serveurs Eviter le point à point entre deux applications. MOM Bus de messages MOM Bus de messages API GW API GW Le protocole HTTP/JSON est à privilégier pour les nouvelles APIs sauf obligations réglementaires ou par compatibilité avec un partenaire / une application existante. Le protocole HTTP/JSON est à privilégier pour les nouvelles APIs sauf obligations réglementaires ou par compatibilité avec un partenaire / une application existante. ** Kafka est plutôt adapté pour un usage interne, car il nécessite de diffuser le modèle de topics et d'évènements et c’est difficile de le faire pour des usages externes A8 Il est possible d’adjoindre aux API REST l’utilisation de Webhook pour couvrir les cas d’usage nécessitant un traitement asynchrone et éviter ainsi de devoir passer par l'ESB pour gérer les notifications*. * l’usage des Webhook est à limiter aux cas simples de dialogue asynchrone. Ne pas s’en servir pour des processus complexes
35. © WAVESTONE 35 ARCHITECTURE Zoom sur l’usage des Webhook Les « webhook » sont des API REST qui permettent de déclencher une action à l’occurrence d’un évènement. L’envoi d’une requête spécifique (souvent POST) notifie une application d’un évènement, qui peut ensuite déclencher une action spécifique. Les « webhook » sont des API REST qui permettent de déclencher une action à l’occurrence d’un évènement. L’envoi d’une requête spécifique (souvent POST) notifie une application d’un évènement, qui peut ensuite déclencher une action spécifique. Notifier un consommateur d’API de la fin d’une opération longue, comme une conversion vidéo par exemple ou un virement bancaire Exemples d’utilisation : Déclencher une action lorsqu’un développeur soumet une nouvelle version de son code Avantages / inconvénients • AVANTAGE : évite au consommateur d’avoir à solliciter régulièrement l’application source pour savoir si un évènement est arrivé • INCONVENIENT : nécessite que le consommateur de l’évènement implémente le webhook (donc une API simple)
36. © WAVESTONE 36 Résumé des recommandations d’architecture ARCHITECTURE Ne pas faire de translation protocolaire dans l’API Gateway Pour exposer une interface non-REST, il est préférable de réécrire l’interface, ou de créer une interface intermédiaire qui elle expose les données en REST A7 Exposer les APIs à l’extérieur via l’API Gateway A1 Publier les APIs externes dans l’API Gateway pour une consommation en interne A3 Rationnaliser le nombre de Gateways Mettre en place différentes Gateways pour des raisons fonctionnelles, mais les mutualiser au sein d’ensembles homogènes (structures sur lesquelles il est possible de mettre en place une gouvernance transverse). Ces Gateways peuvent être dupliquées pour assurer la haute disponibilité A6 Privilégier le protocole HTTP/JSON Eviter au maximum le point à point entre deux applications A8 En interne, consommer les APIs via la Gateway, sauf exception A2 Pour une application externe maitrisée par l'organisation, consommer les APIs externes en direct, sauf exception A4 Mutualiser au maximum l’API Manager L’architecture cible doit avoir un unique API Store et API Publisher pour l’ensemble de l'organisation A5
37. Design /2
38. © WAVESTONE 38 Usages et caractéristiques Usages et caractéristiques Protocoles cibles Protocoles cibles Fonctionnement Fonctionnement Conception API services vs ressources DESIGN Mode services Mode services Mode ressources Mode ressources Permet la réutilisation de traitements complexes Implique une forte dépendance entre l’applicatif qui utilise l’API et le serveur qui la fournit : l’application doit connaitre le fonctionnement de l’API pour l’utiliser Permet la réutilisation de traitements complexes Implique une forte dépendance entre l’applicatif qui utilise l’API et le serveur qui la fournit : l’application doit connaitre le fonctionnement de l’API pour l’utiliser Permet une exposition simple et intuitive de la donnée Implique un découplage entre le fonctionnement de l’API et l’applicatif qui l’utilise Permet une exposition simple et intuitive de la donnée Implique un découplage entre le fonctionnement de l’API et l’applicatif qui l’utilise HTTP/JSON (Monodirectionnel) ou Websocket (Bidirectionnel) HTTP/JSON (Monodirectionnel) ou Websocket (Bidirectionnel) /monAPI.com/monServiceLecture GET /monAPI.com/monServiceEcriture POST Webservices en lecture Webservices en écriture Manipulation des ressources avec les verbes HTTP /monAPI.com/mesressources/idMaressource GET /monAPI.com/mesressources POST Lecture Ecriture /monAPI.com/mesressources/idMaressouce PUT Mise à jour /monAPI.com/mesressources/idMaressouce DELETE Suppression Utilisation « simple » du protocole HTTP D’une manière générale, il faut privilégier la conception des API en mode ressources … … mais il ne faut pas forcer ce mode de conception lorsque le mode services présente plus d’intérêts. D’une manière générale, il faut privilégier la conception des API en mode ressources … … mais il ne faut pas forcer ce mode de conception lorsque le mode services présente plus d’intérêts.
39. © WAVESTONE 39 DESIGN Le mode services est moins indispensable que ce que l’on peut croire Mode ressources Mode ressources Manipulation d’un objet métier Manipulation d’un objet métier Mode services Mode services Manipulation d’un objet métier Manipulation d’un objet métier /monAPI.com/MesObjetsMetiers/id de l’objet désiré GET /monAPI.com/MesObjetsMetiers POST Lecture Création /monAPI.com/MesObjetsMetiers/id de l’objet désiré PUT Mise à jour /monAPI.com/MesObjetsMetiers/id de l’objet désiré DELETE Suppression /monAPI.com/getMonObjetMetier GET Webservices en lecture /monAPI.com/addMonObjectMetier POST Webservices en écriture /monAPI.com/deleteMonObjectMetier Lancement d’un traitement avec ou sans résultat Lancement d’un traitement avec ou sans résultat /monAPI.com/FaireMonCalcul GET Traitement en lecture /monAPI.com/FaireMonCalcul POST Traitement occasionnant des écritures dans les backends /monAPI.com/updateMonObjectMetier Lancement d’un traitement avec ou sans résultat Lancement d’un traitement avec ou sans résultat /monAPI.com/ResultatDuCalcul GET Traitement en lecture POST Traitement occasionnant des écritures dans les backends /monAPI.com/ResultatDuCalcul POST POST Création Mise à jour Suppression Le mode services ne doit être utilisé que lorsqu’il est indispensable … … et bien souvent il est possible de basculer simplement vers le mode ressources. Le mode services ne doit être utilisé que lorsqu’il est indispensable … … et bien souvent il est possible de basculer simplement vers le mode ressources.
40. © WAVESTONE 40 DESIGN Définir le niveau de granularité des API selon les processus métiers D1 1 fonction métier = 1 transaction = 1 service / ressource d’API Partir des processus métiers pour définir la granularité des API. Plusieurs itérations peuvent s’avérer nécessaires. Cette granularité peut être différente d’une API à une autre, avec le besoin de réaliser une orchestration / composition d’API. 1 fonction métier = 1 transaction = 1 service / ressource d’API Partir des processus métiers pour définir la granularité des API. Plusieurs itérations peuvent s’avérer nécessaires. Cette granularité peut être différente d’une API à une autre, avec le besoin de réaliser une orchestration / composition d’API. WS Modèle de données Modèle de données Client Client Contrat Contrat Besoin métier 1 : la création d’un compte client nécessite la création d’un contrat Orchestration d’API Réécriture d’API Orchestration d’API Réécriture d’API Modèle de données Modèle de données Client Client Contrat Contrat WS 1 WS 2 Besoin métier 2 : la création d’un compte client et la création d’un contrat peuvent se faire d’une manière indépendante ou se faire en même temps WS 3 1 2 Modèle de données Modèle de données Client Client Contrat Contrat WS 1 WS 2 WS 3 1 2 Si les WS 1 et 2 peuvent facilement être redéveloppés et intégrés au WS 3, il est préférable d’opter pour la réécriture d’API plutôt que de l’orchestration, pour éviter d’impacter les WS existants (en termes de performances par ex.). En revanche, si les WS 1 et 2 sont complexes à redévelopper (parce qu’il s’agit de WS SOAP, legacy, écrit dans un langage pas moderne, peu ou pas documentés, etc.), alors il est préférable de les réutiliser et faire de l’orchestration.
41. © WAVESTONE 41 Exposition d’une API REST au format Http-JSON DESIGN Les API sont exposées via une API REST versionnée, avec un niveau de maturité 2. L’usage du niveau 3 peut être envisagé en interne s’il est bien encadré pour éviter les interprétations. Illustration / schéma Niveau 0 Niveau 1 Niveau 2 Niveau 3 Exposition technique du patrimoine existant (approche « services ») Manipulation de ressources (approche « objet ») Publication théorique à l’état de l’art Utilisation de toutes les particularités du protocole HTTP Non retenu : exposition technique du patrimoine existant (traduction protocolaire automatisée, sans effort de conception) Non retenu : requiert (comme la maturité 2) un effort de conception mais sans en offrir le niveau de normalisation Cas d’usage : exposer le SI en ressources REST facilement utilisables par les développeurs d’application Non retenu : car non standard (pas de normalisation de la représentation des liens en JSON notamment) Description / L’exposition des services sous la forme d’une API versionnée et facilement compréhensible par les développeurs est essentielle pour faciliter l’ouverture du SI. / Le standard REST/JSON est à privilégier et le niveau de maturité 2 doit constituer la cible. / L’URI contient la version majeure de l’API. / Le niveau de maturité 0 est déconseillé : son utilisation doit être restreinte à l’exposition en REST de services existants, et ce à destination exclusive d’applications développées par l'organisation. Description / L’exposition des services sous la forme d’une API versionnée et facilement compréhensible par les développeurs est essentielle pour faciliter l’ouverture du SI. / Le standard REST/JSON est à privilégier et le niveau de maturité 2 doit constituer la cible. / L’URI contient la version majeure de l’API. / Le niveau de maturité 0 est déconseillé : son utilisation doit être restreinte à l’exposition en REST de services existants, et ce à destination exclusive d’applications développées par l'organisation. Modèle de maturité de Leonard Richardson Modèle de maturité de Leonard Richardson D2 Le niveau de maturité 3 (l’usage des liens hypermédia par ex.) peut être envisagé uniquement en interne et sous conditions : il est indispensable de documenter et encadrer les pratiques au mieux possible, ces pratiques peuvent être différentes de ce qui se fait chez les partenaires / publiques rendant difficile l’utilisation en externe.
42. © WAVESTONE 42 Utiliser les codes erreur HTTP ⁄ Afin de faciliter le travail des développeurs qui utilisent l’API Utiliser les codes erreur HTTP ⁄ Afin de faciliter le travail des développeurs qui utilisent l’API Principes généraux de design d’API 1/3 DESIGN Garder l’API intuitive, simple et attractive. Ne pas oublier que l’API est à destination d’humains (développeurs) et non de machines. Définition du format des messages ⁄ Préférer JSON plutôt qu’XML ⁄ Supporter plusieurs formats si possible (meilleure compatibilité) Définition du format des messages ⁄ Préférer JSON plutôt qu’XML ⁄ Supporter plusieurs formats si possible (meilleure compatibilité) Codes retour HTTP ⁄ Afin de faciliter le travail des développeurs qui utilisent l’API Codes retour HTTP ⁄ Afin de faciliter le travail des développeurs qui utilisent l’API Stateless ⁄ Pas de cookie, de sessions etc… Stateless ⁄ Pas de cookie, de sessions etc… Granularité moyenne des ressources ⁄ Charger automatiquement certaines sous- ressources dans la réponse ⁄ Masquer la complexité du modèle de données ⁄ Construire l’API pour les développeurs et non par les données user:{ "id" : 12, “Name”: Dupont, adress: { “CP" : 92130, “street" : “avenue d’Issy” }} Granularité moyenne des ressources ⁄ Charger automatiquement certaines sous- ressources dans la réponse ⁄ Masquer la complexité du modèle de données ⁄ Construire l’API pour les développeurs et non par les données user:{ "id" : 12, “Name”: Dupont, adress: { “CP" : 92130, “street" : “avenue d’Issy” }} 400 Documentation de l’API ⁄ Simple et compréhensible (en 15min) ⁄ Résumé des fonctionnalités de l’API avec exemples d’usage ⁄ Liste des ressources qui seront dépréciées dans la prochaine version ⁄ Publique ⁄ Notes de versions Rester flexible ⁄ Façon de passer les paramètres, choisir les formats, case-insensitive … ⁄ L’API doit rester agréable à utiliser Rester flexible ⁄ Façon de passer les paramètres, choisir les formats, case-insensitive … ⁄ L’API doit rester agréable à utiliser D3 Réutilisabilité ⁄ L’API doit être pensée pour être au maximum réutilisable Réutilisabilité ⁄ L’API doit être pensée pour être au maximum réutilisable
43. © WAVESTONE 43 Principes généraux de design d’API 2/3 DESIGN Permettre la surcharge des méthodes HTTP ⁄ Certains clients ne sont autorisés qu’à faire du GET et du POST ⁄ Accepter le paramètre de header X-HTTP- Method-Override pouvant contenir PUT, PATCH ou DELETE ⁄ Uniquement pour POST (GET doit rester « readonly ») Permettre la surcharge des méthodes HTTP ⁄ Certains clients ne sont autorisés qu’à faire du GET et du POST ⁄ Accepter le paramètre de header X-HTTP- Method-Override pouvant contenir PUT, PATCH ou DELETE ⁄ Uniquement pour POST (GET doit rester « readonly ») Le verbe d’action GET ne doit jamais modifier une ressource GET monAPI/users/1 monAPI/users Le verbe d’action GET ne doit jamais modifier une ressource GET monAPI/users/1 monAPI/users Gérer la hiérarchie des ressources ⁄ Si elles existent par elles-mêmes: référence à leurs IDs monAPI/users/1/idvoiture ⁄ Sinon accès à travers une ressource parent monAPI/users/1/voitures/1 Gérer la hiérarchie des ressources ⁄ Si elles existent par elles-mêmes: référence à leurs IDs monAPI/users/1/idvoiture ⁄ Sinon accès à travers une ressource parent monAPI/users/1/voitures/1 Utiliser POST dans le cas ou les actions CRUD ne suffisent pas ⁄ Approche services POST monAPI/monWebserviceComplexe Utiliser POST dans le cas ou les actions CRUD ne suffisent pas ⁄ Approche services POST monAPI/monWebserviceComplexe POST POST Utiliser les verbes d’actions CRUD HTTP ⁄ Lire GET ⁄ créer POST ⁄ Mettre à jour PUT ⁄ Supprimer DELETE Utiliser les verbes d’actions CRUD HTTP ⁄ Lire GET ⁄ créer POST ⁄ Mettre à jour PUT ⁄ Supprimer DELETE Utiliser le pluriel pour une collection GET monAPI/users/1 GET monAPI/users Utiliser le pluriel pour une collection GET monAPI/users/1 GET monAPI/users N’utiliser que des noms ⁄ Pas de verbes POST monAPI/getAllUsers GET monAPI/users N’utiliser que des noms ⁄ Pas de verbes POST monAPI/getAllUsers GET monAPI/users CRUD READONLY Unifier les usages ⁄ Fonctionnement de global de l’API ⁄ Règles de nommage ⁄ Utilisation des paramètres Unifier les usages ⁄ Fonctionnement de global de l’API ⁄ Règles de nommage ⁄ Utilisation des paramètres Headers HTTP pour définir les formats supportés ⁄ Content-Type défini le format demandé par le client ⁄ Accept défini une liste de format de réponse supportés Headers HTTP pour définir les formats supportés ⁄ Content-Type défini le format demandé par le client ⁄ Accept défini une liste de format de réponse supportés D4 Généraliser les conventions de nommage et de fonctionnement pour garder l’API cohérente et intuitive.
44. © WAVESTONE 44 Principes généraux de design d’API 3/3 DESIGN Sélection de champs ⁄ Ne remonter que les champs utiles ⁄ Réduire la volumétrie des échanges GET /users?fields=id,name,age Sélection de champs ⁄ Ne remonter que les champs utiles ⁄ Réduire la volumétrie des échanges GET /users?fields=id,name,age Filtrage ⁄ Filtre sur les données en fonction des champs GET /users?name=dupont Filtrage ⁄ Filtre sur les données en fonction des champs GET /users?name=dupont Limitations de la volumétrie ⁄ X-Rate-Limit-Limit – Nombre de requêtes autorisées durant la période en cours ⁄ X-Rate-Limit-Remaining – Nombre de requêtes restantes dans la période en cours N’utiliser que des secondes avant disponibilité. Les timestamps sont lourds et porteurs d’informations inutiles (date, heure…) ⁄ X-Rate-Limit-Reset – Nombre de secondes restantes pour la période en cours Limitations de la volumétrie ⁄ X-Rate-Limit-Limit – Nombre de requêtes autorisées durant la période en cours ⁄ X-Rate-Limit-Remaining – Nombre de requêtes restantes dans la période en cours N’utiliser que des secondes avant disponibilité. Les timestamps sont lourds et porteurs d’informations inutiles (date, heure…) ⁄ X-Rate-Limit-Reset – Nombre de secondes restantes pour la période en cours Tri ⁄ Tri des données en fonction de critères pertinents GET /users?sort=age Tri ⁄ Tri des données en fonction de critères pertinents GET /users?sort=age Pagination ⁄ Mettre en place une pagination par défaut (ex 0-30) ⁄ Permettre la pagination manuelle GET /users?offset=20&limit=5 Pagination ⁄ Mettre en place une pagination par défaut (ex 0-30) ⁄ Permettre la pagination manuelle GET /users?offset=20&limit=5 Permettre la gestion du cache ⁄ Via le code « 304 – resource not modified » ⁄ Evite de renvoyer inutilement la ressource complète au client Permettre la gestion du cache ⁄ Via le code « 304 – resource not modified » ⁄ Evite de renvoyer inutilement la ressource complète au client Mettre en place des alias pour les requêtes fréquentes ⁄ Facilite l’usage de l’API GET /recently_active_users Mettre en place des alias pour les requêtes fréquentes ⁄ Facilite l’usage de l’API GET /recently_active_users 1..25 1..25 D5 Fournir des fonctions basiques pour optimiser les résultats et ne remonter que ce qui est pertinent pour le client.
45. © WAVESTONE 45 Construction de l’URI DESIGN D6 Normaliser les URI et respecter des règles de constructions transverses à l'organisation. Définition de l’URI ⁄ Ne pas utiliser de verbe mais des noms. Une URI doit être de la forme : Définition de l’URI ⁄ Ne pas utiliser de verbe mais des noms. Une URI doit être de la forme : https://MonOrganisation.fr/accounts/v1/currentAccounts/76873 Domaine et environnement API (Contexte) Version Resource Protocole ID Composants de l’URI ⁄ Protocole : http(s); ⁄ Domaine : nom du domaine de service; ⁄ API (Contexte) : API à laquelle la ressource est reliée; ⁄ Version : la version de l’API (composée de 1 chiffre); ⁄ Resource : Resource (collection); ⁄ ID : Une instance de la ressource. Composants de l’URI ⁄ Protocole : http(s); ⁄ Domaine : nom du domaine de service; ⁄ API (Contexte) : API à laquelle la ressource est reliée; ⁄ Version : la version de l’API (composée de 1 chiffre); ⁄ Resource : Resource (collection); ⁄ ID : Une instance de la ressource. Pourquoi versionner dans l’URI plutôt que dans les headers ? ⁄ Versionner ainsi permet de consommer l’API directement depuis un navigateur. Si on versionne par les headers http, il est impossible de le mentionner dans l’URL pour les redirections ⁄ Versionner dans l’URI permet de générer des liens pour transmettre facilement aux autres interlocuteurs (ex : envoi par mail d’un lien, directement cliquable) ⁄ A titre d’exemple, les acteurs suivants adoptent cette stratégie de versionning : Google, Facebook, LinkedIn, Netflix Pourquoi versionner dans l’URI plutôt que dans les headers ? ⁄ Versionner ainsi permet de consommer l’API directement depuis un navigateur. Si on versionne par les headers http, il est impossible de le mentionner dans l’URL pour les redirections ⁄ Versionner dans l’URI permet de générer des liens pour transmettre facilement aux autres interlocuteurs (ex : envoi par mail d’un lien, directement cliquable) ⁄ A titre d’exemple, les acteurs suivants adoptent cette stratégie de versionning : Google, Facebook, LinkedIn, Netflix Cette méthode n’est pas « RESTful » puisque l’URI devrait être stable. La version est un aspect « technique » alors que le reste de l’URI représente des aspects « fonctionnels ». Cependant cela reste la façon d’implémentation la plus simple et permet la meilleure gestion de flux. Cette méthode n’est pas « RESTful » puisque l’URI devrait être stable. La version est un aspect « technique » alors que le reste de l’URI représente des aspects « fonctionnels ». Cependant cela reste la façon d’implémentation la plus simple et permet la meilleure gestion de flux.
46. © WAVESTONE 46 Règles ⁄ Toutes les actions faites sur une ressource ont été décrites avec un verbe (GET, POST, PUT, DELETE, HEAD, OPTIONS). ⁄ Interface uniforme : toujours utiliser les mêmes méthodes pour la même action sur la ressource. ⁄ Utiliser “PUT” seulement pour une mise à jour totale. ⁄ Les verbes suivant sont basés sur les standards du marché : Règles ⁄ Toutes les actions faites sur une ressource ont été décrites avec un verbe (GET, POST, PUT, DELETE, HEAD, OPTIONS). ⁄ Interface uniforme : toujours utiliser les mêmes méthodes pour la même action sur la ressource. ⁄ Utiliser “PUT” seulement pour une mise à jour totale. ⁄ Les verbes suivant sont basés sur les standards du marché : Usage des verbes HTTP DESIGN Verbe Action autorisée / possible Autorisé GET Consulter une ressource Oui POST Créer une ressource Oui PUT Mettre à jour une ressource (sans création) Oui PATCH Mettre à jour partiellement la ressource Sous condition DELETE Supprimer une Resource Oui TRACE Echo la requête reçue pour qu’un client puisse voir quels changements ou ajouts (s’il y en a eu) ont été faits par des serveurs intermédiaires. Non HEAD Vérifier l’existence d’une ressource sans la récupérer et éventuellement consulter ses metadata. Non OPTIONS Déclarer les verbes disponibles pour une ressource donnée, et donc les actions autorisée sur cette dernière. Oui D7 Cadrer l’usage des verbes HTTP sur les ressources (via URI) pour conserver l’API intuitive.
47. © WAVESTONE 47 DESIGN Comment utiliser PATCH ? PATCH est plus flexible que PUT mais doit être utilisé avec précaution. Point d’attention : PATCH n’est pas idempotent ⁄ Une fonction est idempotente si pour tout input x on a f(f(x)) = f(x). Autrement dit, lancer plusieurs fois la requête a le même résultat que ne la lancer qu’une fois. ⁄ Dans le cas de PATCH, certaines requêtes ne présentent pas cette propriété : Ex : Ressource /users : [{ « id » : 1, « name » : « A »}] Requête PATCH /users [{ « op » : « add », « name » : « B »}] A la première requête, /users devient : [{ « id » : 1, « name » : « A »}, { « id » : 2, « name » : « B »}] Puis : [{ « id » : 1, « name » : « A »}, { « id » : 2, « name » : « B »}, { « id » : 3, « name » : « B »}] ; etc ⁄ Il faut donc être prudent lorsqu’on utilise PATCH pour ajouter des données à une collection. Point d’attention : PATCH n’est pas idempotent ⁄ Une fonction est idempotente si pour tout input x on a f(f(x)) = f(x). Autrement dit, lancer plusieurs fois la requête a le même résultat que ne la lancer qu’une fois. ⁄ Dans le cas de PATCH, certaines requêtes ne présentent pas cette propriété : Ex : Ressource /users : [{ « id » : 1, « name » : « A »}] Requête PATCH /users [{ « op » : « add », « name » : « B »}] A la première requête, /users devient : [{ « id » : 1, « name » : « A »}, { « id » : 2, « name » : « B »}] Puis : [{ « id » : 1, « name » : « A »}, { « id » : 2, « name » : « B »}, { « id » : 3, « name » : « B »}] ; etc ⁄ Il faut donc être prudent lorsqu’on utilise PATCH pour ajouter des données à une collection. Usage correct de PATCH : ⁄ Une requête PATCH se structure comme suit : PATCH /ressource [description des modifications à apporter] Ex : PATCH /users/123 [{ "op": "replace", "path": "/email", "value": "new.email@example.org" }] ⁄ Une API implémentant la méthode PATCH doit faire uniquement des modifications atomiques. Cela signifie que si une erreur survient lors de l’application du PATCH, une requête GET ne doit pas pouvoir retourner la ressource partiellement modifiée. (ex : si l’on effectue un « add » et un « replace », et que le « replace » produit une erreur, le « add » ne doit pas être effectué non plus) A noter : Dans le cas d’un JSON Patch Document, la RFC 5789 précise que la méthode HTTP PATCH est atomique : Toute erreur dans l’exécution de la méthode PATCH implique directement que le document est retourné sans aucune modification Usage correct de PATCH : ⁄ Une requête PATCH se structure comme suit : PATCH /ressource [description des modifications à apporter] Ex : PATCH /users/123 [{ "op": "replace", "path": "/email", "value": "new.email@example.org" }] ⁄ Une API implémentant la méthode PATCH doit faire uniquement des modifications atomiques. Cela signifie que si une erreur survient lors de l’application du PATCH, une requête GET ne doit pas pouvoir retourner la ressource partiellement modifiée. (ex : si l’on effectue un « add » et un « replace », et que le « replace » produit une erreur, le « add » ne doit pas être effectué non plus) A noter : Dans le cas d’un JSON Patch Document, la RFC 5789 précise que la méthode HTTP PATCH est atomique : Toute erreur dans l’exécution de la méthode PATCH implique directement que le document est retourné sans aucune modification
48. © WAVESTONE 48 Gestion des erreurs DESIGN Exemples de messages d’erreur JSON HTTP/1.1 400 Bad Request Content-Type: Application/json { "error_messages": { " errors_list": [ { "short_lib": " Higher than the maximum amounts", "long_lib: "Payments higher than the maximum amounts of 2000€", "error_code": "E9854120", "error_value_list": [“operation_amount"] }, { "short_lib": “Insufficient balance", "long_lib: “The account has insufficient funds to execute the payment", "error_code": "E9854121", "error_value_list":[“account_balance"] } ] } } HTTP/1.1 500 Server Error { “error_code": "UOM35268CD500230", "lib" : "Data Base Host unavailable" } Liste des principaux codes HTTP / 200 – OK – Tout fonctionne. / 201 – OK – Une nouvelle ressource a été créée. / 204 – OK – Confirmation de la suppression de la ressource. / 304 – Non modifié – Le client peut utiliser les données dans le cache. / 400 – Mauvaise requête – La requête était invalide ou ne peut pas aboutir. L’erreur exacte devrait être expliquée dans le corps de l’erreur. Ex « Le JSON n’est pas valide ». / 401 – Non autorisé – La requête nécessite l’authentification de l’utilisateur. / 403 – Non autorisé – Le serveur a compris la requête mais la refuse ou l’accès n’est pas autorisé. / 404 – Non trouvée – Il n’y a pas de ressource à l’URI donnée. / 422 – Entité non traitable – Doit être utilisée si le serveur ne peut pas traiter l’entité. Ex : Si une image ne peut pas être formatée ou si des champs obligatoires sont manquants dans le payload. / 500 – Erreur interne du serveur – Les développeurs d’API doivent éviter d’afficher ouvertement le motif de cette erreur. Lorsqu’elle se produit, elle doit être catchée, sa stacktrace, loguée et ne pas être retournée en l’état au consommateur pour des raisons de sécurité, mais aussi d’image. Retourner l’erreur 500 sans stacktrace, avec un message générique. Liste des principaux codes HTTP / 200 – OK – Tout fonctionne. / 201 – OK – Une nouvelle ressource a été créée. / 204 – OK – Confirmation de la suppression de la ressource. / 304 – Non modifié – Le client peut utiliser les données dans le cache. / 400 – Mauvaise requête – La requête était invalide ou ne peut pas aboutir. L’erreur exacte devrait être expliquée dans le corps de l’erreur. Ex « Le JSON n’est pas valide ». / 401 – Non autorisé – La requête nécessite l’authentification de l’utilisateur. / 403 – Non autorisé – Le serveur a compris la requête mais la refuse ou l’accès n’est pas autorisé. / 404 – Non trouvée – Il n’y a pas de ressource à l’URI donnée. / 422 – Entité non traitable – Doit être utilisée si le serveur ne peut pas traiter l’entité. Ex : Si une image ne peut pas être formatée ou si des champs obligatoires sont manquants dans le payload. / 500 – Erreur interne du serveur – Les développeurs d’API doivent éviter d’afficher ouvertement le motif de cette erreur. Lorsqu’elle se produit, elle doit être catchée, sa stacktrace, loguée et ne pas être retournée en l’état au consommateur pour des raisons de sécurité, mais aussi d’image. Retourner l’erreur 500 sans stacktrace, avec un message générique. Erreur technique ⁄ Les erreurs techniques peuvent être dues au client ou au serveur ⁄ Une erreur client est associée au code d’erreur 40x ⁄ Une erreur serveur est associée au code d’erreur 50x ⁄ Les erreurs techniques peuvent retourner des message dans le corps Erreur technique ⁄ Les erreurs techniques peuvent être dues au client ou au serveur ⁄ Une erreur client est associée au code d’erreur 40x ⁄ Une erreur serveur est associée au code d’erreur 50x ⁄ Les erreurs techniques peuvent retourner des message dans le corps Corps du message ⁄ Le corps de la réponse contient un objet qui décrit une ou plusieurs erreurs JSON : ⁄ Code (voir code de réponse http). ⁄ Tables d’erreurs incluant : ⁄ Une petite description. ⁄ Une description complète (compréhensible par l’utilisateur). ⁄ Une URI vers une description détaillée de l’erreur, avec l’action corrective et un contact. ⁄ Une liste des propriétés produisant l’erreur Corps du message ⁄ Le corps de la réponse contient un objet qui décrit une ou plusieurs erreurs JSON : ⁄ Code (voir code de réponse http). ⁄ Tables d’erreurs incluant : ⁄ Une petite description. ⁄ Une description complète (compréhensible par l’utilisateur). ⁄ Une URI vers une description détaillée de l’erreur, avec l’action corrective et un contact. ⁄ Une liste des propriétés produisant l’erreur D8 S’appuyer sur les codes retour HTTP standards.
49. © WAVESTONE 49 Résumé des recommandations de design DESIGN Fournir des fonctions basiques Fournir des fonctions basiques pour optimiser les résultats et ne remonter que ce qui est pertinent pour le client. D5 Choisir la bonne granularité d’API 1 fonction métier = 1 transaction = 1 service / 1 API. D1 Garder l’API intuitive, simple et attractive Ne pas oublier que l’API est à destination d’humains (développeurs) et non de machines. D3 Généraliser des conventions Généraliser les conventions de nommage et de fonctionnement pour garder l’API cohérente et intuitive. D4 Cadrer l’usage des verbes HTTP Cadrer l’usage des verbes HTTP sur les ressources (via URI) pour conserver l’API intuitive. D7 Utiliser les erreurs standard HTTP S’appuyer sur les codes retour HTTP standards. D8 Normaliser les URIs Normaliser les URIs et respecter des règles de constructions transverses à l'organisation. D6 Privilégier le niveau 2 de maturité REST Utilisation standard des différents verbes http pour interagir avec les ressources. Le niveau 3 (liens hypermédia, …) est envisageable sous conditions, en interne. D2
50. Sécurité /3
51. © WAVESTONE 51 SÉCURITÉ Les risques identifiés ne sont pas spécifiques aux APIs L’exposition de données via des APIs n’induit pas de risques fondamentalement différents des autres moyens d’exposition de donnée. Seule la nature de la surface d’attaque est modifiée. Indisponibilité des APIs exposées (ex : saturées) ; les SLA ne sont donc pas respectées Perte d’intégrité des données exposées par des APIs (ex : intrusion sur le SI de l'organisation) Vol des données par des personnes malveillantes depuis le SI de cette tierce partie R5 R2 R4 Vol de données exposées par des APIs depuis le SI de l'organisation Divulgation intentionnelle des données par cette tierce partie R1 R3 L'organisation expose des données par une API à des partenaires/au public. Une de ces tierces parties légitime récupère ces données.
52. © WAVESTONE 52 Quelles mesures de mitigation mettre en place ? SÉCURITÉ Sécurité des données : chiffrement, authentification, recommandations OWASP… M2 M3 M1 Les mesures de mitigation que l’on peut employer sont également similaires à ceux que l’on peut trouver vis-à-vis d’autres moyens d’exposition de données. Dimensionnement des équipements et de l’offre de service, throttling… M4 Sécuriser les APIs comme les autres applications web, tant au niveau des APIs que de l’API Manager Respecter la stratégie d’ouverture des données de l'organisation et gérer les risques résiduels Publiques : implémenter OAuth2 pour que les usagers maitrisent leurs données et inverser la responsabilité Partenaires : ne leur exposer que les données auxquelles ils ont droit, et prévoir un Plan Assurance Qualité pour couvrir les risques
53. © WAVESTONE 53 SÉCURITÉ Réaliser une analyse de risques avant la création de chaque API Type d’API R1 R2 R3 R4 R5 Interne/privée N/A N/A M3 M4 M3 Partenaires connus M1 M1 M3 M4 M3 Publique authentifiée M2 M2 M3 M4 M3 Publique non- authentifiée N/A N/A N/A M4 M3 Les typologies de mesures dépendent du type d’API et des risques à couvrir, mais le niveau de protection à atteindre pour chaque mesure dépend de la criticité des données à exposer, et de l’impact associé. Les mesures de sécurité doivent être déterminées dès la conception à travers une analyse de risques. APIs destinées à être consommées uniquement par des applications internes APIs destinée à être consommée par des partenaires identifiés (avec contractualisation) API destinée au public, exposant des données nécessitant une authentification de l’utilisateur API destinée au public et n’exposant que des données publiques : le vol n’est donc pas un risque C’est le niveau de criticité des données exposées qui conditionne la sévérité de ces mesures : ⁄ Le niveau d’authentification requis (mise en place d’authentification forte pour les données sensibles) ⁄ La mise en place de tests d’intrusion réguliers sur le SI du partenaire à qui des données vont être exposées, et leur fréquence S1
54. © WAVESTONE 54 SÉCURITÉ Contractualiser des Plans Assurance Sécurité avec les partenaires Gestion des données ⁄ Etablir les exigences en terme de confidentialité des données, partitionnement, suppression, redondance … ⁄ Exiger l’intégration suffisante des problématiques sécurité dès la conception des projets utilisant les données exposées par API (analyses de risques …) Gestion des données ⁄ Etablir les exigences en terme de confidentialité des données, partitionnement, suppression, redondance … ⁄ Exiger l’intégration suffisante des problématiques sécurité dès la conception des projets utilisant les données exposées par API (analyses de risques …) Conduite d’audits chez le partenaire ⁄ Obtenir l’autorisation de mener des audits de sécurité, de conformité au PAS, etc.. ⁄ Exiger que le partenaire mène de lui- même des audits réguliers et en transmette les résultats à l'organisation ⁄ Etablir des SLA pour la remédiation des anomalies détectées en audit Conduite d’audits chez le partenaire ⁄ Obtenir l’autorisation de mener des audits de sécurité, de conformité au PAS, etc.. ⁄ Exiger que le partenaire mène de lui- même des audits réguliers et en transmette les résultats à l'organisation ⁄ Etablir des SLA pour la remédiation des anomalies détectées en audit Organisation ⁄ Définir les qualifications exigées (ex : une structure de gestion de crise certifiée ISO 27035) ⁄ Exiger la signature d’une clause de confidentialité par tout employé ou sous- traitant du partenaire amené à travailler sur le périmètre du service ⁄ Faire garantir par le partenaire le maintien à jour de ses différentes briques d’infrastructure et logicielles Organisation ⁄ Définir les qualifications exigées (ex : une structure de gestion de crise certifiée ISO 27035) ⁄ Exiger la signature d’une clause de confidentialité par tout employé ou sous- traitant du partenaire amené à travailler sur le périmètre du service ⁄ Faire garantir par le partenaire le maintien à jour de ses différentes briques d’infrastructure et logicielles Le PAS peut aborder tout ou partie des thématiques ci-dessous, en fonction notamment du niveau de criticité des données échangées, du type de partenaire et la nature de la relation. Hébergement des données et services ⁄ Demander au partenaire les localisations des datacenters dans lesquels peuvent être stockées les données, et des lieux où ces données peuvent être présentes ⁄ Obliger le partenaire à informer l'organisation dans le cas où il serait soumis à des lois de type « Patriot Act » Hébergement des données et services ⁄ Demander au partenaire les localisations des datacenters dans lesquels peuvent être stockées les données, et des lieux où ces données peuvent être présentes ⁄ Obliger le partenaire à informer l'organisation dans le cas où il serait soumis à des lois de type « Patriot Act » Conformité au cadre légal en vigueur ⁄ S’assurer que le partenaire respecte l’ensemble des textes et exigences liés à l’activité en question (GDPR, LPM, LIL …) ⁄ Charger le partenaire d’effectuer une veille pour identifier les impacts de nouveaux textes sur le service Conformité au cadre légal en vigueur ⁄ S’assurer que le partenaire respecte l’ensemble des textes et exigences liés à l’activité en question (GDPR, LPM, LIL …) ⁄ Charger le partenaire d’effectuer une veille pour identifier les impacts de nouveaux textes sur le service Politiques de l'organisation ⁄ Exiger du partenaire de se conformer à la PSSI de l'organisation Politiques de l'organisation ⁄ Exiger du partenaire de se conformer à la PSSI de l'organisation Modalités de sous-traitance ⁄ Exiger du partenaire d’obtenir l’accord de l'oganisation pour partager les données avec d’éventuels sous-traitants Modalités de sous-traitance ⁄ Exiger du partenaire d’obtenir l’accord de l'oganisation pour partager les données avec d’éventuels sous-traitants Gestion des accès ⁄ Garantir que l’IAM du partenaire permet d’avoir un minimum de traçabilité sur les accès aux données échangées (comptes nominatifs, pas de comptes génériques, gestion des comptes à privilèges, …) Gestion des accès ⁄ Garantir que l’IAM du partenaire permet d’avoir un minimum de traçabilité sur les accès aux données échangées (comptes nominatifs, pas de comptes génériques, gestion des comptes à privilèges, …) Modalités de désengagement ⁄ Préciser le processus de désengagement (suppression des données récupérées par API, …) Modalités de désengagement ⁄ Préciser le processus de désengagement (suppression des données récupérées par API, …) S2
55. © WAVESTONE 55 SÉCURITÉ Appliquer les mêmes mesures de sécurité que les applications web Les « zones » à risques Gestion des sessions Authentification & Maintien de session Côté client vs côté serveur Identifiant de sessions non devinables Ré-authentifier pour des actions critiques Contrôle d’accès Gestion des profils & privilèges Situation de concurrence Séparation des espaces utilisateurs Gestion des entrées/sorties Traitement des entrées Accès aux ressources et traitement Injection de données côté client Encoder les données avant réponse Données sensibles Séparation des environnements Stockage et gestion des secrets Faire usage de mécanismes de sécurité éprouvés Gestion des exceptions Gestion des erreurs Journalisation Intercepter toutes les erreurs et les traiter Gestion de la mémoire Allocation de la mémoire Initialisation des objets et des variables Supervision consommation mémoire 1 2 6 3 5 4 Une API est une application web comme les autres, elle doit donc être sécurisée en temps que telle : chiffrement de flux, protection contre le vol de session ou de cookies, protection contre l’injection de code… S3 Comme n’importe quelle application, les APIs peuvent également être intégrées à une solution de détection d’intrusion, type SIEM dans le cadre d’un dispositif SOC, et être sujettes à des tests d’intrusions.
56. © WAVESTONE 56 SÉCURITÉ Exemples des bonnes pratiques de développement Désérialiser les données JSON contrôlées par l’utilisateur ⁄ Ne pas utiliser les valeurs directement (ex : éviter .innerHTML) document.getElementById("adresse").innerHTML = JSON.parse(data) ["address"]; ⁄ Préférer les fonctions .value, .innerText ou .textContent document.getElementById("adresse").value= JSON.parse(data) ["address"]; Désérialiser les données JSON contrôlées par l’utilisateur ⁄ Ne pas utiliser les valeurs directement (ex : éviter .innerHTML) document.getElementById("adresse").innerHTML = JSON.parse(data) ["address"]; ⁄ Préférer les fonctions .value, .innerText ou .textContent document.getElementById("adresse").value= JSON.parse(data) ["address"]; Contrôler les origines des requêtes dans le cadre du Cross Origin Ressource Sharing (CORS) ⁄ Le serveur requêté récupère la valeur de l’entête Origin de la requête et vérifie sa présence dans sa whitelist ⁄ Si l’origine de la requête est de confiance, la whitelist est renvoyée via l’entête Acces-Control-Allow-Origin ⁄ Sinon renvoyer un code http différent de 2XX Contrôler les origines des requêtes dans le cadre du Cross Origin Ressource Sharing (CORS) ⁄ Le serveur requêté récupère la valeur de l’entête Origin de la requête et vérifie sa présence dans sa whitelist ⁄ Si l’origine de la requête est de confiance, la whitelist est renvoyée via l’entête Acces-Control-Allow-Origin ⁄ Sinon renvoyer un code http différent de 2XX Limiter les contenus accessibles aux navigateurs ⁄ Utiliser l’entête Content-Security-Policy (CSP) Content-Security-Policy: default-src 'self'; upgrade-insecure-requests Par défaut les contenus ne peuvent provenir que du domaine de la page. Le navigateur corrige, à l’envoi des requêtes, les url http en https ⁄ Le paramétrage peut être assoupli pour permettre le téléchargement de contenu depuis des sources de confiance Content-Security-Policy: default-src 'self'; img-src https://agriculture.gouv.fr; upgrade-insecure-requests Limiter les contenus accessibles aux navigateurs ⁄ Utiliser l’entête Content-Security-Policy (CSP) Content-Security-Policy: default-src 'self'; upgrade-insecure-requests Par défaut les contenus ne peuvent provenir que du domaine de la page. Le navigateur corrige, à l’envoi des requêtes, les url http en https ⁄ Le paramétrage peut être assoupli pour permettre le téléchargement de contenu depuis des sources de confiance Content-Security-Policy: default-src 'self'; img-src https://agriculture.gouv.fr; upgrade-insecure-requests Maitrîser le type de contenu échangé ⁄ Toujours positionner l’entête Content-Type dans les requêtes comme dans les réponses ⁄ Le serveur doit : ⁄ Matcher le contenu envoyé avec l’entête Content-Type ⁄ Utiliser les entêtes X-Content-Type: nosniff et X-Frame- Options: deny pour protéger les navigateurs anciens Maitrîser le type de contenu échangé ⁄ Toujours positionner l’entête Content-Type dans les requêtes comme dans les réponses ⁄ Le serveur doit : ⁄ Matcher le contenu envoyé avec l’entête Content-Type ⁄ Utiliser les entêtes X-Content-Type: nosniff et X-Frame- Options: deny pour protéger les navigateurs anciens Respecter les recommandations usuelles de la sécurité web ⁄ Suivre par exemple les recommandations d’OWASP Respecter les recommandations usuelles de la sécurité web ⁄ Suivre par exemple les recommandations d’OWASP Utiliser les méthodes standard pour se prémunir d’attaques classiques (ex : XSS).
57. © WAVESTONE 57 SÉCURITÉ Chiffrer et signer les données selon leur criticité S4 - Sensibilité et criticité de la donnée à exposer + Chiffrement TLS 1.2 Chiffrer systématiquement l’ensemble des flux (niveau couche 4 et 5 OSI) Chiffrement applicatif Au niveau de l’API / backend, quand la confidentialité de la donnée le justifie Signature applicative Au niveau de l’API / backend, quand le niveau de preuve nécessaire le justifie Signature HTTP Signer et authentifier les messages HTTP si nécessaire (niveau couche 7 OSI) JSON Web Signature Permet de signer les données JSON techniques ou métiers au niveau de l’API Gateway JSON Web Encryption Permet de chiffrer les données JSON techniques ou métiers au niveau de l’API Gateway Quant à la traçabilité des accès aux API, elle doit être gérée au niveau des API Gateway et/ou les APIs elles-mêmes. Le niveau de traçabilité doit être fonction des risques et des besoins métiers. A priori, TYK sait faire du JWS (JSON Web Signature) mais pas du JWE (JSON Web Encryption). En attentant une évolution du produit, il peut s’avérer nécessaire de basculer sur un chiffrement côté backend pour protéger les données sensibles. L’analyse de risques à réaliser avant la création de chaque nouvelle API, doit permettre d’identifier les mesures de protections à mettre en œuvre selon la sensibilité et criticité des données à exposer.
58. © WAVESTONE 58 Prévoir le support d’OAuth2 et OpenID Connect SÉCURITÉ OAuth2.0 / Protocole de délégation d’accès : un client applicatif consomme une ressource (API) « au nom de » l’utilisateur. / L’access token est la « clé » permettant d’accéder à la ressource. OpenID Connect / Protocole d’authentification : une application délègue l’authentification à un serveur OIDC / Permet de délivrer un jeton d’identité (ID token), autoporteur et signé par le serveur d’autorisation / Le jeton contient des attributs utilisateurs et des informations sur l’authentification effectuée (niveau, timestamp, etc.) OAuth2.0 / Protocole de délégation d’accès : un client applicatif consomme une ressource (API) « au nom de » l’utilisateur. / L’access token est la « clé » permettant d’accéder à la ressource. OpenID Connect / Protocole d’authentification : une application délègue l’authentification à un serveur OIDC / Permet de délivrer un jeton d’identité (ID token), autoporteur et signé par le serveur d’autorisation / Le jeton contient des attributs utilisateurs et des informations sur l’authentification effectuée (niveau, timestamp, etc.) OAuth2 est le protocole de délégation d’autorisation de référence. Il permet de restreindre l’accès aux APIs aux seuls utilisateurs qui en ont légitimement besoin, via des clients pas forcément maitrisés. OpenID Connect offre une normalisation de la fourniture des services d’authentification et de SSO. Get token Use token Token exchange Client Serveur d’Autorisation API Tous types de consommateurs - app mobile, serveur, objet connecté, etc. - maîtrisé ou tierce partie Access token API ID token Les tokens peuvent être : - Opaques nécessitant une validation auprès du serveur d’autorisation - Autoporteurs des informations de validité S5
59. © WAVESTONE 59 SÉCURITÉ Quel intérêt pour de déployer OAuth2 ? Si les usages actuels ne nécessitent le déploiement immédiat d’OAuth2, ceci peut devenir nécessaire pour accompagner la stratégie d’ouverture de la donnée à l’avenir, et respecter l’esprit de la stratégie Etat Plateforme. Permettre la délégation des accès à des tiers « Faciliter la circulation de la donnée […] et permettre à l’usager la maîtrise des données échangées quand il s’agit d’informations confidentielles (notamment personnelles), ce qui impose de disposer d’un mécanisme d’identification des usagers, [et] compléter si nécessaire d’un système d’authentification, pour faciliter également la circulation de ces données au-delà de la sphère publique sous le contrôle de l’usager tout en évitant une exploitation illégitime. » Partager un standard avec France Connect « Il convient de simplifier la vie des usagers de manière à ce qu’ils puissent s’identifier et s’authentifier quand cela est nécessaire, sur la base d’un mécanisme de fédération d’identité – France Connect - reconnu par tous les acteurs de l’Etat plateforme. » Utiliser le standard majoritaire du marché « [Faire] rapidement des choix communs, incontestables et s’imposant naturellement à tous : […] standards du Web éprouvés par ailleurs » Source : http://references.modernisation.gouv.fr/sites/default/files/Pr%C3%A9sentation%20G%C3%A9n%C3%A9rale %20Strat%C3%A9gie%20Plateforme%20v422%20Compl%C3%A8te.pdf
60. © WAVESTONE 60 SÉCURITÉ Terminologie OAuth2 Le client désigne l’application cliente de l’API, consommatrice de l’API. Il existe 3 formes de consommation d’une API : / La consommation par une application exécutée côté serveur / La consommation par une application native exécutée sur un mobile ou un poste de travail / La consommation par une application exécutée côté client (ou application user agent) Client Il s’agit du consommateur final de l’API (derrière le client) lorsqu’il s’agit d’un utilisateur. L’utilisateur est appelé Ressource Owner dans OAuth2 et End User dans OpenID Connect. Utilisateur Ce serveur permet d’authentifier les utilisateurs de l’API, il peut être inclus dans le serveur d’autorisation. Serveur d'authentification Ce serveur permet de déterminer le niveau d’habilitation d’un utilisateur, à travers la délivrance d’un jeton par exemple. Ce niveau d’habilitation est ensuite contrôlé par l’API pour déterminer plus finement les droits d’accès aux ressources. Serveur d’autorisation (AS)
61. © WAVESTONE 61 SÉCURITÉ OAuth2 définit 4 modes opératoires pour gérer les autorisations C’est l’implémentation privilégiée, utilisée à partir du moment où l’application possède une partie serveur ⁄ L’utilisateur autorise le client à accéder aux données en s’identifiant ⁄ Le serveur d’autorisation (AS) délivre un code d’autorisation au client ⁄ L’application (serveur) peut échanger ce code contre un jeton d’accès auprès de l’AS Authorization Code Grant Implémentation qui devient nécessaire quand le client ne peut pas porter un secret (applications javascript, sites web à page unique) ⁄ L’utilisateur autorise l’accès aux données ⁄ L’AS délivre directement au client le jeton d’accès Implicit Grant Implémentation qui revient à une autorisation entre serveurs. Le cas d’usage est le cas où le client est également Resource Owner (ex : un site qui stocke ses fichiers dans un Cloud Google et souhaite les modifier, et doit donc demander l’accès à l’API Google) ⁄ Le serveur d’application s’authentifie directement auprès de l’AS, qui lui délivre le jeton d’accès ⁄ Il n’y a pas de notion d’utilisateur final Client Credentials Grant Implémentation qui implique une relation de confiance forte entre le client et l’AS. (par exemple quand le client et l’AS sont gérés par la même autorité) ⁄ L’utilisateur autorise l’accès aux données ⁄ Les identifiants de l’utilisateurs sont directement envoyés à l’AS, à travers le client, qui délivre le jeton d’accès à l’application (côté serveur) Resource Owner Password Credentials Grant Les cinématiques sont détaillées en annexes ATTENTION : Cette méthode est à éviter car pose des problèmes de sécurité, le jeton d’accès étant délivré côté client. Ex : Une tierce partie malveillante peut créer un client utilisant également l’implicit grant, et récupérer ainsi le jeton d’accès, pour l’utiliser au nom de l’utilisateur
62. © WAVESTONE 62 SÉCURITÉ Dans quel cas utiliser chaque mode opératoire d’OAuth2 ? Qui consomme l’API ? Type de client ? Client maîtrisé par l'organisati on ? Client maîtrisé par l'organisati on ? Cas d’usage 2 Cas d’usage 3 Cas d’usage 4 Cas d’usage 5 Cas d’usage 6 Utilisateur App native ou desktop App côté client (user agent) App côté serveur Oui Oui Non Non Cas d’usage 1 Machine Client Credentials Grant ROPC grant Implicit code grant ROPC grant Authorization code grant Authorization code grant
63. © WAVESTONE 63 Le marché des solutions d’Access Management compatibles OAuth2 Forgerock est aujourd’hui le produit d’access management le plus déployé chez nos clients (Société Générale, AXA, Gras Savoye, etc.). La solution est modulaire (ajout de connecteur d’authentification, customisation des tokens) et fortement scalable. La partie Identity Management est aussi robuste. La solution est uniquement disponible On-premises. Son positionnement tarifaire est élevé. Forgerock est aujourd’hui le produit d’access management le plus déployé chez nos clients (Société Générale, AXA, Gras Savoye, etc.). La solution est modulaire (ajout de connecteur d’authentification, customisation des tokens) et fortement scalable. La partie Identity Management est aussi robuste. La solution est uniquement disponible On-premises. Son positionnement tarifaire est élevé. Solution opensource supportée et développée par RedHat. Elle s’intègre nativement avec plusieurs modules d’authentification / annuaires. La solution est utilisée par exemple chez Banque de France, et nous constatons plusieurs déploiement en cours. Les fonctionnalités sont moins riches que CAS par exemple, mais les retours sont positifs sur les fonctionnalités couvertes de la dernière version. Solution opensource supportée et développée par RedHat. Elle s’intègre nativement avec plusieurs modules d’authentification / annuaires. La solution est utilisée par exemple chez Banque de France, et nous constatons plusieurs déploiement en cours. Les fonctionnalités sont moins riches que CAS par exemple, mais les retours sont positifs sur les fonctionnalités couvertes de la dernière version. Ping Identity est un acteur reconnu du marché de l’IAM, notamment sur la partie fédération. Une offre on-premise est disponible, mais l’orientation de l’éditeur est portée vers le cloud, il faudra être vigilant sur la différence de niveau d’offre entre les deux solutions. Il est présent chez Alstom par exemple. Ping Identity est un acteur reconnu du marché de l’IAM, notamment sur la partie fédération. Une offre on-premise est disponible, mais l’orientation de l’éditeur est portée vers le cloud, il faudra être vigilant sur la différence de niveau d’offre entre les deux solutions. Il est présent chez Alstom par exemple. OAuth2 supporté à partir de la version 5.x (sauf le client credentials grant). Bonne solution opensource d’Access Management, dont la communauté de développeurs est très active, elle ne sait cependant pas faire d’Identity Management. La version 5.x est encore peu déployée chez nos clients, mais les autres versions (3.x et 4.x) sont très répandues. OAuth2 supporté à partir de la version 5.x (sauf le client credentials grant). Bonne solution opensource d’Access Management, dont la communauté de développeurs est très active, elle ne sait cependant pas faire d’Identity Management. La version 5.x est encore peu déployée chez nos clients, mais les autres versions (3.x et 4.x) sont très répandues. Aujourd’hui, la plupart des solutions d’Access Management sont compatibles OAuth2 (au moins sur le papier, certaines implémentations laissant à désirer. ARCHITECTURE
64. © WAVESTONE 64 SÉCURITÉ Comment implémenter OAuth2 en lien avec son SSO ? Selon que le serveur SSO de l'organisation est compatible OAuth2 ou non, il existe 2 familles de solutions d’architecture pour supporter OAuth2. Solution 1 : prévoir le support d’OAuth2 dans le SSO Solution 2 : mettre en place un second serveur d’autorisations en proxy entre le serveur SSO de l'organisation et les API et leurs clients, pour transformer les tokens (CAS par exemple) en tokens OAuth2 Get token Use token Token exchange SSO compatible OAuth2 API Access token ID token Client Get token Use token Token exchange AS compatible OAuth2 API Access token ID token Client SSO « CAS » non compatible OAuth2 Délivrance d’un token CAS Transformation du token CAS en token OAuth2
65. © WAVESTONE 65 SÉCURITÉ Comment TYK supporte-t-il OAuth2 ? La documentation de TYK est peu claire sur le support d’OAuth2, il est nécessaire de tester le produit pour connaitre le niveau du respect des RFC OAuth2 et les modes opératoires / architectures supportées. Compatibilité avec les serveurs d’autorisations en mode OAuth2 ⁄ TYK indique intégrer les workflows standards OAuth2, mais aucune garantie / explication n’est donnée. Plusieurs questions à se poser ⁄ Quels modes opératoires OAuth2 TYK supporte-t-il ? ⁄ TYK sait-il valider les jetons et identifier les clients ? Ou bien délègue-t-il ces opérations aux API ? ⁄ Quels types de jetons sont-ils supportés ? Opaques ? Autoporteurs ? Les deux ? ⁄ Quels sont les serveurs d’autorisations compatibles ? En particulier si les jetons opaques sont supportés. Source : https://tyk.io/docs/security/your-apis/oauth-2-0/ Fonctionnement en mode « serveur d’autorisation » compatible OAuth2 ⁄ TYK indique pouvoir agir comme serveur d’autorisation et délivrer lui-même des jetons OAuth2, mais difficile d’évaluer le niveau du respect des RFC (6749, 6750, 7636 et 7662). Plusieurs questions à se poser ⁄ Quels modes opératoires OAuth2 TYK supporte-t-il ? Seul le mode « client credentials » semble être supporté d’une manière standard, les modes avec utilisateurs ne le semblent pas. ⁄ A quel niveau sont gérées l’authentification et autorisation des utilisateurs ? TYK ou les API ? TYK semble « simuler » ces opérations mais les déléguer aux API, est-ce bien le cas ?
66. © WAVESTONE 66 Cadrer les besoins additionnels et limiter les solutions « fait-maison » SÉCURITÉ Navigation sans couture entre application natives mobiles et vers ou depuis le navigateur du terminal Single Sign-On Mobile Authentification contextuelle Propagation de l’identité Protection contre le vol de jeton Ajustement du niveau d’authentification en fonction de la sensibilité de l’API consommée Transmission de l’identité de l’utilisateur aux APIs backend et validation de la chaîne d’appels Rendre inopérant le vol d’un jeton de sécurité et ne pas dépendre de la sécurité d’un terminal non maîtrisé ou d’un tiers Exemples de besoins légitimes souvent rencontrés, traités par des sous-standards, du plus mature au plus expérimental, à utiliser avec parcimonie, et surtout en évitant les solutions « fait-maison »… L’explosion des besoins conduits souvent à mettre en place des développements très spécifiques qui sont pourtant à proscrire pour conserver cohérence et interopérabilité. SDK AppAuth pour Android et iOS et utilisation des composants CustomTabs (Android) et BrowserView (iOS) pour OAuth2 Authorization Code Flow Utilisation des Levels Of Assurance décrits dans le standard OAuth2 Utilisation du grant type token Exchange décrit dans le standard OAuth2 (en développement) Utilisation de la cinématique « token binding » définie dans le standard OAuth2 (en développement) S6
67. © WAVESTONE 67 Illustration / schéma API API Manager Focus sur l’authentification graduelle PRINCIPES DE SÉCURITÉ Sécurité Authent. forte Médiation Vérification JWT Auth. forte Vérification JWT Service 1 Ressource 1 Service 2 Confirmation identité Serveur d’identité Description ⁄ A chaque appel de service, l’API contrôle si le niveau d’authentification est suffisant pour accéder au service invoqué. ⁄ En fonction du niveau d’authentification de son jeton OpenIDConnect et de la ressource demandée, le client pourra être amené à se ré- authentifier avec le mécanisme adapté (ex: OTP). ⁄ L’authentification forte sera obligatoire pour les ressources d’un niveau de confidentialité élevé. Description ⁄ A chaque appel de service, l’API contrôle si le niveau d’authentification est suffisant pour accéder au service invoqué. ⁄ En fonction du niveau d’authentification de son jeton OpenIDConnect et de la ressource demandée, le client pourra être amené à se ré- authentifier avec le mécanisme adapté (ex: OTP). ⁄ L’authentification forte sera obligatoire pour les ressources d’un niveau de confidentialité élevé. App. mobiles Portail Client La mise en œuvre de l’authentification graduelle permet d’envisager la gestion de droits d’accès très fin au sein des applications, au-delà de ce que permettent les scopes OAuth2.
68. © WAVESTONE 68 Résumé des recommandations de sécurité SÉCURITÉ Prévoir des Plans Assurance Sécurité Contractualiser des Plans Assurance Sécurité avec les partenaires pour maitriser les risques S2 Appliquer les pratiques usuelles de sécurité Une API est une application Web. Les recommandation de sécurité habituelles s’appliquent donc. S3 Prévoir le déploiement d’OAuth2 Mettre en place OAuth2 comme standard de délégation d’accès pour anticiper les nouveaux cas d’usage liés à la stratégie d’ouverture des données S5 Eviter au maximum les développements spécifiques Rester aussi proche que possible des standards afin de conserver la cohérence et l’interopérabilité S6 Chiffrer et signer les données selon leur criticité S4 Réaliser une analyse de risques Avant chaque création d’API, effectuer une analyse de risque pour identifier les mesures de sécurité adaptées à mettre en œuvre S1
69. Gouvernance /4
70. © WAVESTONE 70 Stratégie générale autour des APIs GOUVERNANCE Pour les producteurs • Autant que possible, faire évoluer les APIs via des montées de version mineures afin d’impacter le moins possible les consommateurs. Cette exigence est d’autant plus critique que le nombre d’applications consommatrices devient élevé pour une API donnée • Appliquer un versioning explicite des APIs : • Mettre le numéro de version majeure dans l’URI de l’API • Suivre les bonnes pratiques en terme de règles syntaxiques pour la conception des URI • Exposer en parallèle deux versions majeures d’une même API pour laisser aux consommateurs un temps suffisant pour s’adapter à la nouvelle version majeure • Publier et tenir à jour une roadmap des API Pour les producteurs • Autant que possible, faire évoluer les APIs via des montées de version mineures afin d’impacter le moins possible les consommateurs. Cette exigence est d’autant plus critique que le nombre d’applications consommatrices devient élevé pour une API donnée • Appliquer un versioning explicite des APIs : • Mettre le numéro de version majeure dans l’URI de l’API • Suivre les bonnes pratiques en terme de règles syntaxiques pour la conception des URI • Exposer en parallèle deux versions majeures d’une même API pour laisser aux consommateurs un temps suffisant pour s’adapter à la nouvelle version majeure • Publier et tenir à jour une roadmap des API Pour les consommateurs • Faire en sorte que le code de l’application supporte les changements de version mineure : • Appliquer la charte de rétrocompatibilité • Consulter les roadmaps des API pour anticiper les décommissionnements Pour les consommateurs • Faire en sorte que le code de l’application supporte les changements de version mineure : • Appliquer la charte de rétrocompatibilité • Consulter les roadmaps des API pour anticiper les décommissionnements La raison d’être des APIs est de permettre le découplage entre les consommateurs et les producteurs de service. Il s’agit de répondre à un enjeu de modularité.
71. © WAVESTONE 71 GOUVERNANCE Définir le cadre de création et d’utilisation des APIs Former et outiller les développeurs Des sessions de formation et de présentations des principes adoptés doivent être organisées. Les équipes projets peuvent être rendues autonomes dans leur intégration au reste du SI. Définir les règles et les communiquer Les cinématiques autorisées et leur cadre d’application, les checklists sécurité, l’architecture de référence doivent être formalisées. Intégrer des ressources sécurité dans des sprints agiles Identifier des ressources agissant en tant que coach sécurité pour accompagner la conception applicative. Apporter des solutions prêtes à l’emploi et être un accélérateur. La démarche APIsation doit aller de pair avec un jeu complet de règles et d’outillages afin que l’ensemble des acteurs puissent répondre aux attentes dde l'organisation vis-à-vis des APIs. G1
72. © WAVESTONE 72 Documentation du framework Il est obligatoire de documenter une API. La meilleure façon de le faire est d’utiliser un Framework dédié. ⁄ Swagger est un framework de documentation d’API permettant de produire : ⁄ Un document interactif ⁄ Un client test ⁄ Une découverte d’API ⁄ La documentation doit : ⁄ Être compréhensible par un humain ou une machine. ⁄ Permettre de connaître les actions autorisées sans analyse du code. ⁄ Permettre une interaction facile avec le service. Documentation du framework Il est obligatoire de documenter une API. La meilleure façon de le faire est d’utiliser un Framework dédié. ⁄ Swagger est un framework de documentation d’API permettant de produire : ⁄ Un document interactif ⁄ Un client test ⁄ Une découverte d’API ⁄ La documentation doit : ⁄ Être compréhensible par un humain ou une machine. ⁄ Permettre de connaître les actions autorisées sans analyse du code. ⁄ Permettre une interaction facile avec le service. Documenter les API GOUVERNANCE Exemple de fichier Swagger G2 Utiliser le framework de documentation Swagger pour documenter le code des APIs.
73. © WAVESTONE 73 GOUVERNANCE Enrôler des consommateurs Rendre la souscription des applications consommatrices obligatoire pour utiliser une API, même publique. Catalogue des API Référentiel des applications consommatrices Portail API Enrôlement client_id client_secret Souscription Développeur d’applications 1 2 3 1 Le développeur d’application ou son mandataire accède au portail API de l'organisation 2 Le développeur d’application ou son mandataire enrôle une application consommatrice auprès de l’API manager et obtient en retour ses authentifiants 3 Le développeur d’application ou son mandataire souscrit à une ou plusieurs API pour l’application concernée client_id G3 La souscription, même pour des API publiques, permet de maitriser et tracer les accès, de s’assurer du respect des règles d’utilisation (volumétrie, fréquence …) et mettre en place le cas échéant des règles de gestion de la qualité de service (throttling).
74. © WAVESTONE 74 Définir une gestion simple des versions de l’API GOUVERNANCE Plusieurs versions en parallèle ⁄ Idéalement, se limiter à 2 versions majeures en cohabitation pour conserver une gouvernance simple ⁄ Toute évolution entre versions mineures doit être rétro compatible ⁄ Monter de version uniquement quand la rétro compatibilité n’est plus possible Plusieurs versions en parallèle ⁄ Idéalement, se limiter à 2 versions majeures en cohabitation pour conserver une gouvernance simple ⁄ Toute évolution entre versions mineures doit être rétro compatible ⁄ Monter de version uniquement quand la rétro compatibilité n’est plus possible Une seule version ⁄ API rétro compatible à chaque évolution ⁄ Nécessite plus d’étude pour éviter d’impacter les consommateurs ⁄ Peut obliger à bloquer la sortie de fonctionnalités ⁄ Plus facile à mettre en œuvre sur des APIs Privées Une seule version ⁄ API rétro compatible à chaque évolution ⁄ Nécessite plus d’étude pour éviter d’impacter les consommateurs ⁄ Peut obliger à bloquer la sortie de fonctionnalités ⁄ Plus facile à mettre en œuvre sur des APIs Privées Une version par client ⁄ Un socle technique commun pour toutes les versions ⁄ Possibilité de mettre en œuvre une couche de médiation ⁄ S’adapter au client tout en conservant les développements mutualisés Une version par client ⁄ Un socle technique commun pour toutes les versions ⁄ Possibilité de mettre en œuvre une couche de médiation ⁄ S’adapter au client tout en conservant les développements mutualisés Plus simple G4 Choisir un mode de montée de version qui facilite l’utilisation de l’API.
75. © WAVESTONE 75 Rétrocompatibilité (1/2) GOUVERNANCE APP  Pas de montée de version API Client Contrat Adresse v7 v5 Une application a besoin d’accéder à une ressource (ex : Adresse) qui n’est pas déjà exposée dans l’API v2 v3 v1 APP v8 API Client Contrat API Client Contrat v5 v6 Une application a besoin d’accéder à une version plus récente d’une ressource déjà exposée dans l’API  Montée de version v2 v3 v2 v4 APP APP v7 v8 La montée de version de l’API est nécessaire uniquement à l’occasion de la montée de version majeure d’une ressource déjà exposée sur l’API. G4
76. © WAVESTONE 76 Rétrocompatibilité (2/2) GOUVERNANCE La montée de version majeure d’une ressource est décidée par le fournisseur de la ressource. Elle n’est nécessaire qu’en cas de modification non rétrocompatible. Exemple de modification rétrocompatible : - ajout du champ devise dans la réponse à la requête GET sur la ressource /contrats  Pas de montée de version systématique Le contrat d’interface de la ressource change Contrat - ref - montant - type - devise L’implémentation de la ressource change  Pas de montée de version systématique Exemple de modification non rétrocompatible : - L’opération GET sur la ressource /contrats ne supporte plus le filtre sur le type d’opération GET /contrats?type=… Pas de montée de version requise Montée de version nécessaire Exemple de modification rétrocompatible - Ajout d’un mécanisme de cache à la ressource /contrats afin d’améliorer ses temps de réponse Pas de montée de version requise G4
77. © WAVESTONE 77 Cycle de vie d’une API GOUVERNANCE Versions majeures de l’API Versions majeures de l’API décomissionnée production dépréciée N dépréciée production N+1 production N+2 Evolution mineure d’une ressource (retro compatible) Evolution majeure d’une ressource (Non retro compatible) Développement Production Dépréciée (Plus d’évolution possible, indisponible aux nouveaux consommateurs) Décomissionée Arrêt de service de la version de l’API Evolution mineure d’une ressource propagée dans la version supérieure en développement Généralités et rappels ⁄ Une API peut être dans les états suivants : Nominale, dépréciée ou décomissionnée ⁄ Seules 2 versions majeures d’une API peuvent être simultanément en production (1 nominale et 1 dépréciée) ⁄ La montée de version d’une API ne se justifie que dans le cas d’évolutions non-rétrocompatibles La montée de version d’une API impacte l’ensemble des applications consommant l’API. Pour cette raison, toute montée de version doit rester de l’ordre de l’exceptionnel. G4
78. © WAVESTONE 78 Communiquer sur les versions GOUVERNANCE Se limiter à 2 versions majeures en parallèle et ne pas versionner les ressources. Se limiter à 2 versions majeures en parallèle et ne pas versionner les ressources. Sémantiques ⁄ Une version est écrite avec le format suivant : vX.Y.Z (ex : v2.8.5) ⁄ Version majeure (X, ex : 2) : concerne les mises à jour non rétro compatibles ⁄ Version mineure (Y, ex : 8) : concerne les mises à jour rétro compatibles ⁄ Version patch (Z, ex : 5) : concerne la résolution de bugs de rétro compatibilité ⁄ La rétro compatibilité est l’ensemble des changements restant compatibles avec la version d’API précédente. Sémantiques ⁄ Une version est écrite avec le format suivant : vX.Y.Z (ex : v2.8.5) ⁄ Version majeure (X, ex : 2) : concerne les mises à jour non rétro compatibles ⁄ Version mineure (Y, ex : 8) : concerne les mises à jour rétro compatibles ⁄ Version patch (Z, ex : 5) : concerne la résolution de bugs de rétro compatibilité ⁄ La rétro compatibilité est l’ensemble des changements restant compatibles avec la version d’API précédente. Invocation ⁄ Seule la version majeure est exposée. ⁄ L’invocation d’une version est faite dans l’URI ⁄ V1 : GET http://.../v1/current_accounts/1234 ⁄ V2 : GET http://.../v2/current_accounts/1234 ⁄ Implémentation : Google, Facebook, LinkedIn, Netflix Invocation ⁄ Seule la version majeure est exposée. ⁄ L’invocation d’une version est faite dans l’URI ⁄ V1 : GET http://.../v1/current_accounts/1234 ⁄ V2 : GET http://.../v2/current_accounts/1234 ⁄ Implémentation : Google, Facebook, LinkedIn, Netflix G4 Il faut communiquer les informations de versions et la roadmap de l’API auprès des consommateurs.
79. © WAVESTONE 79 Centre de contrôle des API Ses rôles sont précisés dans la slide suivante. Centre de contrôle des API Ses rôles sont précisés dans la slide suivante. Rôles intervenants dans la construction et la sécurisation d’une API GOUVERNANCE Gestionnaire du SI (exploitation) Gère le système d’information dans lequel fonctionne l’API, il est responsable de la disponibilité de l’infrastructure. Gestionnaire du SI (exploitation) Gère le système d’information dans lequel fonctionne l’API, il est responsable de la disponibilité de l’infrastructure. Souscripteurs d’API et Responsables projet applicatif Souscripteurs d’API et Responsables projet applicatif Responsables de ressource Responsables de ressource Responsables d’API Responsables d’API Gère et maitrise la ressource, il est responsable du ou des points d’entrées à sa ressource. Gère l’interface permettant d’accéder à la ressource (l’API), il est responsable notamment de son cycle de vie (déploiement, montée de version, fin de vie). Gère le déploiement et le cycle de vie de son application, il est responsable de la bonne utilisation des API par son application. G5 Mettre en place un centre de contrôle des API garant de la démarche unifiée au sein de l'organisation.
80. © WAVESTONE 80 Décide de l’évolution du patrimoine des APIs Établit le cadre de référence et de gouvernance des APIs • Fait évoluer le cycle de vie projet • Définit le modèle de versioning • Définit les référentiels/outils nécessaires à la gouvernance • Définit les normes d’exposition (syntaxe, taxonomie) • Fournit des guides sur la fabrication, la gestion des versions, la sécurité, la gestion des bouchons, etc… • Constitue et anime des modules de formations à l’attention des équipes projets (chefs de projet et développeurs) Fournit la plateforme d’API Management et le Portail d’API • Joue le rôle de Product Owner pour les composants API Manager et le Portail API • Valide l’inscription des applications aux API via l’API Manager • Support N3 Lettre de mission de l’équipe « Centre de contrôle des API » Accompagne opérationnellement les équipes projets dans leurs réalisations d’APIs • Participe à l’identification et à la conception des ressources avec les équipes projets, et valide les swaggers et autres documentations • Supporte les projets dans la réalisation et la consommation des API • Contrôle la conformité des API avec le cadre de référence • Établit le capacity planning des APIs, et alerte au besoin les responsables d’API • Décide des évolutions à apporter au patrimoine d’API (création, montées de version, décommissionnement) • Donne son avis pour les dossiers d’architecture • Tient à jour et publie la roadmap du patrimoine • S’assure de la nomination de responsables d’API Compétences : urbanisme Compétences : maîtrise de la solution d’API Management Compétences : connaissance des modèles de données, architecture applicative distribuée, développement Compétences : génie logiciel GOUVERNANCE
81. © WAVESTONE 81 Équipes Projets Équipes Projets Run Zoom sur le rôle de centre de contrôle dans le cycle de vie d’un projet • Qualifier l’impact du projet sur le patrimoine des API : faut-il créer une nouvelle API ? Adapter une API existante ? Est-ce une adaptation majeure ou mineure ? • Communiquer l’impact aux Product Owner des APIs, et lancer des projets en conséquence • Créer un code API pour toute nouvelle version majeure d’API pour faciliter le suivi • Mettre à jour la roadmap du patrimoine des API 2. Concevoir la solution • Documenter dans le dossier d’architecture les APIs ré-utilisées • Documenter dans le dossier d’architecture le design des nouvelles APIs à créer 3. Spécifier la solution • Rédiger le contrat d’interface (Swagger) pour les nouvelles API ou les APIs à adapter • Aider les développeurs à s’approprier les outils et frameworks de développement. • Aider au debug, notamment sur l’API Manager • Accompagner les équipes sur la méthodologie de test (TNR) • Valider le contrat d’interface / Vérifier la conformité aux règles syntaxiques, à la taxonomie des objets métiers, aux règles de versioning. Si pertinent, mettre en conformité le Swagger avec des standards du marché (normes ISO…) 1. Évaluer l’intérêt du projet • Recenser les API existantes pouvant faciliter la mise en œuvre du projet • Fournir des abaques (estimations non engageantes) permettant d’évaluer le coût complet (TCO) de création de nouvelles APIs 4. Implémenter la solution • Développer les APIs • Garantir la non- régression des APIs en cas d’évolution mineure 5. Exploiter la solution • Exploiter 2 versions majeures en parallèle • Approuver la souscription des applications (front- end) aux API • Suivre la consommation des APIs ; si besoin prévenir les PO pour une adaptation de la puissance • Pas de changement • Dossier d’Archi. avec chapitre « API » • Swagger • Code source API • Bouchons • Jeux de tests • Ressource et compte de test (« healthcheck ») • Pas de livrable • Accord pour validation de l’architecture • Roadmap des APIs mise à jour • Swagger validé • Pas de livrable • Carto. des consommateurs • Capacity planning mis à jour Build Solution design Business Case Centre de contrôle Centre de contrôle Nouveaux travaux Nouveaux livrables Travaux Livrables GOUVERNANCE
82. © WAVESTONE 82 Zoom sur le rôle de centre de contrôle lors de la montée de version majeure d’une API GOUVERNANCE 1 2 3 Dès prise de connaissance d’un besoin de montée de version d’une API • Le centre de contrôle notifie chaque application consommatrice de l’API qu’une nouvelle version est en cours de conception • Cette 1ère notification permet aux applications consommatrices d’avoir de la visibilité sur le cycle de vie de l’API et d’anticiper bien en amont la dépréciation de la version en cours Dès prise de connaissance d’un besoin de montée de version d’une API • Le centre de contrôle notifie chaque application consommatrice de l’API qu’une nouvelle version est en cours de conception • Cette 1ère notification permet aux applications consommatrices d’avoir de la visibilité sur le cycle de vie de l’API et d’anticiper bien en amont la dépréciation de la version en cours Développement d’une version N+1 • La version N+1 de l’API doit intégrer : • Les ressources créées dans le cadre de la version N+1 • L’ensemble des ressources non dépréciées de la version N (Version mineure la plus récente) Le centre de contrôle notifie chaque application consommatrice qu’elle doit inscrire dans sa roadmap la consommation de la nouvelle version de l’API Développement d’une version N+1 • La version N+1 de l’API doit intégrer : • Les ressources créées dans le cadre de la version N+1 • L’ensemble des ressources non dépréciées de la version N (Version mineure la plus récente) Le centre de contrôle notifie chaque application consommatrice qu’elle doit inscrire dans sa roadmap la consommation de la nouvelle version de l’API Mise en production de la version N+1 • La mise en production de la version N+1 entraine automatiquement la dépréciation de la version N • Toute nouvelle application consommatrice de l’API doit consommer la version N+1 • Toutes les évolutions mineures de ressource doivent être déployées dans la version N+1 • Dans le Magasin d’API, le centre de contrôle passe le statut de l’API version N à dépréciée Mise en production de la version N+1 • La mise en production de la version N+1 entraine automatiquement la dépréciation de la version N • Toute nouvelle application consommatrice de l’API doit consommer la version N+1 • Toutes les évolutions mineures de ressource doivent être déployées dans la version N+1 • Dans le Magasin d’API, le centre de contrôle passe le statut de l’API version N à dépréciée … …
83. © WAVESTONE 83 GOUVERNANCE Exemple d’organisation interne d’un centre de contrôle des API Il est intéressant d’avoir des personnes à cheval sur plusieurs rôles pour éviter les silos. Accompagnants projets Responsables outils transverses Architectes fonctionnels Responsable du centre de contrôle PMO
84. © WAVESTONE 84 Zoom sur le rôle « responsable centre du contrôle des API » GOUVERNANCE Pilote et dimensionne l’équipe centre de contrôle des API Identifie et cartographie l’ensemble des projets API Identifie et responsabilise un accompagnant pour chaque projet En s’appuyant sur un PMO, synchronise le planning en fonction de la disponibilité des ressources (outils transverses et accompagnants) Anime les réunions de gouvernance : / Meeting hebdomadaire des membres de la cellule pour assurer notamment la synchronisation entre l’équipe responsable des outils transverses et les accompagnants projets / Meeting hebdomadaire ou bimensuel avec tous les projets et le PMO (voire peut être certains accompagnants projets) pour communiquer sur les actualités, partager les avancement, prévoir et ajuster les plannings et identifier les nouveaux projets
85. © WAVESTONE 85 Zoom sur le rôle « accompagnants projets » GOUVERNANCE Point de contact unique (un seul par projet) pour tout accompagnement relatif à l’API Accompagnent des projets sur les phases de : / Conception : identification des ressources et opérations nécessaires, respect des guidelines, aide à la rédaction du Swagger / Développement / recette : conseil / expertise sur les outils à utiliser / Déploiement : configuration de l’API manager, gestion des souscriptions / Cycle de vie : évolution du plan de consommation, routage, nouveaux souscripteurs, montées de version, etc. Définissent et documentent les processus à suivre par les projets Doivent être formés par l’équipe responsable des outils transverses : au début en direct, avec l’équipe outil transverses qui aide à l’accompagnement projet, puis ensuite il faudra industrialiser et documenter les processus Important : pas d’ingérence dans le projet, c’est un accompagnant sur lequel peut s’appuyer le chef de projet
86. © WAVESTONE 86 Zoom sur le rôle « responsables des outils transverses » GOUVERNANCE Mettent en place, opèrent et assurent l’évolution des outils et méthodes transverses à tous les projets. Notamment dans un premier temps : / L’API Manager (TYK) / L’infrastructure de sécurité (SSO / AS) Assurent la formation des accompagnants projets sur l’outillage et les méthodes à disposition (guidelines de conception, publication, sécurisation, …) et les assistent dans leurs choix d’architecture pour les projets Font évoluer les guidelines (conception, publication, sécurisation, …) Identifier 1 architecte technique référent, assurant la cohérence de l’outillage transverse, en lien avec les besoins des projets Faire contribuer les équipes dédiées à chaque outil
87. © WAVESTONE 87 Zoom sur le rôle « architectes fonctionnels » GOUVERNANCE Construisent et assurent la cohérence du catalogue d’API à l’échelle des QSI voire de tout le ministère Connaissent les objets et workflow métiers et appuient à la conception de certaines API complexes en soutient à l’accompagnant Ces architectes doivent être au plus proche du métier
88. © WAVESTONE 88 Exemple de processus d’un projet développant une API GOUVERNANCE 2 Le centre de contrôle assigne un accompagnant au projet 3 Le projet réalise la conception de l’API avec la MOA, la MOE et l’accompagnant 4 Le projet rédige un Swagger qui est ensuite validé par l’accompagnant 6 L’accompagnant déploie l’API hors-prod et génère les souscriptions nécessaires 5 Le projet développe l’API et complète la documentation de l’API (en plus du Swagger) 7 Le projet teste l’API 8 L’accompagnant déploie l’API en prod et génère les souscriptions nécessaires 1 Le projet d’API sollicite le centre de contrôle
89. © WAVESTONE 89 Impliquer le métiers dans le développement des API GOUVERNANCE ⁄ Cas d’usage significatifs ⁄ Validation des contraintes juridiques ⁄ Choix de Modèle économique ⁄ Faisabilité technique ⁄ Nouvelles solutions technologiques ⁄ Constituer une équipe de développement solide et agile ⁄ Mobilisation de ressources métiers internes et externes ⁄ Rapport d’opportunité ⁄ Mobilisation de ressources techniques internes et externes ⁄ Bilan d’implémentation ⁄ Montée en compétence ⁄ Projets pilotes ⁄ Dialogue entre métiers ⁄ Gouvernance de données ⁄ Design du Store d’API ⁄ Promouvoir l’API ⁄ Construction de l’offre (Socle technologique, règles de conception des APIs, Facturation…) ⁄ Infrastructure robuste et adaptée aux enjeux métier ⁄ Opportunités sur les données (étude de marché, cas d’usages potentiels…) ⁄ État de l’art ⁄ Inventaire de l’existant réutilisable ⁄ Evaluation du ROI ⁄ Veille sur les opportunités ⁄ Enrichissement des modèles et données ⁄ Gérer le cycle de vie de l’API ⁄ Veille et innovations technologiques ⁄ Enrichissement de la plateforme Directions métiers Directions métiers Direction des systèmes d’information Direction des systèmes d’information Prise de conscience des opportunités Choix de cas d’usage éligibles pour un POC POC(s), démonstration et échanges Transformation progressive Animation de l’écosystème API Émergence Émergence Étude Étude Expérimentation Expérimentation Construction Construction Animation Animation G6 Les API ne sont pas qu’un sujet technique. Le métier doit être impliqué dans tout initiative relative aux échanges de données.
90. © WAVESTONE 90 Résumé des recommandations de gouvernance DESIGN Documenter grâce à Swagger Utiliser le framework de documentation Swagger pour documenter le code des APIs. G2 Simplifier la gestion des versions et communiquer dessus Choisir un mode de montée de version qui facilite l’utilisation de l’API. Idéalement deux versions majeures en cohabitation. G4 Se doter d’un centre de contrôle des API Il sera garant du respect de la démarche d’APIsation au sein de l'organisation et assurea un rôle de conseil et d’expertise auprès des projets. G5 Impliquer le métier Les API ne sont pas qu’un sujet technique, le métier doit être impliqué dans tout initiative relative aux échanges de données. G6 Enrôler les consommateurs Rendre la souscriptions des applications obligatoires même pour les API publiques. G3 Définir le cadre de création et d’utilisation des APIs Pour partager les consignes et pratiques à respecter. G1
91. Jean-Loup VIARD Consultant M +33 (0)6 99 82 68 62 Jean-loup.viard@wavestone.com Saad BOUNJOUA Consultant Senior M +33 (0) 7 62 70 33 97 Saad.bounjoua@wavestone.fr
92. PARIS LONDON NEW YORK HONG KONG SINGAPORE * DUBAI * BRUSSELS LUXEMBOURG GENEVA CASABLANCA LYON MARSEILLE NANTES * Strategic partners
93. Annexes /05
94. Chiffrement des données /A
95. © WAVESTONE 95 ANNEXES Zoom sur le chiffrement des données avec les API Déploiement d’un certificat pour chaque API et contrôle du certificat par le navigateur, l’application ou le serveur qui réalise l’appel / Dans le cas d’un appel depuis le navigateur, forcer l’utilisation de TLS via l’entête Strict-Transport-Security Strict-Transport-Security: max-age=expireTime [; includeSubDomains] [; preload] Le certificat de l’API exposé aux clients peut être porté par différentes briques : / L’API, si elle est consommée directement sans passer par un API Gateway / L’API Gateway, qui doit nécessairement réaliser une rupture protocolaire pour examiner les flux / Un équipement réseau qui consolide les flux sortant (WAF, reverse proxy …) et qui portent les certificats publiques de l'organisation (potentiellement wildcard) Quand le certificat frontal n’est pas porté par l’API, il est conseillé de chiffrer les flux à l’intérieur de l'organisation entre le composant frontal et jusqu’à l’API, en utilisant plusieurs certificats internes si besoin. Chiffrement TLS 1.2 Permets de chiffrer les objets JSON contenant soit des données techniques ou des données métiers. Le chiffrement est réalisé entre l’API Gateway et les clients, qui doivent s’enrôler au préalable pour récupérer leurs clés cryptographiques. Toutes les données ne sont pas à chiffrer, l’analyse de risques doit permettre d’identifier lesquelles retenir. Un jeton JWE est constitué de 5 objets JSON concaténés, encodés en base64url / Un entête : spécifie les algorithmes et certificats utilisés / Une EncryptedKey : clé symétrique de chiffrement, chiffrée avec la clé publique du destinataire / Un InitializationVector : clé aléatoire qui sert de vecteur d’initialisation au chiffrement symétrique / Les données chiffrées / Une Balise d’Authentification : la signature RSA de l’entête, concaténée aux données chiffrées JSON Web Encryption Permets de chiffrer les données métiers au niveau applicatif, par les API, ressources voire les bases de données. Dans ce cas, l’API et l’API GW manipulent des données chiffrées. Pour que les clients puissent les déchiffrer, ils doivent avoir accès à la clé de chiffrement : / Elle peut soit être liée à la donnée, et donc partagée avec plusieurs clients (c’est utile lorsque la donnée est stockée chiffrée en base, sans appeler des fonctions crypto lors de l’appel à l’API) / Soit elle peut être liée à un client, et dans ce cas le client doit s’enrôler au préalable, et la donnée doit être chiffrée à la volée à chaque appel à l’API Toutes les données ne sont pas à chiffrer, l’analyse de risques doit permettre d’identifier lesquelles retenir. Ce type de solutions est relativement complexe à mettre en place, avec le besoin de disposer d’infrastructure type KMS ou HSM pour stocker et gérer le cycle de vie des clés cryptographiques. Ces solutions doivent être utilisées pour protéger des données très sensibles à grand impacts. Chiffrement applicatif
96. Signature des données /B
97. © WAVESTONE 97 ANNEXES Zoom sur la signature des données avec les API -> RFC 3230 Signature de l’ensemble de la requête HTTP Ajout de headers : ⁄ Digest : Contient le hash du corps de la requête ⁄ Signature : Contient une chaine de signature construite à partir du verbe HTTP, de l’opération, et d’une liste de headers Points d’attention : ⁄ Le protocole permet de choisir les headers signés › Les headers signés ne doivent pas être modifiés par des composants intermédiaires (reverse-proxy, WAF…) ⁄ Nécessite une extension du socle pour vérifier la signature ⁄ Ce protocole permet de signer tous les formats de messages véhiculés par le protocole HTTP (JSON, application/x-www-form- urlencoded, XML, etc.) ⁄ En cas de journalisation, l’ensemble de la requête HTTP doit être journalisée (et pas seulement le message) Signature HTTP -> RFC 7515 Signature du message JSON de la requête REST Il existe deux types de signature JWS : ⁄ Sérialisation compacte › Le header JWS, le message JSON et la signature sont encodés en base64 et concaténés avec le caractère « . » ⁄ Sérialisation JSON › Le header JWS, le message JSON et la signature sont encodés en base64 puis insérés dans le JSON défini dans le standard JWS › L’intérêt est de pouvoir signer de manière multiple un même document JSON Points d’attention : ⁄ Le format du document JSON est modifié (encodé en base64) › Incompatible avec la représentation Swagger (qui décrit le JSON) ⁄ Nécessite une extension du socle pour vérifier la signature ⁄ Le message ainsi encodé est plus long (+33% en moyenne) ⁄ Ce protocole permet de signer uniquement le format JSON (et donc ne permet pas de signer une requête sans corps HTTP) ⁄ En cas de journalisation, seul le corps JWS doit être journalisé JSON Web Signature
98. © WAVESTONE 98 ANNEXES Illustration de la signature HTTP POST /paymentCoverage/?param Date: Tue, 07 Jun 2014 20:51:35 Accept: application/hal+json Signature: <params signature> Digest: SHA-256=vd2xlZ…LCBleGN { "cardPan": "1234567890123456", "amount": { "InstdAmt": "1200.00", "Ccy": "EUR" } } Signature HTTP POST /paymentCoverage/?param Date: Tue, 07 Jun 2014 20:51:35 Accept: application/hal+json { "cardPan": "1234567890123456", "amount": { "InstdAmt": "1200.00", "Ccy": "EUR" } } (request-target):POST /paymentCoverage/?param Date: Tue, 07 Jun 2014 20:51:35 Digest: SHA-256=vd2xlZ… LCBleGN Vdts8…UoyWxB 1 2 Requête initiale
99. © WAVESTONE 99 ANNEXES Illustration de JSON Web Signature { "headers": [ "eyJhbGciOiJSUzI1NiJ9" ], "payload": "ew0KICAiY2FyZFBhbiI6ICIxMjM0NTY3ODkwMTIzNDU2IiwNCiAgImFt b3VudCI6IHsNCiAgICAiSW5zdGRBbXQiOiAiMTIwMC4wMCIsDQogICAg IkNjeSI6ICJFVVIiDQogIH0NCn0NCg", "signatures": [ "jmqPmLpeCncXTVYz6Tcf4nhIeRVVCoWhhmE0aWSsSwvPK4Tov- A5eQ71DDDpUkLYmmQHbpgI6gBw3Hk29LSPfYwThvsseY2vpn2LWtKN qy9e7zpmdyZFiqcBE37ZMEW1i68ouhlNzdCULL5x1JscrBs5m4X7fG6kH 93os4kefe63E_XAWShZ3xjisdRajkPFsMRRCYJxEo5FhycgMc3k1CfiqMyB O-AoQiu9Jx8bHeQIa- 0IS9GKn_igYS9SlRN6NHFnr8HNVAxBFMFXrGzX_FLzqStSywId07mcHw Pv9FoHIKVsydmVgaIvZUovLvW9O9iuEKieXgLGNbEBqeZY8Q" ] } Signature JWS – Sérialisation JSON POST /paymentCoverage/?param Date: Tue, 07 Jun 2014 20:51:35 Accept: application/hal+json { "cardPan": "1234567890123456", "amount": { "InstdAmt": "1200.00", "Ccy": "EUR" } } Requête initiale eyJhbGciOiJSUzI1NiJ9.ew0KICAiY2FyZFBhbiI6ICIxMjM0NTY3ODkwMTIzND U2IiwNCiAgImFtb3VudCI6IHsNCiAgICAiSW5zdGRBbXQiOiAiMTIwMC4wMC IsDQogICAgIkNjeSI6ICJFVVIiDQogIH0NCn0NCg.jmqPmLpeCncXTVYz6Tcf4 nhIeRVVCoWhhmE0aWSsSwvPK4… _FLzqStSywId07mcHwPv9FoHIKVsydmVgaIvZUovLvW9O9iuEKieXgLGNbEB qeZY8Q Signature JWS – Sérialisation compacte
100. Modes opératoires OAuth2 /C
101. © WAVESTONE 101 OAuth2 : illustration extraite de la RFC 6749 du mode opératoire « Authorization Code Grant » ANNEXES
102. © WAVESTONE 102 OAuth2 : illustration extraite de la RFC 6749 du mode opératoire « Resource Owner Password Credentials Grant » ANNEXES
103. © WAVESTONE 103 OAuth2 : illustration extraite de la RFC 6749 du mode opératoire « Implicit Grant » ANNEXES
104. © WAVESTONE 104 OAuth2 : illustration extraite de la RFC 6749 du mode opératoire « Client Credentials Grant » ANNEXES