Las Named Credentials simplifican el código Apex de Callouts mediante configuración estándar

La mayoría de los proyectos de Salesforce requieren Callouts para integrarse e invocar servicios en sistemas externos. Habitualmente estos Callouts, requieren de código Apex, el cual, puede volverse costoso, voluminoso y engorroso de mantener si desconocemos las Named Credentials.

Retos en el uso de Callouts

Pero la codificación de una llamada a un Web Service, supone ciertos retos:

1. Si el servicio requiere autenticación, ¿Cómo evitamos divulgar las credenciales a un equipo desarrollo que puede cambiar regularmente? (Esto supone un reto y quizás un problema legal cuando estas credenciales permiten el acceso a datos sensibles)
2. Si el sistema destino, el que ofrece el servicio, tiene distintos endpoints en función del entorno (DES, INT,…): ¿Cómo podemos invocar el servicio en varios entornos sin duplicar/modificar el código ni provocar retrabajos?
3. Si cada usuario debe utilizar unas credenciales distintas, ¿Debo almacenar estas credenciales y añadir código Apex para su utilización?
   1. Además será necesario almacenar todas las credenciales en el mismo lugar para que sean accesibles, con lo que seguramente acabaré haciendo públicas unas credenciales que quiero mantener privadas (punto anterior).
4. Si el servicio destino utiliza diferentes mecanismos de autenticación, o cambian a lo largo de la vida de nuestro proyecto, por ejemplo de Basic Authentication a oAuth2:
   1. ¿Debemos modificar nuestro código y provocar retrabajo?
5. Si el servicio destino ofrece autenticación oAuth2:
   1. ¿No existe un mecanismo para evitar, el gestionar todo el diálogo y los tokens entre los sistemas?

La respuesta a estos retos es Named Credentials, una funcionalidad nativa en Salesforce, disponible a partir de Spring ’15.

Named Credentials es la herramienta adecuada para simplificar las Callouts en Salesforce

Ventajas asociadas a las Named Credentials

1. Permite que el código Apex para los Callouts contenga las direcciones de los endpoints, evitando su hardcoding, y además, no requiere de uso de otros mecanismos como global settings, etc.
2. Esto comporta que la gestión de los endpoints en diferentes ubicaciones del sistema destino (DES, INT, PRE, PRO, etc.) se realice sin ningún cambio en nuestro código Apex
3. Análogamente sucede con las credenciales, ya que nos permite la gestión de credenciales, fuera de nuestro código Apex, sin necesidad de usar otros mecanismos, tanto si la autenticación es Basic Authentication ó OAuth2.
4. Permite limitar que usuarios pueden invocar estos servicios, y además,  podemos indicar credenciales únicas para cada usuario. Esto comporta por ejemplo, que el sistema destino ofrezca diferentes niveles de servicio (costes) según el usuario/perfil.
5. Permite el uso de un certificado, para que el tráfico entre Salesforce y el sistema destino sea cifrado, definido también por configuración en nuestra ORG.

Por tanto: el uso de Named Credentials, reduce el volumen de código Apex necesario y el impacto en nuestros despliegues, permitiendo la gestión de los parámetros que pueden cambiar, en elementos de configuración y de manera externa al código, que permanece inmutable independientemente de la autenticación usada.

Ejemplos reales de Named Credentials de menos a más

Veamos varios ejemplos de uso de Named Credentials, partiendo del caso más simple al más complejo. Para ello, utilizamos una aplicación Java (Spring Boot) desplegada en Heroku, que ofrece 2 endpoints:

• https://echowebservice.herokuapp.com/HolaConAuth: endpoint configurado para  Basic Auth (username/password)
• https://echowebservice.herokuapp.com/HolaSinAuth: no requiere autenticación

Ambos servicios, retornan las  cabeceras HTTP recibidas en las peticiones (las generadas por Salesforce para invocar el servicio). De esta manera podemos evaluar, que invocaciones realiza Salesforce.

