Aller au contenu

Applications mobiles et natives

Une application mobile ou de bureau ne peut pas garder de secret : tout ce qu’elle embarque peut être lu. LexOpti suit la RFC 8252 (OAuth 2.0 pour les applications natives) pour ces applications, et leur permet d’afficher les composants embarqués dans une webview.

Votre produit Enregistrez Où vivent les jetons
Une application avec votre propre serveur (la plupart des logiciels métier) une application web : votre serveur est le client, l’application parle à votre serveur sur votre serveur, jamais sur l’appareil
Une application sans serveur à elle une application native : un client public, sans secret sur l’appareil, dans le trousseau (iOS, macOS) ou un stockage adossé au Keystore (Android)

Quand vous avez un serveur, gardez-le comme client : le membre autorise dans le navigateur du système, LexOpti redirige vers l’adresse de retour HTTPS de votre serveur, et votre application ne détient jamais de jeton LexOpti. La suite de cette page traite du second cas, et des composants embarqués dans une webview, qui valent dans les deux.

Dans la console développeur, choisissez Application native ou mobile comme type d’application. LexOpti enregistre un client public : aucun secret client (aucun n’est affiché, aucun ne peut être renouvelé), PKCE S256 exigé à chaque autorisation. Ses URI de redirection prennent l’une des trois formes de la RFC 8252, chacune comparée à l’identique :

Forme Exemple Règle
Interface de boucle locale, pour les applications de bureau (§7.3) http://127.0.0.1/oauth/callback, http://[::1]/oauth/callback l’adresse IP littérale, jamais localhost (§8.3) ; le port est omis et tout port correspond à l’autorisation, l’application écoute donc sur le port que le système lui donne
Schéma d’URI à usage privé (§7.1) com.example.crm:/oauth/callback un nom de domaine inversé que vous contrôlez, avec un point (§8.4)
URI HTTPS revendiquée (§7.2) https://app.example.com/oauth/callback un lien universel iOS ou un lien d’application Android, vérifié pour votre domaine ; la règle d’une application web

Préférez une URI HTTPS revendiquée quand vous pouvez vérifier votre domaine : une autre application de l’appareil peut déclarer le même schéma à usage privé et recevoir le code (§8.1), et seul PKCE rend alors inutile un code intercepté. Un serveur d’écoute en boucle locale n’écoute que l’interface de boucle locale, accepte une redirection, puis s’arrête.

Ouvrez l’URL d’autorisation dans le navigateur du système, jamais dans une webview de votre application (RFC 8252 §8.12 : l’application pourrait lire le mot de passe du membre, et le membre ne pourrait pas vérifier l’adresse) : ASWebAuthenticationSession sur iOS et macOS, Custom Tabs sur Android, le navigateur par défaut sur ordinateur. La requête est celle d’une application web (authentification), avec votre URI de redirection et un vérificateur PKCE et un state neufs à chaque tentative.

Avec une redirection en boucle locale ou un schéma à usage privé, rien ne prouve quel programme demande (RFC 8252 §8.6) : n’importe lequel sur l’appareil pourrait envoyer votre client_id. LexOpti affiche donc la page de consentement, qui nomme votre application, à chaque autorisation, même quand le membre l’a déjà approuvée, et refuse prompt=none avec interaction_required à votre URI de redirection. Une redirection HTTPS revendiquée est liée à votre domaine vérifié et suit la règle d’une application web.

Appelez ensuite le point de jeton avec votre client_id dans le formulaire, sans en-tête Authorization :

Type d’octroi Paramètres au point de jeton
authorization_code client_id, code, code_verifier, redirect_uri, resource
refresh_token client_id, refresh_token, resource

Un code refusé une fois, vérificateur absent ou faux, est consommé : recommencez l’autorisation. Les jetons de rafraîchissement tournent comme ceux d’une application web : chaque rafraîchissement en renvoie un nouveau, valable 30 jours, et l’ancien cesse de fonctionner (un rafraîchissement concurrent dans les 10 secondes reçoit la même réponse). Enregistrez le nouveau jeton de rafraîchissement dans le trousseau ou le Keystore avant d’utiliser le jeton d’accès, et ne laissez courir qu’un rafraîchissement à la fois (durées de vie et rotation).

