Tutorial de Okta Workflows: Crea un conector para la API de Spotify (con OAuth 2.0)

Este tutorial te enseñará cómo crear un conector para la API de Spotify que utiliza OAuth para la autenticación utilizando el Constructor de conectores de Okta Workflows.

• Conector para la API de Spotify
• Crea un conector para la API de Spotify
• Recursos

Conector para la API de Spotify

Crearás un conector para Spotify API porque utiliza OAuth para la autenticación. Este tutorial te enseñará cómo crear un conector en el Connector Builder que utiliza OAuth para la autenticación.

La autenticación OAuth es un tema avanzado. Si eres nuevo en el Creador de conectores, lee y completa otros artículos y tutoriales de esta serie: 

• Understanding Okta Workflows Connectors.
• Tutorial de Okta Workflows: crea un conector para la API de OpenWeather.

Si desea llamar a la API de Spotify utilizando la tarjeta API Connector, lea este artículo de la base de conocimientos:

• Cómo llamar a la API de Spotify desde Okta Workflows (Ejemplo de autenticación OAuth).

Este KB te enseñará cómo configurar la conexión OAuth y llamar a la API de Spotify utilizando la tarjeta API Connector.

Crea un conector para la API de Spotify

En esta sección, construirá un conector a Spotify en el Connector Builder.

El Constructor de conectores utiliza flujos y tarjetas (acción, función) de Workflows para crear un conector.

Un conector consta de varios flujos:

• Un flujo para realizar solicitudes HTTP.
• Un flujo para verificar que la autenticación al servicio esté funcionando.
• Uno o más flujos de acción. Cada flujo de acción llama al endpoint de la API de un servicio.
• Flujo de acción personalizado para permitir llamar a cualquier endpoint de la API en el servicio (consulte el tutorial Crear un conector para la API de OpenWeather).

Primero, necesitas una cuenta de Spotify antes de empezar a construir el conector.

Configura una cuenta y una aplicación de Spotify

Crea una cuenta de Spotify

1. Crea una cuenta de Spotify, si no tienes una.

Crear una aplicación

Después de implementar un flujo de autorización, la aplicación proporcionará un token de acceso para realizar llamadas a la API de Spotify.

1. Para crear una aplicación, vaya a su Dashboard, haga clic en Crear una aplicación.
2. Ingrese Workflows Connector Builder para el Nombre de la aplicación.
3. Ingrese Workflows Connector Builder app para App description.
4. Introduce http://localhost:8080 en Redirect URIs (URI de redireccionamiento). Cambiarás este valor más adelante.
5. Verifica Web API para ¿Qué API/SDKs planeas usar?
6. Marca la casilla de verificación Developer Terms of Service.
7. Haz clic en Save (Guardar) para crear la aplicación.

Aplicación de Spotify.

Crear un proyecto de conector

 

Inicia el Connector Builder

1. Haz clic en el menú junto a tu nombre para iniciar el Connector Builder.

Lanza el Connector Builder.

Crear un proyecto de conector

1. Haz clic en el ➕ en el panel izquierdo para crear un proyecto de conector.
2. Ingresa Spotify para el Nombre del conector.
3. Ingresa Conector de Spotify para la Descripción del conector.
4. Haga clic en Guardar para crear el proyecto.

Proyecto del conector de Spotify.

Flujos del conector y autenticación

Flujos de conectores

El conector que construirá tiene tres flujos:

• httpHelper: administra todas las solicitudes de autenticación y HTTP para el conector.
• authPing: comprueba el estado de la conexión.
• List User Albums: enumera los álbumes actuales de Spotify de los usuarios (documentación de la API).

Authentication

La autenticación es donde define los parámetros necesarios para crear una conexión segura al servicio API.

Cuando un usuario final crea una conexión a su servicio, el diálogo Nueva conexión recopila los detalles de autenticación específicos.

Hay tres tipos de autenticación:

• Basic: utiliza nombre de usuario y contraseña.
• OAuth 2.0: otorga acceso limitado a los recursos a un tercero. Puede utilizar los tipos de concesión Authorization Code o Client Credential en un conector.
• Custom: utiliza la clave API u otro proceso de autenticación.

Configurarás una conexión de OAuth para Spotify.

Crear autenticación para la API de Spotify

Crear una conexión OAuth

