Intégrations

OAuth

Autoriser une application externe à accéder à votre site avec OAuth 2.0 et OpenID Connect, grâce au document Client OAuth.

OAuth

Votre site peut jouer le rôle de fournisseur OAuth 2.0 (et OpenID Connect). Une application externe obtient alors un jeton d'accès au nom d'un utilisateur, sans connaître son mot de passe. L'utilisateur se connecte sur votre site et autorise l'application.

Pour l'inverse (se connecter à votre site avec un compte Google, GitHub ou Office 365), consultez Connecteurs sociaux.

Prérequis

  • Avoir le rôle Responsable système.
  • Connaître l'URL de retour (redirect URI) de l'application externe.

Enregistrer une application externe

  1. Ouvrez la recherche (Ctrl+K) et saisissez Client OAuth. Le document se trouve aussi dans l'espace Intégrations, section Authentification.
  2. Cliquez sur Créer.
  3. Saisissez le Nom de l'application (Nom du client).
  4. Dans URIs de redirection, saisissez les URL de retour autorisées, une par ligne.
  5. Dans URI de redirection par défaut, saisissez l'URL utilisée quand l'application n'en précise pas.
  6. Vérifiez les Périmètres (par défaut all openid).
  7. Enregistrez.

Dokos remplit alors l'ID client (le nom du document) et génère le Secret client si vous ne l'avez pas saisi. Transmettez ces deux valeurs à l'application externe.

Champs du Client OAuth

ChampRôle
ID clientIdentifiant public de l'application. Il est égal au nom du document.
Nom de l'application (Nom du client)Nom affiché à l'utilisateur sur l'écran d'autorisation. Obligatoire.
UtilisateurUtilisateur associé au client, si besoin.
Secret clientSecret partagé avec l'application. Généré à l'enregistrement s'il est vide.
Ne pas demander d'autorisationSi coché, l'utilisateur n'a pas à confirmer l'accès sur l'écran d'autorisation.
PérimètresPérimètres accordés, séparés par des espaces. Valeur par défaut : all openid.
URIs de redirectionURL de retour autorisées.
URI de redirection par défautURL de retour par défaut. Obligatoire.
Type d'autorisationCode d'autorisation ou Implicite.
Type de réponseCode ou Token.
Rôles autorisésRôles qui peuvent utiliser ce client. Si la liste est vide, Dokos ajoute le rôle « Utilisateur système » à l'enregistrement.
Méthode d'authentification du point de terminaison de jetonSecret client basique (par défaut), Secret client POST ou Aucun (client public).

Les champs de la section Métadonnées du client (URI du client, URI du logo, URI TOS…) sont remplis quand un client s'enregistre lui-même par l'API. Ils ne s'affichent que s'ils ont une valeur.

Le Type d'autorisation et le Type de réponse vont par paires : Code d'autorisation avec Code, Implicite avec Token. Une autre combinaison bloque l'enregistrement.

Points de terminaison

Les URL sont relatives à l'adresse de votre site.

UsageURL
Autorisation/api/method/frappe.integrations.oauth2.authorize
Jeton/api/method/frappe.integrations.oauth2.get_token
Révocation/api/method/frappe.integrations.oauth2.revoke_token
Profil OpenID (userinfo)/api/method/frappe.integrations.oauth2.openid_profile
Introspection/api/method/frappe.integrations.oauth2.introspect_token
Configuration OpenID/.well-known/openid-configuration

Paramètres du fournisseur OAuth

Le document Paramètres du Fournisseur OAuth contient un seul réglage, Ne pas demander d'autorisation :

  • Forcer : l'écran d'autorisation s'affiche à chaque demande.
  • Auto : l'écran ne s'affiche qu'à la première autorisation de l'application par l'utilisateur.

Exemple

Exemple fictif. Une application de prise de rendez-vous doit lire le nom et l'e-mail de vos utilisateurs.

  1. Créez un Client OAuth nommé « Agenda Partenaire ».
  2. Saisissez https://agenda.example.com/oauth/callback dans URIs de redirection et URI de redirection par défaut.
  3. Gardez Code d'autorisation et Code, puis enregistrez.
  4. Donnez l'ID client et le Secret client à l'éditeur de l'application.

L'utilisateur clique sur « Se connecter avec Dokos » dans l'application. Il se connecte sur votre site, autorise l'accès, puis revient dans l'application avec un code. L'application échange ce code contre un jeton sur le point de terminaison Jeton.