API Integration
· docusign
· JWT
· JWT token
· OAuth 2.0
· rest api
· Technical Articles
Configuración de SAP PI para la autenticación JWT en las API de DocuSign
By s4pcademy
Estimados amigos de SAP
Durante la implementación del flujo de OAuth 2.0 JWT Grant en SAP PI REST, aprendí muchos entresijos al respecto y espero que a través de este blog tenga una mejor comprensión de qué esperar al configurar la autenticación JWT para las API que lo requieren.
Hay otro blog sobre la autenticación JWT de DocuSign para la integración en la nube, por lo que si necesita detalles de configuración sobre el mismo en el contexto de la integración en la nube, puede consultar este excelente blog:
Cuando obtuve el requisito, el blog anterior no estaba allí, así que me aseguré de incluir pasos y observaciones detallados y las razones detrás de ellos en esta publicación de blog.
Objetivo:
Comprender e implementar un escenario completo de extremo a extremo para la configuración del adaptador SAP PI REST donde usaremos la configuración OAuth2 para usar la autenticación de concesión JWT. Estoy seguro de que esta publicación de blog podrá arrojar luz sobre la autenticación basada en JWT, que tiene una documentación disponible muy limitada.
Lo que ya deberías saber antes de esta publicación de blog:
(i) Comprensión de cómo funcionan las API. (Métodos HTTP, encabezados, parámetros, etc.)
(ii) Comprensión del adaptador REST.
(iii) Pruebas de API con Postman.
Para obtener una explicación teórica e información más detallada sobre JWT, puede consultar la página de inicio de jwt.io o debajo de la página de DocuSign:
https://developers.docusign.com/platform/auth/jwt/
Intentaré centrarme más en la implementación aquí. Empecemos.
- JWT Grant ¿Para qué sirve?
Es un mecanismo OAuth 2.0 que se utiliza para otorgar un token de acceso a las integraciones de servicios, que desean aprovechar una integración de API. - Consumir una API
El consumo de una API requiere los siguientes pasos en todos los tipos de integración.
(a) Inicie sesión en el portal de desarrolladores de DocuSign.
(b) Crear una aplicación que genere valores clave únicos.
(c) Usar claves de API generadas u otros parámetros que identifiquen esta aplicación de manera única.
(d) Inicie sesión en el cliente y configure estos valores de clave API para la autenticación.
(e) Implementar la configuración para usar la API en tiempo real. En el contexto de DocuSign, navegaremos por cada uno de estos pasos. - Desglose del flujo JWT
(a) Otorgar consentimiento para realizar llamadas en nombre del usuario registrado (desde el paso 2.i). Este paso genera un código de autorización.
(b) La aplicación (del paso 2.b) solicita el token de acceso.
(c) Si el paso 3.a aún no se completó, enrutará la llamada de regreso al paso 3.a, de lo contrario, validará los parámetros pasados. Si los parámetros son válidos, devolverá el código de acceso. De lo contrario, devolverá errores relevantes. - Usando el token de acceso
El token de acceso obtenido en el paso 3 se utilizará para autenticar las API y completar las llamadas con éxito. En la configuración de SAP PI REST, la selección está disponible en cuanto a cómo desea usar el «token de acceso OAuth 2.0 como:», puede seleccionar «Encabezado HTTP» allí, como se mostrará en pasos posteriores. - Configurar en DocuSign(a) Cree una cuenta de desarrollador en DocuSign o se la proporcionará el administrador de su organización. (b) Vaya a «Mi aplicación y claves» como se muestra a continuación:
(c) Esto lo llevará a una página de inicio donde se enumeran los detalles de su cuenta junto con la aplicación que ha creado. Haga clic en el botón señalado para crear una nueva aplicación para nuestro servicio de integración.
(d) Crear la aplicación
(f) Desplácese hacia abajo hasta la sección Integración de servicios, donde puede cargar su propio par de claves RSA o generar uno nuevo. Generaremos uno nuevo aquí.
(g) Verá que se genera un nuevo par de claves, copie los valores haciendo clic en los botones resaltados como se muestra a continuación y cópielos en un bloc de notas (o guárdelos de forma segura para su uso posterior).
Haga clic en el botón «Guardar» en la parte inferior y listo.
(i) Como estamos utilizando la concesión individual, en este caso debemos otorgar el consentimiento para que esta aplicación se autentique en nuestro nombre (el del usuario que ha iniciado sesión).
Para hacer esto, debemos llamar a la siguiente URL y dar nuestro consentimiento. Se le pedirá que inicie sesión en caso de «no iniciar sesión» o «sesión obsoleta».
La URL es:
https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20spring_read%20spring_write%20interpretación&id_cliente={Clave de integración}&redirect_uri={redirigir_uri}
Observación #1: el parámetro de consulta de alcance debe incluir «suplantación de identidad» como se muestra arriba, de lo contrario obtendrá «consentimiento requerido” error más tarde (consulte el paso 3.b) a pesar de una ejecución exitosa del siguiente paso.
Haga clic en «PERMITIR ACCESO» y será redirigido a la página siguiente.
Siempre que el código se genere en la URL como se ve a continuación, esto es lo esperado. Confirma que el consentimiento ahora se ha otorgado con éxito en nombre del usuario que inició sesión. Ahora su integración en SAP PI puede usar los identificadores de esta aplicación para obtener «access_token» con el flujo de concesión de JWT para la autenticación final.
- Configuración SAP PI (Canal REST)
(a) Usaremos el adaptador REST aquí para consumir las API, ya que tiene toda la configuración para satisfacer nuestras necesidades en el contexto de OAuth 2.0 y JWT Grant.
(b) Cree un canal de comunicación REST y seleccione el campo como se muestra a continuación:
(c) Los campos resaltados a continuación son los que necesitamos para la configuración de autenticación JWT aquí.
Ahora abajo están todos los valores para cada campo:
emisor (iss) Clave de integración para la aplicación DocuSign Asunto (sub) ID de usuario del usuario registrado en el portal DocuSign Developer Audiencia (audiencia) en la documentación oficial de DocuSign es cuenta-d.docusign.com Caducidad (exp) no tiene ninguna relación con el proceso de autorización, ya que el vencimiento del token lo establece la aplicación DocuSign y no el cliente. estableceremos como 3600 aquí. Algoritmo de firma JWT puede usar varios tipos de algoritmos de firma, pero según la documentación de DocuSign, usaremos RSA256 Alcance Básicamente, se trata de la autorización/permiso a nivel de entidad otorgado al usuario para realizar ciertas operaciones, estas serán proporcionadas por el usuario funcional e implementadas por el administrador de la organización para su usuario. Observación #2: Para el algoritmo de firma JWT, usaremos el par de claves RSA generado en el paso 5.f y estas claves se instalarán en Almacén de claves NWA para uso en la configuración del canal REST
(d) Ahora completaremos toda la información para el paso (c) del paso 5.
Observación #3: Es posible que hayas notado que el campo de alcance está en blanco aquí. La razón de esto es el hecho de que, por alguna razón, el «alcance» era una reclamación que no se trató como tal cuando los valores se configuraron aquí y la configuración no pudo usar los valores del alcance para generar el token.Para configurar el alcance, utilizaremos la configuración de «Parámetros adicionales de OAuth 2.0» como se muestra a continuación:
Observación #4: Todos los valores de alcance configurados aquí se deben usar en el paso «otorgar consentimiento» en el paso 5; de lo contrario, el token de acceso generado, aunque sea válido, no podrá obtener ni actualizar las entidades relevantes en DocuSign.
Configuración de URL de REST
Como ya seleccionó «Encabezado HTTP» como opción para usar el token de OAuth 2.0 en la configuración, como se muestra en el paso 6.d, no necesita configurar nada específico para el parámetro «Autorización» en la pestaña «Encabezados HTTP de REST». canal.
Configuración de encabezado HTTP
Termina el resto de la configuración y listo.
(f) Puede ejecutar una prueba de extremo a extremo o hacer ping al canal para validar la configuración. A continuación se muestra una muestra de ping exitosa:
(g) Para las pruebas de extremo a extremo, he creado un escenario simple REST (SAP PI) a REST (DocuSign API). No entraré en la configuración de iFlow aquí.
A continuación se muestra la captura del cartero para probar la misma interfaz.
Solo para aclarar el campo «creado» en la respuesta, como se ve arriba, es la marca de tiempo de cuando se creó mi cuenta en DocuSign el año pasado. Esta API de DocuSign solo obtiene información de la cuenta del usuario.Y aquí están los registros de una llamada exitosa a la API de DocuSign.
- algunas notas:
(a) Todo lo marcado en «Observación» son los problemas que encontré, así que quería asegurarme de que no se pierda esas configuraciones.
(b) Si hay algún problema con la configuración de OAuth, obtendrá «no se pudo recuperar el token de OAuth» en algún lugar del ping o procesamiento de mensajes en el paso 6.viii. Vuelva a visitar la configuración si nota este problema.
(c) Asegúrese de haber importado el certificado HTTPS en el almacén de claves del certificado de confianza de NWA también. El OAuth no funcionará sin él. El certificado de confianza debe ser de «URL del servidor de autorización» del paso 6.dConclusión:
En este blog, he tratado de transmitir una forma visualizada de comprender la configuración de OAuth 2.0 para el flujo de subvenciones de JWT. Hemos repasado:
– Comprender el flujo de subvenciones de JWT.
– Configuración de cosas en DocuSign (se darán pasos similares para otros socios API de terceros)
– Configuración del adaptador REST para consumir estas API. Junto con esto, he tratado de señalar los problemas y la observación y el cambio relevante que debe tener en cuenta para que la configuración funcione correctamente. Espero que este blog lo ayude con sus implementaciones a través de información más informada.Acción para el lector:
Puede hacer que esta configuración funcione para otras API de terceros también con una configuración similar. Asegúrese de probar primero las API en Postman para esta configuración, de modo que tenga menos problemas que solucionar cuando mueva la configuración al Adaptador REST.Las preguntas y comentarios son muy bienvenidos. Por favor, comparte, dale me gusta y sígueme para más publicaciones de este tipo si disfrutaste esta.
Gracias por leer.