1. Desplácese hacia abajo y haga clic en Set up authentication en la página Overview para crear una conexión.
2. Seleccione Oauth 2.0 de la lista Auth Type.
3. Selecciona Código de autorización del Tipo de concesión.
4. Ingresa https://accounts.spotify.com para la URL base.
5. Ingrese /authorize para la ruta de autorización.
6. Ingresa /api/token para la ruta del token.
7. Deje el campo Ruta del token de actualización en blanco.

Creación de una conexión.

Actualiza el URI de redireccionamiento en la aplicación de Spotify

1. Copia el enlace en Redirect URI. Esta es la URL de retorno de llamada.
2. Regrese a la aplicación de Spotify que creó anteriormente. Haga clic en Settings.
3. En la parte inferior de la página, haz clic en Edit.
4. En la sección Redirect URIs, haz clic en Remove para eliminar el URI actual.
5. Pegue el URI from the Connector Builder y haga clic en Add.
6. Haga clic en Save para guardar los cambios.

Configurar el Client ID y Client Secret

1. Regrese al Creador de conectores.
2. Mantenga Developer para Client Ownership.
3. Copia el Client ID de la aplicación de Spotify y pégalo en el campo Client ID en la conexión.
4. Copia el Client Secret de la aplicación de Spotify (haz clic en View client secret) y pégalo en el campo Client Secret en la conexión.

Configurar el scope

La API Get Current User’s Playlists requiere el alcance playlist-read-private. Los scopes definen los recursos a los que la aplicación tiene acceso. 

Creación de una nueva conexión (continuación).

1. En la sección Scopes, haga clic en Add Scope.
2. Ingresa playlist-read-private para el Nombre.
3. El lado derecho muestra la vista previa de la conexión. Haz clic en Save para crear la conexión.

Información de conexión de Spotify.

Cree un flujo para realizar solicitudes HTTP

Creará un flujo llamado httpHelper.

El httpHelper es un flujo del sistema que gestiona la autenticación y las solicitudes HTTP para el conector. El flujo httpHelper es un flujo auxiliar; otros flujos pueden llamarlo. El flujo tiene:

• Varias entradas.
• Tarjetas de función para crear información de consulta, encabezado y cuerpo de la solicitud.
• La tarjeta HTTP – Raw Request para hacer una llamada a una API.
• Varias salidas.

Crear un flujo

1. Abre la página Flows.
2. Para crear un flujo, haz clic en + New Flow.
3. Haz clic en Unnamed en la esquina superior izquierda para nombrar el flujo.
4. Ingrese httpHelper para el Nombre del flujo.
5. Ingrese Este flujo gestiona todas las solicitudes de autenticación y HTTP para el conector para la Descripción.
6. Marque la casilla Save all data that passes through the Flow? opción.
7. Para guardar el flujo, haga clic en Guardar.

Configurar las entradas de flujo

1. Haz clic en Add event y elige Helper Flow.
2. Añada los siguientes campos en la tarjeta Helper Flow:
   • relative_url (tipo: Text [Texto]).
   • request_method (Text).
   • query (Object).
   • headers (Object).
   • body (Object).

El flujo httpHelper con entradas

Flujo httpHelper.

Configurar la URL de la API

El conector puede admitir múltiples puntos de conexión de Spotify. La URL base sigue siendo la misma, y la URL relativa cambiará. Necesitas combinar los dos valores en una URL completa.

1. Agrega la tarjeta Texto – Concatenar después de la tarjeta Helper Flow.
2. Ingresa https://api.spotify.com el campo text 1.
3. Conecte relative_url al campo text 2.
4. Cambia el nombre del campo de salida de la tarjeta.
   • Para editar la tarjeta, haga clic en ⚙️ > Edit card.
   • Para cambiar el nombre del campo output, haga clic en su icono ✏️ y establezca el nombre a full_url.

Configurando la URL.

Configurar los encabezados

Debe configurar dos parámetros de encabezado:

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

La conexión que configuró adquirirá el token de acceso. El campo Connection lista el valor del Access Token en la primera tarjeta.

Para configurar el encabezado Authorization:

1. Agregue la tarjeta Text – Compose.
2. Escribe Bearer dentro de la tarjeta.
3. Conecte el Access Token después de la cadena Bearer (agregue un espacio entre las cadenas).
4. Cambia el nombre del campo output de la tarjeta Compose a bearer.