Pour afficher les écrans de LexOpti dans votre application, hébergez les composants sur votre propre page HTTPS, comme sur le web (composants embarqués), et chargez cette page dans une webview (WKWebView sur iOS, WebView sur Android). Ce qui fonctionne et ce qu’il faut régler :

  • L’origine de la page. Enregistrez l’origine exacte de la page (https://crm.example.com) comme origine d’intégration, et chargez la page par son URL. Une page chargée depuis un fichier, un schéma personnalisé ou une chaîne HTML n’a pas d’origine que LexOpti puisse autoriser : le cadre refuse de s’afficher, car il n’accepte que les origines enregistrées comme parent et comme interlocuteur postMessage.
  • Les sessions. Le fournisseur de session demande chaque code de session à votre serveur depuis cette page, avec votre propre session auprès de votre serveur, de premier niveau dans la webview comme dans un navigateur. Une nouvelle webview, ou un rechargement, ouvre de nouvelles sessions : un code sert une seule fois pendant 60 secondes, un jeton de session vit 10 minutes dans la mémoire du cadre.
  • Cookies et stockage. Le jeton de session de LexOpti ne quitte jamais la mémoire du cadre, mais le cadre garde ses préférences d’interface (la vue en cartes ou en tableau d’une liste, un avis écarté) dans le stockage DOM et la langue dans un cookie. Quand le stockage ou le cookie tiers est refusé (Intelligent Tracking Prevention de WebKit dans WKWebView, CookieManager.setAcceptThirdPartyCookies désactivé par défaut dans Android WebView), le cadre continue de fonctionner avec ses valeurs par défaut : la vue en tableau, rien de retenu d’une page à l’autre, la langue que votre page donne aux composants. N’assouplissez pas le blocage des cookies pour LexOpti.
  • JavaScript et stockage DOM. Activez-les sur Android (settings.javaScriptEnabled = true, settings.domStorageEnabled = true) ; WKWebView les a par défaut.
  • Nouvelles fenêtres. La connexion à LexOpti, la facturation, un PDF et les liens vers LexOpti s’ouvrent dans un nouvel onglet (parcours dans la fenêtre de LexOpti). Une webview n’ouvre rien tant que vous ne le gérez pas : ouvrez ces URL dans le navigateur du système (SFSafariViewController ou le navigateur par défaut) depuis webView(_:createWebViewWith:for:windowFeatures:) de WKUIDelegate sur iOS, et depuis WebChromeClient.onCreateWindow avec setSupportMultipleWindows(true) sur Android (Custom Tabs). Une page ne peut ouvrir une fenêtre que si la webview le permet : javaScriptCanOpenWindowsAutomatically = true (WKPreferences sur iOS, WebSettings sur Android). Sur Android, onCreateWindow doit confier à la nouvelle fenêtre une WebView de transport (WebView.WebViewTransport, puis resultMsg.sendToTarget()) et lire l’URL que cette webview doit charger, pour l’ouvrir dans un Custom Tab. Ces réglages viennent de la documentation des plateformes : LexOpti ne les a pas testés sur un appareil.
  • Versions. WKWebView est le WebKit du système : iOS 16.4 ou plus récent, comme Safari 16.4. Android WebView suit Chrome par le Play Store.
  • Pas dans la webview. L’autorisation OAuth du membre (ci-dessus) ne s’y déroule jamais.
  • Une application native n’a pas de secret client : rien à protéger dans votre binaire, rien à renouveler. PKCE lie chaque code à l’application qui l’a demandé.
  • localhost est refusé : le nom peut se résoudre ailleurs, et un autre programme pourrait répondre sur une autre interface (§8.3).
  • Un schéma à usage privé sans point, comme monappli:, est refusé : n’importe quelle application pourrait le déclarer (§8.4).
  • Un jeton de rafraîchissement sur l’appareil est l’accès du membre pendant 30 jours : gardez-le dans le trousseau ou le Keystore, jamais dans des préférences en clair, et révoquez-le quand le membre se déconnecte de votre application : POST https://app.lexopti.com/api/auth/oauth2/revoke avec client_id, token et token_type_hint=refresh_token, sans secret (déconnecter un membre).