Okta Workflows Tutorial : Créer un connecteur pour l’API Spotify (avec OAuth 2.0)

Ce tutoriel vous apprendra à créer un connecteur pour l'API Spotify qui utilise OAuth pour l'authentification à l'aide de Okta Workflows Connector Builder.

• Connecteur pour l'API Spotify
• Créer un connecteur pour l'API Spotify
• Ressources

Connecteur pour l'API Spotify

Vous créerez un connecteur pour l'API Spotify car elle utilise OAuth pour l'authentification. Ce tutoriel vous apprendra à créer un connecteur dans le Connector Builder qui utilise OAuth pour l'authentification.

L’authentification OAuth est un sujet avancé. Si vous débutez avec le générateur de connecteurs, veuillez lire et suivre les autres articles et didacticiels de cette série : 

• Comprendre les connecteurs Okta Workflows.
• Tutoriel Okta Workflows : Créer un connecteur pour l'API OpenWeather.

Si vous souhaitez appeler l'API Spotify en utilisant la carte API Connector, consultez cet article de la base de connaissances bsp;:

• Comment appeler l'API Spotify à partir d'Okta Workflows (exemple d'authentification OAuth).

Cet article de la base de connaissances vous expliquera comment configurer la connexion OAuth et appeler l’API Spotify à l’aide de la carte API Connector (connecteur API).

Créer un connecteur pour l'API Spotify

Dans cette section, vous allez créer un connecteur vers Spotify dans le Connector Builder.

Le Connector Builder utilise des flux Workflows et des cartes (action, fonction) pour créer un connecteur.

Un connecteur est constitué de plusieurs flux :

• Un flux pour effectuer des requêtes HTTP.
• Un flux pour vérifier que l'authentification au service fonctionne.
• Un ou plusieurs flux d'action. Chaque flux d'action appelle le point de terminaison API d'un service.
• Flux d'action personnalisé pour permettre d'appeler n'importe quel point de terminaison d'API sur le service (voir le tutoriel Créer un connecteur pour l'API OpenWeather).

Tout d’abord, vous devez avoir un compte Spotify avant de commencer à créer le connecteur.

Créez un compte et une application Spotify

Créer un compte Spotify

1. Créer un compte Spotify, si vous n'en avez pas.

Créer une application

Après avoir mis en œuvre un flux d'autorisation, l'application fournira un jeton d'accès pour effectuer des appels à l'API Spotify.

1. Pour créer une application, accédez à votre tableau de bord, puis cliquez sur Create an app.
2. Entrez Workflows Connector Builder pour App name.
3. Saisissez Workflows Connector Builder app pour App description.
4. Saisissez http://localhost:8080 pour les URI de redirection. Vous modifierez cette valeur ultérieurement.
5. Vérifiez Web API pour Which API/SDKs are you planning to use?
6. Cochez la case Conditions d'utilisation du développeur.
7. Cliquez sur Save pour créer l'application.

Application Spotify.

Créer un projet de connecteur

 

Lancer le Connector Builder

1. Cliquez sur le menu à côté de votre nom pour lancer Connector Builder.

Lancez le Concepteur de connecteurs.

Créer un projet de connecteur

1. Cliquez sur le signe ➕ dans le panneau de gauche pour créer un projet de connecteur.
2. Entrez Spotify pour le Connector name.
3. Saisissez Spotify connector pour le champ Connector description (description du connecteur).
4. Cliquez sur Enregistrer pour créer le projet.

Projet de connecteur Spotify.

Flux de connecteur et authentification

Flux de connecteurs

Le connecteur que vous allez créer comporte trois flux :

• httpHelper : gère toutes les authentifications et les requêtes HTTP pour le connecteur.
• authPing : vérifie l’état de la connexion.
• List User Albums (Répertorier les albums de l’utilisateur): répertorie les albums Spotify actuels des utilisateurs (documentation de l’API).

Authentification

L’authentification est l’endroit où vous définissez les paramètres requis pour créer une connexion sécurisée au service API.

Lorsqu'un utilisateur final crée une connexion à votre service, la boîte de dialogue Nouvelle connexion recueille les informations d'authentification spécifiques.

Il existe trois types d'authentification :

• Basic: utilise le nom d'utilisateur et le mot de passe.
• OAuth 2.0 bsp;: octroie un accès limité aux ressources à un tiers. Vous pouvez utiliser les types d'octroi Authorization Code ou Client Credential dans un connecteur.
• Personnalisé: utilise la clé API ou un autre processus d'authentification.

Vous allez configurer une connexion OAuth pour Spotify.

Créer une authentification pour l'API Spotify

Créer une connexion OAuth

1. Faites défiler vers le bas et cliquez sur Set up authentication sur la page Overview pour créer une connexion.
2. Sélectionnez Oauth 2.0 dans la liste Type d’authentification.
3. Sélectionnez Authorization Code (Code d’autorisation) dans le champ Grant Type (Type d’autorisation).
4. Entrez https://accounts.spotify.com pour l'URL de base.
5. Entrez /authorize pour le Authorize Path.
6. Entrez /api/token pour le Token Path.
7. Laissez le champ Refresh Token Path vide.

Création d’une connexion.

Mettez à jour l'URI de redirection dans l'application Spotify

1. Copiez le lien sous Redirect URI. Il s'agit de l'URL de rappel.
2. Retournez à l'application Spotify que vous avez créée précédemment. Cliquez sur Settings.
3. Au bas de la page, cliquez sur Modifier.
4. Dans la section URI de redirection, cliquez sur Supprimer pour supprimer l'URI actuel.
5. Collez l'URI from the Connector Builder et cliquez sur Add.
6. Cliquez sur Save pour enregistrer les modifications.

Configurez l'ID client et le secret client

1. Retournez à Connector Builder.
2. Conservez Developer pour la Client Ownership.
3. Copiez le Client ID de l'application Spotify et collez-le dans le champ Client ID de la connexion.
4. Copiez le Client Secret de l'application Spotify (cliquez sur View client secret) et collez-le dans le champ Client Secret de la connexion.

Configurer l'étendue

L’API Get Current User’s Playlists (Obtenir les listes de lecture de l’utilisateur actuel) nécessite l’étendue playlist-read-private. Les étendues définissent les ressources auxquelles l’application a accès. 

Création d'une nouvelle connexion (suite).

1. Dans la section Scopes, cliquez sur Add Scope.
2. Entrez playlist-read-private pour le Name.
3. Le côté droit affiche l’aperçu de la connexion. Cliquez sur Save (enregistrer) pour créer la connexion.

Informations de connexion Spotify.

Créer un flux pour effectuer des requêtes HTTP

Vous allez créer un flux nommé httpHelper.

Le flux httpHelper est un flux système qui gère l'authentification et les requêtes HTTP pour le connecteur. Le flux httpHelper est un flux d'assistance; d'autres flux peuvent l'appeler. Le flux a :

• Plusieurs entrées.
• Cartes de fonction pour créer des informations de requête, d’en-tête et de corps de requête.
• La carte HTTP – Raw Request pour effectuer un appel à une API.
• Plusieurs sorties.

Créer un flow

1. Ouvrez la page Flows.
2. Pour créer un flux, cliquez sur + New Flow.
3. Cliquez sur Unnamed dans le coin supérieur gauche pour nommer le flux.
4. Saisissez httpHelper pour le champ Nom du flux.
5. Entrez Ce flux gère toutes les requêtes d’authentification et HTTP pour le connecteur pour la Description.
6. Cochez l'option Save all data that passes through the Flow? option.
7. Pour enregistrer le flux, cliquez sur Save.

Configurer les entrées de flux

1. Cliquez sur Ajouter un événement et choisissez Flux d'assistance.
2. Ajoutez les champs suivants sur la carte Helper Flow :
   • relative_url (type : Text (texte)).
   • request_method (Text).
   • query (Objet).
   • headers (Object (objet)).
   • body (Object (objet)).

Le flux httpHelper avec les entrées

flux httpHelper.

Configurer l'URL de l'API

Le connecteur peut prendre en charge plusieurs points de terminaison Spotify. L'URL de base reste la même et l'URL relative change. Vous devez combiner les deux valeurs en une URL complète.

1. Ajoutez la carte Text – Concatenate (texte – concaténer) après la carte Helper Flow (flux d’assistance).
2. Saisissez https://api.spotify.com le champ text 1.
3. Connectez relative_url au champ text 2.
4. Renommez le champ de sortie de la carte.
   • Pour modifier la carte, cliquez sur ⚙️ > Modifier la carte.
   • Pour renommer le champ de sortie, cliquez sur son icône ✏️ et définissez le nom sur full_url.

Configuration de l'URL.

Configurez les en-têtes

Vous devez configurer deux paramètres d'en-tête :

• Content-Type: application/json.
• Authorization: Bearer access_token.

La connexion que vous configurez acquerra le jeton d'accès. Le champ Connexion répertorie la valeur du Jeton d'accès dans la première carte.

Pour configurer l'en-tête Authorization bsp;:

1. Ajoutez la carte Text – Compose (texte – composer).
2. Tapez Bearer à l'intérieur de la carte.
3. Connectez le jeton d’accès après la chaîne Porteur (ajoutez un espace entre les chaînes).
4. Renommez le champ output de la carte Compose en bearer.

Pour configurer l’en-tête Content-Type :

1. Ajoutez la carte Object – Construct .
2. Créez un champ Content-Type et saisissez la valeur application/json.
3. Créez un champ Authorization et, pour la valeur, connectez le champ bearer de la carte Compose.
4. Renommez le champ output (sortie) en headers_auth.

Vous devez fusionner les en-têtes Content-Type (type de contenu) et Authorization (autorisation) avec tous les en-têtes qu’un utilisateur Workflows pourrait fournir.

1. Ajouter la carte Objet – Fusionner.
2. Connectez le champ headers de la première carte au champ object 1.
3. Connectez headers_auth de la carte Construct au champ object 2.
4. Renommez le champ output en merged_headers.

flux httpHelper avec cartes d'en-têtes.

Effectuer l’appel d’API

1. Ajoutez la carte HTTP – Raw Request.
2. Créez les connexions suivantes :
   • full_url au champ url sur la carte Raw Request.
   • request_method à la method sur la carte Raw Request.
   • merged_headers au champ headers sur la carte Requête brute.
   • query de la première carte vers le champ query.
   • body au champ body.

Configurez les sorties de flux

1. Connectez les champs statusCode, headers et body de la carte HTTP – Raw Request à la carte Flow Control – Return.
2. Remplacez le type de champ body par Object.

Flux httpHelper final :

flux httpHelper.

Tester le flux

1. Cliquez sur Exécuter pour tester le flux.
2. Sélectionnez New connection dans la liste Test Connection.
3. Entrez Spotify dans le champ Nom.
4. Saisissez Spotify connection (Connexion Spotify) pour le champ Description.
5. Cliquez sur Create. Une fenêtre contextuelle vous demandera de vous connecter à Spotify et d'autoriser l'application que vous avez créée (Workflows Connector Builder) à accéder à vos informations de playlist.
6. Saisissez /v1/me/playlists dans le champ relative_url.
7. Saisissez GET pour le champ request_method.
8. Cliquez sur Exécuter pour tester le flux.

Créer un flux pour vérifier une connexion valide

Vous allez créer un flux nommé _authPing. Un flux _authPing est un flux système utilisé par la plateforme pour appeler une API et vérifier l'autorisation valide.

Cette action sert de contrôle de validation et s'exécute lorsque vous authentifiez le connecteur pour la première fois, ajoutez de nouveaux connecteurs ou ouvrez des flux.

Créer un flow

1. Revenir à la vue du projet de connecteur.
2. Cliquez sur + New Flow depuis la page Flows.
3. Cliquez sur Add event, et sélectionnez l'événement Authping.
4. Pour enregistrer le flux, cliquez sur Sans nom dans le coin supérieur gauche.
5. Saisissez _authping pour le champ Name (nom).
6. Saisissez Connection health check (Vérification de l’état de la connexion) pour la description.
7. Cochez l'option Save all data that passes through the Flow? option.
8. Cliquez sur Save.

_authping flow.

Ajouter des cartes de contrôle de l'état de la connexion

1. Cliquez sur Add function et sélectionnez la carte Error Handling – If Error.
2. Dans le bloc Try (essayer) (automatiquement sélectionné), cliquez sur ➕, puis sur function (fonction) (icône de calculatrice) et sélectionnez la carte Flow Control – Call Flow (contrôle de flux – appeler le flux).
3. Sur la carte Call Flow, cliquez sur Choose Flow.
4. Sélectionnez le flow httpHelper, puis cliquez sur Choose.

Le flux ressemble à ceci :

flux _authping avec la carte Call Flow.

Ce flux appelle le flux httpHelper pour vérifier que la connexion au service fonctionne. Vous devez utiliser un point de terminaison d'API qui nécessite une authentification.

Remarque: l'équipe Okta Workflows recommande une requête avec la plus petite taille de réponse. Par exemple, certaines API ont un point de terminaison /me pour obtenir des informations sur l'utilisateur connecté.

L’API Spotify possède un point de terminaison /me que vous pouvez utiliser dans ce flux.

Terminez la configuration de la carte Call Flow :

1. Entrez /v1/me pour relative_url.
2. Saisissez GET pour le champ request_method (méthode de requête).
3. Laissez les champs query, headers et body vides.
4. Connectez le champ Connection de la première carte au champ Connection de la carte Call Flow.

Appel du point de terminaison /me.

Pour créer des sorties sur la carte Call Flow bsp;:

1. Cliquez à l'intérieur de la zone Click or drag to create et créez les champs de sortie suivants :
   • statusCode (type Number).
   • headers (Object (objet)).
   • body (Object (objet)).

Carte de flux d'appel avec sorties.

Ensuite, vous allez configurer un message lorsque la connexion fonctionne et un message lorsque la connexion ne fonctionne pas.

Pour configurer un message lorsqu'une connexion fonctionne :

1. Cliquez sur le ➕ après la carte Call Flow à l'intérieur de la carte If Error et sélectionnez la carte Flow Control – Assign.
2. Ajoutez un champ message et définissez-le sur la valeur The connection is successful dans la carte Control – Assign .

Créer des sorties pour la carte If Error  :

1. Cliquez sur View Outputs dans la carte If Error (coin supérieur droit). La carte ouvre une section où vous définissez les sorties de la carte.
2. Cliquez à l’intérieur du champ et créez deux sorties :
   • statusCode (code d’état).
   • message.
3. Créez les connexions suivantes :
   • statusCode de la carte Call Flow vers le premier sous-champ de statusCode.
   • message de la carte Assign au premier sous-champ du message.

Les cartes ressemblent à ceci :

Configurez un message lorsque la connexion fonctionne.

Pour configurer un message lorsque la connexion ne fonctionne pas :

1. En utilisant la liste où il est écrit Try, passez au bloc If Error sur la carte If Error.
2. Ajoutez deux champs à l'objet Error :
   • statusCode (type Text).
   • description (Text (Texte)).
3. Cliquez sur ➕ à droite de l’objet Error (Erreur) à l’intérieur du bloc If Error (Si erreur) et ajoutez la carte Text – Concatenate (Texte – Concaténer).
4. Créez les connexions suivantes :
   • description de l'objet Erreur vers le champ text 1.
   • Entrez : (deux-points) dans le champ text 2.
   • Cliquez pour créer un troisième champ et connectez message de Error à celui-ci.

Ensuite, vous connecterez le message à la sortie de la carte If Error (en cas d’erreur).

1. Cliquez sur Afficher les sorties sur la carte Si Erreur.
2. Créez les connexions suivantes :
   • statusCode de Erreur au deuxième sous-champ de statusCode.
   • output de Concatenate vers le deuxième sous-champ de message.

Les cartes ressemblent à ceci :

Configurez un message lorsque la connexion ne fonctionne pas.

Configurer la sortie du flux

La carte Flow Control – Return Status comporte deux champs : working et serviceResponse. Vous utiliserez les informations disponibles dans ce flux pour définir ces champs.

1. Cliquez sur ➕ après la carte If Error et ajoutez la carte True/False – Compare.
2. Connectez statusCode de la sortie de la carte If Error au champ value a.
3. Entrez 200 pour le champ value b.
4. Renommez le champ de sortie result en working.

Configuration du code d'état de la connexion.

Si l'appel à l'API réussit (200), la connexion fonctionne.

1. Cliquez sur ➕ après la carte Vrai/Faux – Comparer et ajoutez la carte Objet – Construire.
2. Créez deux champs sur la carte Construct :
   • statusCode (type Text).
   • body (Texte).
3. Créez les connexions suivantes :
   • statusCode de la sortie de la carte If Error vers le champ statusCode sur la carte Construct.
   • message de la sortie de la carte If Error au champ body sur la carte Construct.
4. Renommez le champ output sur la carte Construct en serviceResponse.

Configuration de la réponse de l'état de la connexion.

Pour configurer les sorties du flux :

1. Connectez le champ working de la carte Compare au champ working de la carte Return Status.
2. Connectez serviceResponse de la carte Construct au champ serviceResponse sur la carte Return Status.

Le flow complet :

Le flux _auththing complet.

Tester le flux

1. Enregistrer le flow.
2. Cliquez sur Run.
3. Sélectionnez la connexion Spotify et cliquez sur Run.

Créer une action pour répertorier les albums de l’utilisateur

Dans cette section, vous allez créer une action de connecteur pour le point de terminaison Get Current User’s Playlists.

Créer un flow

1. Retournez à la vue du projet du connecteur.
2. Cliquez sur + New Flow pour créer un nouveau flux.
3. Cliquez sur Unnamed dans le coin supérieur gauche pour nommer le flux.
4. Entrez List Current User Albums pour le Nom du flux.
5. Entrez List current user Spotify albums pour la Description.
6. Cochez l'option Save all data that passes through the Flow? option
7. Cliquez sur Enregistrer pour enregistrer le flux.

Configurer le flux en tant qu’action

Un flux d'action effectue un appel d'API de service.

Pour configurer ce flux en tant que flux d'action :

1. Cliquez sur Add event puis sur le type d'événement Action.

Le flux d'action n'a pas besoin d'entrées, car le point de terminaison Get Current User’s Playlists n'a pas d'entrées.

Le flux ressemble à ceci :

Action Répertorier les albums de l'utilisateur actuel.

Appeler l'API Spotify

Dans cette étape, vous ferez un appel à l'API Spotify.

1. Ajoutez la carte Flow Control – Call Flow.
2. Cliquez sur Choose Flow, sélectionnez le flux httpHelper et cliquez sur Choose.
3. Saisissez /v1/me/playlists dans le champ relative_url.
4. Saisissez GET pour le champ request_method (méthode de requête).
5. Connectez le champ Connection de la première carte au champ Connection de la carte Call Flow.
6. Créez trois sorties pour la carte Call Flow :
   • statusCode (type Number).
   • headers (Object (objet)).
   • body (Object (objet)).

Carte Call Flow.

Créer des sorties de flux

Créez les sorties suivantes sur la carte Flow Control – Return Outputs :

1. Cliquez sur Add Outputs.
2. Ouvrez Ajouter un groupe et sélectionnez Ajouter un groupe statique.
3. Créer trois sorties :
   • Code d'état (type Nombre).
   • Headers (En-têtes) (Object (Objet)).
     • Supprimez l'entrée de clé vide.
   • Body (corps) (Object (objet)).
     • Supprimez l'entrée de clé vide.
4. Cliquez sur Apply (Appliquer) pour enregistrer les sorties.
5. Connectez les données de la carte Call Flow à la carte Return Outputs :
   • statusCode au champ Status Code.
   • headers au champ Headers.
   • body au champ Body.

La fin du flux ressemble à ceci :

Le flux d’action complet Liste des albums de l’utilisateur actuel.

Tester le flux

1. Cliquez sur Exécuter pour tester le flux.
2. Sélectionnez la connexion Spotify dans la liste Test Connection et cliquez sur Exécuter.

Déployer le connecteur`

Activer les flux

Les flux doivent être activés avant le déploiement.

1. Retournez à la page Flows (Flux).
2. Activez les trois flux.

Mettre à jour les paramètres du connecteur

Dans cette section, vous entrerez des informations supplémentaires dans les paramètres.

1. Revenir à la vue principale du projet.
2. Ouvrez la page Aperçu.
3. Cliquez sur Edit dans la section Settings.
4. Télécharger et définissez l'icône Spotify pour le connecteur.
5. Modifiez la Accent Color si vous le souhaitez.
6. Saisissez les informations d'URL de la documentation utilisateur et d'E-mail de contact pour le support.
7. Cliquez sur Enregistrer pour enregistrer toutes les modifications.

Paramètres du connecteur.

Déployer le connecteur

Pour déployer le connecteur :

1. Passez à l’onglet Deployment (déploiement).
2. Cliquez sur Créer une version test.
3. Sélectionnez les trois points verticaux sous Actions pour une version de test que vous avez créée, puis sélectionnez Deploy Version.

Vous verrez le connecteur déployé dans la section Private deployment.

Déploiement du connecteur.

Vous êtes prêt à utiliser le connecteur dans un flux.

Utilisation du connecteur dans un flow

Dans cette étape, vous utiliserez l'action de connecteur dans un flux.

Connecteur Spotify.

Ajouter la carte

Action du connecteur Spotify.

1. Créez un nouveau flux dans Workflows.
2. Cliquez sur Add app action et sélectionnez le connecteur Spotify. Vous pouvez également le rechercher.
3. Sélectionnez l'action Spotify – List Current User Albums.

Créer une connexion

1. Cliquez sur + New Connection et suivez les étapes pour créer une connexion pour Spotify.

Spotify – Action de liste des albums de l’utilisateur actuel.

Test

1. Testez la carte ou le flux.

Test du flux.

Félicitations

Beau travail!

Vous avez créé un connecteur pour Spotify qui exploite OAuth pour l'authentification. 

Ressources

📚 Building a Custom Connector in Okta Workflows, a Video Series.

📖 Documentation du générateur de connecteurs Okta Workflows.

🍫 Obtenez de l'aide auprès de spécialistes Workflows pendant les heures de bureau communautaires hebdomadaires.

📺 Apprenez grâce aux vidéos Workflows.

🛟 Obtenez de l'aide auprès du support : discutez d'un sujet Workflows ou posez une question.

🙋🏻‍♀️ Obtenez de l'aide de la communauté : rejoignez le canal #okta-workflows sur MacAdmins Slack.