Para configurar el encabezado Content-Type:

1. Agrega la tarjeta Object – Construct.
2. Crea un campo Content-Type y para el valor ingresa application/json.
3. Cree un campo Authorization, y para el valor conecte el campo bearer de la tarjeta Compose.
4. Cambia el nombre del campo output a headers_auth.

Necesita fusionar los encabezados Content-Type y Authorization con cualquier encabezado que un usuario de Workflows pueda proporcionar.

1. Agrega la tarjeta Objeto – Fusionar.
2. Conecta el campo headers (encabezados) de la primera tarjeta al campo object 1 (objeto 1).
3. Conecta headers_auth de la tarjeta Construct al campo object 2.
4. Cambia el nombre del campo de **output** a *merged_headers*.

Flujo httpHelper con tarjetas de encabezados.

Realice la llamada a la API

1. Agregue la tarjeta HTTP – Raw Request.
2. Cree las siguientes conexiones:
   • full_url al campo url en la tarjeta Raw Request.
   • request_method al method en la tarjeta Raw Request.
   • merged_headers al campo headers en la tarjeta Raw Request.
   • query de la primera tarjeta al campo query.
   • body al campo body.

Configurar salidas de flujo

1. Conecte los campos statusCode, headers y body de la tarjeta HTTP – Raw Request a la tarjeta Flow Control – Return.
2. Cambie el tipo de campo body a Object.

Flujo final de httpHelper:

Flujo httpHelper.

Probar el flujo

1. Haz clic en Run para probar el flujo.
2. Selecciona New connection de la lista Test Connection.
3. Ingrese Spotify para el campo Name.
4. Ingresa Conexión de Spotify para el campo Description.
5. Haz clic en Create (Crear). Verás una ventana emergente que te pedirá que inicies sesión en Spotify y permitas que la aplicación que has creado (Workflows Connector Builder) acceda a la información de tu lista de reproducción.
6. Ingresa /v1/me/playlists para el campo relative_url.
7. Ingrese GET para el campo request_method.
8. Haz clic en Run para probar el flujo.

Cree un flujo para verificar una conexión válida

Creará un flujo llamado _authPing. Un flujo _authPing es un flujo del sistema utilizado por la plataforma para llamar a una API y verificar la autorización válida.

Esta acción actúa como una comprobación de validación y se ejecuta cuando autentica por primera vez el conector, agrega nuevos conectores o abre flujos.

Crear un flujo

1. Regrese a la vista del proyecto del conector.
2. Haz clic en + Nuevo Flujo desde la página Flujos.
3. Haz clic en Add event y selecciona el evento Authping.
4. Para guardar el flujo, haga clic en Unnamed en la esquina superior izquierda.
5. Introduce _authping en Name (Nombre).
6. Ingresa Comprobación del estado de la conexión para la descripción.
7. Marque la casilla Save all data that passes through the Flow? opción.
8. Haz clic en Save (Guardar).

flujo _authping.

Agrega tarjetas de verificación del estado de la conexión

1. Haz clic en Add function, y selecciona la tarjeta Error Handling – If Error.
2. En el bloque Try (seleccionado automáticamente), haz clic en ➕, luego en function (icono de calculadora) y selecciona la tarjeta Flow Control – Call Flow.
3. En la tarjeta Call Flow, haga clic en Choose Flow.
4. Seleccione el flujo httpHelper y haga clic en Choose.

El flujo se ve así:

flujo _authping con la tarjeta Call Flow.

Este flujo llama al flujo httpHelper para verificar que la conexión al servicio esté funcionando. Debes usar un *endpoint* de API que requiera autenticación.

Nota: El equipo de Okta Workflows recomienda una solicitud con el tamaño de respuesta más pequeño. Por ejemplo, algunas API tienen un *endpoint* /me para obtener información sobre el usuario que ha iniciado sesión.

La API de Spotify tiene un /me punto final que puedes usar en este flujo.

Termina de configurar la tarjeta Call Flow:

1. Ingrese /v1/me para la relative_url.
2. Ingrese GET para el request_method.
3. Deje los campos query, headers y body en blanco.
4. Conecte el campo Connection de la primera tarjeta al campo Connection en la tarjeta Call Flow.

Llamar al punto de conexión /me.

Para crear salidas en la tarjeta Call Flow:

1. Haz clic dentro del área Click or drag to create y crea los siguientes campos de salida:
   • statusCode (tipo Number).
   • headers (Object).
   • body (Object).

Tarjeta de flujo de llamada con salidas.

A continuación, configurará un mensaje cuando la conexión esté funcionando y un mensaje cuando la conexión no esté funcionando.

Para configurar un mensaje para una conexión en funcionamiento:

1. Haz clic en el ➕ después de la tarjeta Call Flow (Flujo de llamada) dentro de la tarjeta If Error (Si hay error) y selecciona la tarjeta Flow Control – Assign (Control de flujo - Asignar).
2. Agregue un campo message y establézcalo en el valor La conexión es exitosa en la tarjeta Control – Assign .

Cree salidas para la tarjeta If Error:

1. Haga clic en View Outputs en la tarjeta If Error (esquina superior derecha). La tarjeta abre una sección donde se definen las salidas de la tarjeta.
2. Haz clic dentro del campo y crea dos salidas:
   • statusCode.
   • mensaje.
3. Cree las siguientes conexiones:
   • statusCode de la tarjeta Call Flow al primer subcampo de statusCode.
   • message de la tarjeta Assign al primer subcampo de message.

Las tarjetas tienen este aspecto:

Configura un mensaje cuando la conexión esté funcionando.

Para configurar un mensaje cuando la conexión no esté funcionando:

1. Usando la lista donde dice Try, cambie al bloque If Error en la tarjeta If Error.
2. Agrega dos campos al objeto Error:
   • statusCode (tipo Text).
   • description (Text).
3. Haga clic en ➕ a la derecha del objeto Error dentro del bloque If Error y agregue la tarjeta Text – Concatenate.
4. Cree las siguientes conexiones:
   • description del objeto Error al campo text 1.
   • Introduzca : (dos puntos) en el campo text 2.
   • Haz clic para crear un tercer campo y conecta el message de Error a él.

A continuación, conectarás el mensaje a la salida de la tarjeta If Error.

1. Haga clic en View Outputs en la tarjeta If Error.
2. Cree las siguientes conexiones:
   • statusCode de Error al segundo subcampo de statusCode.
   • output de Concatenate al segundo subcampo del message.

Las tarjetas tienen este aspecto:

Configure un mensaje cuando la conexión no funcione.

Configurar la salida del flujo

La tarjeta Flow Control – Return Status tiene dos campos: working y serviceResponse. Utilizará la información disponible en este flujo para configurar estos campos.

1. Haga clic en ➕ después de la tarjeta If Error y agregue la tarjeta True/False – Compare.
2. Conecta statusCode desde la salida de la tarjeta If Error al campo value a.
3. Ingrese 200 para el campo value b.
4. Cambia el nombre del campo de salida result a working.

Configuración del código de estado de la conexión.

Si la llamada a la API se realiza correctamente (200), la conexión funciona.

1. Haga clic en ➕ después de la tarjeta True/False – Compare y agregue la tarjeta Object – Construct.
2. Cree dos campos en la tarjeta Construct:
   • statusCode (tipo Text).
   • body (Texto).
3. Cree las siguientes conexiones:
   • statusCode de la salida de la tarjeta If Error al campo statusCode en la tarjeta Construct.
   • message de la salida de la tarjeta If Error al campo body en la tarjeta Construct.
4. Cambie el nombre del campo output en la tarjeta Construct a serviceResponse.

Configurando la respuesta del estado de la conexi n.

Para configurar las salidas de flujo:

1. Conecta working de la tarjeta Compare a el campo working en la tarjeta Return Status (Estado de retorno).
2. Conecte serviceResponse de la tarjeta Construct al campo serviceResponse en la tarjeta Return Status.

El flujo completo:

El flujo completo de _auththing.

Probar el flujo

1. Guardar el flujo.
2. Haz clic en Run.
3. Selecciona la conexión de Spotify y haz clic en Run (Ejecutar).

Crea una acción para listar los álbumes del usuario

En esta sección, crearás una acción de conector para el *endpoint* Obtener listas de reproducción del usuario actual.

Crear un flujo

1. Regresa a la vista del proyecto del conector.
2. Haz clic en + New Flow (+ Nuevo flujo) para crear un nuevo flujo.
3. Haz clic en Unnamed en la esquina superior izquierda para nombrar el flujo.
4. Ingresa List Current User Albums para el Nombre del flujo.
5. Ingresa List current user Spotify albums para la Description.
6. Marque la casilla Save all data that passes through the Flow? option
7. Haga clic en Save para guardar el flujo.