Todo el código está disponible en este repo de Bitbucket (https://bitbucket.org/estevegraells/forcegraells-namedcredentials). Gracias a Spring Boot, en pocas líneas de código conseguimos exponer estos servicios.

En Salesforce he creado 3 objetos:

• Visualforce para la invocación de los servicios
• Un Controller para gestionar las peticiones de la VF
• Una clase tipo helper donde se realizan las llamadas a los servicios

1: Uso de Named Credentials sin autenticación

Este es el ejemplo más simple, pero ya podemos observar varias ventajas de las Named Credentials.

A continuación se muestra la configuración, donde los campos son auto-explicativos.

Configuración de una Named Credential para acceso al servicio que no requiere Autorización

La parte de código Apex relevante es la siguiente, donde se observa que:

• el código no hace referencia a un endpoint concreto
• si el endpoint cambiara, el código seguiría siendo el mismo

Código Apex que realiza la invocación al Web Service sin autenticación

En el resultado obtenido, que son las cabeceras HTTP generadas por Salesforce no hay autenticación, dado que así lo hemos configurado y solo aparecen cabeceras de información de la petición:

Respuesta obtenida del Servicio Echo

2: Uso de Named Credentials con autenticación

Cuando el endpoint a invocar requiere autenticación, las Named Credentials, ofrecen 2 opciones:

• Named Principal: implica que las credenciales de autenticación serán las mismas para todas las invocaciones a realizar
• Per user: implica que cada usuario tendrá sus propias credenciales de autenticación, bajo su Profile de Salesforce

Tipos de Autenticación Disponibles para Named Credentials

2.1: Uso de Named Credentials con autenticación Named Principal

Cuando seleccionamos Named Principal, decidimos que todas las invocaciones se realizarán con las mismas credenciales, ya sea mediante Username/Password o mediante oAuth2:

La configuración para el caso de autenticación con Username y Password es muy simple:

Configuración de una Credential mediante Named Principal con autenticación Username y Password

Las 3 últimas opciones, indican a Salesforce:

1. Que genere la cabecera estándar de Basic Authorization (ahorrándonos así el tener que calcular el B64, crear la cabecera e incluirla)
2. Permitir el uso de los campos Username, Password, etc., en las cabeceras HTTP,por parte del código Apex
3. Análogamente para el Body del mensaje

Las 2 últimas opciones permiten construir Headers y Body ad-hoc, para aquellos endpoints que no implementan Basic Auth estándar sino con adaptaciones.

Además podemos usar un certificado, habiéndolo definido previamente, para el cifrado de las comunicaciones.

El código Apex requerido es idéntico al anterior, aunque esta vez, la petición se realizará mediante autenticación Basic Auth (username y password):

Código Apex para petición con Named Principal

El resultado es:

Respuesta obtenida del Servicio Echo para la invocación autenticada con Named Principal – notar la cabecera Basic Auth generada e incluida por Salesforce de forma transparente

2.2: Uso de Named Credentials con autenticación por Usuario

Si la invocación del servicio debe diferenciarse por usuario, es decir, cuando se realice la invocación al servicio, serán las credenciales definidas para ese usuario las que usará Salesforce para autenticarse,  deben seguirse los siguientes pasos de configuración:

1. Al definir la Named Credential, indicar la opción Per User
   1. Introducir en ese apartado unos valores cualesquiera para Username y Password, ya que no se utilizan en la invocación
2. Crear un Permission Set o modificar el Profile para asignar la capacidad de usar esa Named Credential
   1. Realizar un Assigment de ese Permission Set a los usuarios
3. Para cada uno de los usuarios, acceder a sus Settings, y definir en el apartado  Authentication Settings for External Systems, las credenciales que usará ese usuario, cuando se use la Named Credential creada

Las siguientes capturas de pantalla, clarifican la configuración de los pasos importantes:

Definición d el Permission Set para las Named Credentials

Definición del Auth Settings External System donde definimos las credenciales reales que  usará Salesforce para contruir la cabecera de autenticación, y por tanto para autenticarse en el endpoint remoto

El código Apex de invocación vuelve a ser idéntico:

Código Apex para petición con autenticación con credenciales por usuario

Cuyo resultado es:

Respuesta obtenida del Servicio Echo para la invocación autenticada con credenciales por usuario

3: Uso de Named Credentials con oAuth

El caso más complejo y donde las Named Credentials vuelven a simplificar nuestros desarrollos y mantenimiento es en el caso de uso que los servicios requieran autenticación oAuth.

El diálogo para la autenticación mediante oAuth no es simple, dado que se requiere la gestión de tokens, la intervención de un servidor tercero:

Usando Named Credentials nuestro código queda aislado de todas estas llamadas de «infraestructura», y únicamente con la configuración del oAuth Provider en Salesforce, conseguiremos el uso de este mecanismo de autenticación.

Conclusiones

Resumiendo las Named Credentials:

• aportan un nivel de abstracción sobre el uso de los Callouts (aislando el código de los cambios de los endpoints)
• permiten una gestión por configuración tanto de los endpoints como de las credenciales
  • evitan la divulgación de credenciales
• permite autenticación «global» ó granular por usuario, sin modificaciones sobre el código
• podemos cambiar o combinar diferentes métodos de autenticación, por ejemplo en entornos distintos, sin modificar el código

Por su simplicidad, es una característica muy a tener en cuenta en el uso de Callouts.

Enlaces interesantes

• Documentación oficial de Named Credentials: https://developer.salesforce.com/docs/atlas.en-us.210.0.apexcode.meta/apexcode/apex_callouts_named_credentials.htm
• Artículos interesantes:
  • http://martijnschwarzer.com/integration/using-named-credentials-simplify-apex-callouts-part-1/
  • http://blog.lkatney.com/2016/01/14/named-credentials-a-turning-point-for-callouts-in-apex/
  • http://blog.enree.co/2016/03/salesforce-apex-lets-play-with-named.html
• Definición del Permission Set para Named Credential: https://help.salesforce.com/articleView?id=named_credentials_permsets_profiles.htm&type=0
• Entrada en StackExchange donde se describe el uso de las credenciales en los Settings del usuario en lugar de las que se utilizan en la definición de la Named Credential: https://salesforce.stackexchange.com/questions/102484/use-of-named-credentials-seem-to-be-tied-to-external-data-source
• Repo en Bitbucket con todo el código: https://bitbucket.org/estevegraells/forcegraells-namedcredentials

Anuncio publicitario