Generación de tokens de acceso para las API del lado del servidor generating-access-tokens-for-server-side-apis

Algunas arquitecturas dependen de la realización de llamadas a Adobe Experience Manager (AEM) as a Cloud Service desde una aplicación alojada en un servidor fuera de la infraestructura de AEM. Por ejemplo, una aplicación móvil llama a un servidor, que luego realiza solicitudes de API a AEM as a Cloud Service.

Use AEM as a Cloud Service Developer Console para crear una cuenta técnica de servidor a servidor OAuth. Su aplicación intercambia su ID de cliente y su secreto de cliente por un token de acceso mediante la concesión client_credentials de Adobe Identity Management Services (IMS). No se requiere JWT, clave privada o certificado firmado.

El flujo de servidor a servidor the-server-to-server-flow

Los usuarios con una función de administrador de organización de IMS que también sean miembros del perfil de producto Usuarios de AEM o Administradores de AEM en el Autor de AEM pueden crear una cuenta técnica. El secreto de cliente solo se muestra al usuario que lo crea en el momento de la creación. Un usuario con la función de administrador del entorno de AEM as a Cloud Service puede ver los detalles de la cuenta, que no incluyen el secreto de cliente.

El flujo de servidor a servidor incluye estos pasos:

Crear una cuenta técnica y recuperar sus credenciales fetch-the-aem-as-a-cloud-service-credentials

Para revisar los detalles de un secreto más adelante, abre el menú de filas del secreto de cliente y selecciona Ver. El cuadro de diálogo de credenciales muestra el extremo de IMS, los ámbitos, el ID de cliente, el correo electrónico de cuenta técnica, el ID secreto y el estado de revocación. No muestra el valor secreto del cliente.

Instalación de las credenciales del servicio de AEM en un servidor que no sea de AEM install-the-aem-service-credentials-on-a-non-aem-server

Hacer que las credenciales solo estén disponibles para la aplicación del lado del servidor que llama a AEM. Utilice un administrador secreto u otro mecanismo de almacenamiento con control de acceso.

No coloque un secreto de cliente en código del lado del explorador, aplicaciones móviles, control de código fuente o registros. Trate los tokens de acceso como secretos también.

Solicitar un token de acceso de OAuth request-an-oauth-access-token

Enviar una solicitud HTTPS POST a https://<imsEndpoint>/ims/token/v3. El imsEndpoint de su JSON de credencial es un nombre de host de IMS. Por ejemplo, ims-na1.adobelogin.com usa https://ims-na1.adobelogin.com/ims/token/v3. Utilice el nombre de host proporcionado en las credenciales, incluido el nombre de host de fase al utilizar las credenciales de fase.

Use Content-Type: application/x-www-form-urlencoded e incluya estos campos de formulario en el cuerpo de la solicitud:

Codifique con URL cada valor de formulario. Enviar secretos en el cuerpo de la solicitud, no en la dirección URL o la cadena de consulta.

La respuesta incluye access_token, token_type y expires_in. Use access_token para llamar a AEM. El valor expires_in es la duración del token en segundos. Utilice ese valor en lugar de suponer una hora de caducidad fija.

Almacene en caché y reutilice el token de acceso hasta que se aproxime a la caducidad y, a continuación, solicite un nuevo token con las mismas credenciales de cliente. Esta concesión no requiere un intercambio JWT ni un token de actualización.

Ejemplo de autenticación de Node.js nodejs-authentication-example

Para obtener una implementación mínima de servidor a servidor de OAuth, consulte el ejemplo de la biblioteca de cliente de la API de AEM-CS. Utiliza las API de Node.js integradas y requiere Node.js 18 o posterior, sin dependencias adicionales.

El ejemplo espera las credenciales dentro de un objeto integration. El archivo aem-s2s-credentials.json descargado de AEM Developer Console contiene las credenciales sin este contenedor. Ajuste su contenido antes de utilizarlo con el ejemplo, por ejemplo, con jq:

jq '{integration: .}' aem-s2s-credentials.json > downloaded_integration.json

Como alternativa, edite el archivo para que todo su contenido se convierta en el valor de un campo integration de nivel superior. Desde una extracción del repositorio de ejemplo, ejecute:

node oauth-s2s-cli.js downloaded_integration.json

Para uso programático, el ayudante de OAuth acepta el objeto ajustado como requestAccessToken(credentials). Utiliza el nombre de host de IMS, el ID de cliente, el secreto de cliente y los ámbitos dentro de integration.

Mantenga el archivo de credenciales privado. La CLI imprime un token de acceso. No envíe su salida a registros compartidos ni la publique. El LÉAME del ejemplo también muestra cómo utilizar el token en una solicitud de API de AEM.

Llamar a la API de AEM calling-the-aem-api

Incluya el token de acceso en el encabezado Authorization de las solicitudes a su entorno de AEM as a Cloud Service, usando el valor Bearer <access_token>.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  "https://author-p<program-id>-e<environment-id>.adobeaemcloud.com/content/dam.json"

Utilice el nombre de host para el entorno y el nivel al que accede la aplicación. Llamar solo a los recursos a los que la cuenta técnica tiene autorización para acceder.

Establezca los permisos adecuados para el usuario de la cuenta técnica en AEM set-the-appropriate-permissions-for-the-technical-account-user-in-aem

Para obtener más información acerca de los usuarios y grupos de IMS y AEM, consulte Compatibilidad con IMS.

Flujo de desarrollador developer-flow

Para las pruebas locales, los desarrolladores pueden generar un token de acceso de desarrollo directamente en AEM Developer Console sin crear una cuenta técnica de servidor a servidor OAuth. El token se puede utilizar para llamar a entornos de AEM a los que el desarrollador puede acceder. Utilice credenciales de servidor a servidor de OAuth, en lugar de un token de desarrollo local, para aplicaciones de servidor desatendidas.

Consulte las Directrices para desarrolladores para obtener los permisos necesarios para usar AEM Developer Console.

Generación del token de acceso generating-the-access-token

Llamar a la aplicación de AEM con un token de acceso call-the-aem-application-with-an-access-token

Use el token de acceso de desarrollo local como token de portador en el encabezado Authorization, tal como se describe en Llamar a la API de AEM.

Para un proyecto de AEM que se ejecute en el equipo local, no se necesita un token de acceso IMS.

Rotar secretos de cliente refresh-credentials

Las credenciales de servidor a servidor OAuth no requieren la renovación anual de certificados. Rotar los secretos del cliente periódicamente y siempre que se exponga un secreto. Cree un nuevo secreto, cambie sus aplicaciones a él y solo entonces revoque el secreto antiguo.

Crear y revocar secretos requiere los valores secretos que ha guardado. AEM Developer Console utiliza un secreto introducido solo para autenticar la solicitud con IMS y no la almacena.

Revocación de credenciales credentials-revocation

Revocar deshabilita un secreto seleccionado para nuevas solicitudes de token. Requiere el valor del secreto que se está revocando. La revocación puede tardar un tiempo en propagarse. No suponga que revocar un secreto invalida inmediatamente los tokens de acceso que ya se emitieron.

Eliminar de un secreto revocado elimina sus metadatos, como el ID secreto y el estado de revocación, de AEM Developer Console. No realiza una revocación de IMS independiente y no está disponible para secretos activos.

Eliminar una cuenta técnica delete-a-technical-account

Al eliminar una cuenta técnica, se revocan inmediatamente la cuenta y todos sus secretos de cliente en IMS. No se emiten nuevos tokens de acceso para ninguna credencial de la cuenta y las integraciones que la utilizan dejan de funcionar una vez que caducan sus tokens actuales. Para restaurar el acceso, debe crear una nueva cuenta técnica, actualizar las aplicaciones con sus credenciales y asignar de nuevo los permisos necesarios en AEM.

La eliminación de cuentas no se puede deshacer. Confirme solo después de comprobar qué aplicaciones dependen de la cuenta y no la utilice como paso de rotación secreto individual.

Migración de una integración basada en JWT migrate-a-jwt-based-integration

Para operaciones de certificado y clave privada en la cuenta antigua, consulte la guía heredada de JWT. No elimine la cuenta antigua antes de comprobar la integración de reemplazo.