Configure el flujo como una acción

Un flujo de acción realiza una llamada a la API de servicio.

Para configurar este flujo como un flujo de acción:

1. Haz clic en Add event y luego en el tipo de evento Action.

El flujo de acción no necesita entradas ya que el punto de conexión Get Current User’s Playlists no tiene entradas.

El flujo se ve así:

Acción Listar Álbumes del Usuario Actual.

Llama a la API de Spotify

En este paso, harás una llamada a la API de Spotify.

1. Agrega la tarjeta Flow Control – Call Flow.
2. Haz clic en Choose Flow, selecciona el flujo httpHelper y haz clic en Choose.
3. Ingresa /v1/me/playlists para el campo relative_url.
4. Ingrese GET para el request_method.
5. Conecte el campo Connection de la primera tarjeta al campo Connection en la tarjeta Call Flow.
6. Cree tres salidas para la tarjeta Call Flow:
   • statusCode (tipo Number).
   • headers (Object).
   • body (Object).

Tarjeta Call Flow.

Crear salidas de flujo

Crea las siguientes salidas en la tarjeta Control de flujo - Devolver salidas:

1. Haga clic en Add Outputs.
2. Abra Add group y seleccione Add Static Group.
3. Crea tres salidas:
   • Status Code (tipo Número).
   • Headers (Objeto).
     • Eliminar la entrada de clave vacía.
   • Body (Object).
     • Eliminar la entrada de clave vacía.
4. Haga clic en Apply para guardar las salidas.
5. Conecta los datos de la tarjeta Call Flow a la tarjeta Return Outputs (Salidas de retorno):
   • statusCode al campo Status Code.
   • headers al campo Headers.
   • body al campo Body.

El final del flujo se ve así:

El flujo completo de acción List Current User Albums.

Probar el flujo

1. Haz clic en Run para probar el flujo.
2. Selecciona la conexión Spotify de la lista Test Connection y haz clic en Run.

Implementar el conector`

Activar flujos

Los flujos deben estar activados antes de la implementación.

1. Regresa a la página Flows.
2. Active los tres flujos.

Actualizar la configuración del conector

En esta sección ingresará información adicional en la configuración.

1. Regresa a la vista principal del proyecto.
2. Abra la página Overview.
3. Haz clic en Editar en la sección Ajustes.
4. Descargue y configure el icono de Spotify para el conector.
5. Cambia el Accent Color si lo deseas.
6. Ingrese la información de User Documentation URL y Support Contact Email.
7. Haz clic en Save para guardar todos los cambios.

Configuración del conector.

Implementar el conector

Para implementar el conector:

1. Cambia a la pestaña Deployment.
2. Haga clic en Create test version.
3. Selecciona los tres puntos verticales debajo de Acciones para una versión de prueba que hayas creado y selecciona Desplegar versión.

Verás el conector implementado en la sección Implementación privada.

Implementación del conector.

Estás listo para usar el conector en un flujo.

Usando el conector en un flujo

En este paso, utilizarás la acción del conector en un flujo.

Conector de Spotify.

Agrega la tarjeta

Acción del conector de Spotify.

1. Cree un nuevo flujo en Workflows.
2. Haga clic en Add app action y seleccione el conector Spotify. También puede buscarlo.
3. Selecciona la acción Spotify – List Current User Albums.

Crear una conexión

1. Haz clic en + New Connection y sigue los pasos para crear una conexión para Spotify.

Acción Spotify – Listar álbumes del usuario actual.

Probar

1. Prueba la tarjeta o el flujo.

Probando el flujo.

Felicidades

¡Buen trabajo!

Creó un conector para Spotify que aprovecha OAuth para la autenticación. 

Recursos

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

📖 Okta Workflows Connector Builder documentation.

🍫 Obtenga ayuda de los especialistas de Workflows durante el horario de oficina comunitario semanal.

📺 Aprenda de los videos de Workflows.

🛟 Obtenga ayuda del soporte técnico: analice un tema de Workflows o haga una pregunta.

🙋🏻‍♀️ Obtenga ayuda de la comunidad: únase al canal #okta-workflows en MacAdmins Slack.