custom web experience with amazon q business

Experiencia web personalizada con Amazon Q Business

⚡ Si creó una nueva aplicación de Amazon Q Business a partir del 30 de abril de 2024, ahora puede configurar una interfaz de usuario personalizada siguiendo las instrucciones actualizadas que se proporcionan a continuación.

Nota: Las instrucciones proporcionadas en esta guía son específicas de Cognito, pero también deberían funcionar para otros proveedores de identidad (IdP) compatibles con OIDC 2.0 con ajustes menores.

Los clientes a menudo desean tener la capacidad de integrar funcionalidades personalizadas en la interfaz de usuario de Amazon Q, como manejar comentarios, usar colores y plantillas corporativos, inicio de sesión personalizado y reducir el cambio de contexto integrando la interfaz de usuario en una única plataforma. El repositorio de código mostrará cómo integrar una interfaz de usuario personalizada en Amazon Q utilizando Amazon Cognito para la autenticación de usuarios y el SDK de Amazon Q para invocar la aplicación de chatbot mediante programación, a través de la API chat_sync.

?‍ El flujo de trabajo incluye los siguientes pasos:

1. Primero, el usuario accede a la aplicación chatbot, que está alojada detrás de un balanceador de carga de aplicaciones.

2. Se solicita al usuario que inicie sesión con Cognito

3. La aplicación UI intercambia el token de Cognito con un token de IAM Identity Center con alcance para Amazon Q

4. Las aplicaciones de interfaz de usuario asumen una función de IAM y recuperan una sesión de AWS del Secure Token Service (STS), aumentada con el token del IAM Identity Center para interactuar con Amazon Q.

   • El flujo detallado del intercambio de tokens entre IAM Identity Center e Idp se explica en las siguientes publicaciones del blog.

   ? Blog 1

   ? Blog 2

5. Amazon Q utiliza la API ChatSync para llevar a cabo la conversación. Gracias a la sesión con reconocimiento de identidad, Amazon Q sabe con qué usuario está interactuando.

   • La solicitud utiliza los siguientes parámetros obligatorios.

     1. applicationId : el identificador de la aplicación de Amazon Q vinculada a la conversación de Amazon Q.

     2. userMessage : un mensaje de usuario final en una conversación.

   • Amazon Q devuelve la respuesta como un objeto JSON (detallado en la documentación de Amazon Q) y a continuación se muestran algunos atributos principales de la carga útil de la respuesta.

     1. systemMessage : un mensaje generado por IA en una conversación

     2. sourceAttributions : los documentos de origen utilizados para generar la respuesta de la conversación. En RAG (Generación de aumento de recuperación), esto siempre se refiere a uno o más documentos de bases de conocimientos empresariales que están indexados en Amazon Q.

Implementar esta solución

Requisitos previos:

Antes de implementar esta solución, asegúrese de tener configurados los siguientes requisitos previos:

• Una cuenta de AWS válida.
• Un rol de AWS Identity and Access Management (IAM) en la cuenta que tiene permisos suficientes para crear los recursos necesarios.
  Si tiene acceso de administrador a la cuenta, no es necesario realizar ninguna acción.
• Un certificado TLS creado e importado en AWS Certificate Manager (ACM).
  Para obtener más detalles, consulte Importación de un certificado.
  Si no tiene un certificado TLS público, siga los pasos de la siguiente sección para aprender cómo generar un certificado privado.
• Una aplicación de Amazon Q existente y en funcionamiento
• IAM Identity Center y cree algunos usuarios en Identity Center configurando su dirección de correo electrónico y nombre

Generar certificado privado

Si ya tiene un certificado TLS, puede omitir esta sección.
Sin embargo, si no tiene uno y desea continuar con la ejecución de esta demostración, puede generar un certificado privado asociado con un dominio usando el siguiente comando openssl:

 openssl req 
  -x509 -nodes -days 365 -sha256 
  -subj '/C=US/ST=Oregon/L=Portland/CN=sampleexample.com' 
  -newkey rsa:2048 -keyout key.pem -out cert.pem

aws acm import-certificate --certificate fileb://cert.pem --private-key fileb://key.pem

➡️ Tenga en cuenta que recibirá una advertencia de su navegador al acceder a la interfaz de usuario si no proporcionó un certificado TLS personalizado al iniciar AWS CloudFormation Stack. Las instrucciones anteriores le muestran cómo crear un certificado autofirmado, que puede usarse como respaldo, pero ciertamente no se recomienda para casos de uso de producción.

Debe obtener un certificado TLS que haya sido validado por una autoridad certificadora, importarlo a AWS Certificate Manager y hacer referencia a él al iniciar AWS CloudFormation Stack.

Si desea continuar con el certificado autofirmado (para fines de desarrollo), debería poder pasar la página de advertencia del navegador. Con Chrome, verá el mensaje de error "Su conexión no es privada" (NET::ERR_CERT_AUTHORITY_INVALID), pero al hacer clic en "Avanzado", debería ver un enlace para continuar.

Implemente esta solución:

Paso 1: Inicie la siguiente plantilla de AWS CloudFormation para implementar ELB, grupo de usuarios de Cognito, incluida la instancia EC2 para alojar la aplicación web.

Proporcione los siguientes parámetros para la pila

• Nombre de la pila : el nombre de la pila de CloudFormation (por ejemplo, AmazonQ-UI-Demo).

• AuthName : un nombre global único para asignar al grupo de usuarios de Amazon Cognito. Asegúrese de que su nombre de dominio no incluya palabras reservadas, como cognito, aws o amazon.

• CertificateARN : el CertificateARN generado en el paso anterior.

• IdcApplicationArn : ARN de la aplicación del cliente de Identity Center; manténgalo en blanco en la primera ejecución, ya que necesitamos crear el grupo de usuarios cognito como parte de esta pila para crear la aplicación IAM Identity Center con un emisor de token confiable.

• PublicSubnetIds : los ID de las subredes públicas que se pueden usar para implementar la instancia EC2 y el balanceador de carga de aplicaciones. Seleccione al menos 2 subredes públicas

• QApplicationId : el ID de la aplicación existente de Amazon Q.

• VPCId : el ID de la VPC existente que se puede utilizar para implementar la demostración.

? Una vez que la pila esté completa, copie la siguiente clave de la pestaña Salida.

Audiencia : Audiencia para configurar la aplicación del cliente en Identity Center

RoleArn : ARN del rol de IAM necesario para configurar el intercambio de tokens en Identity Center

TrustedIssuerUrl : punto final del emisor de confianza para configurar Identity Center

URL : la URL del balanceador de carga para acceder a la aplicación Streamlit.

Paso 2: crear una aplicación del Centro de identidad IAM

• Navegue hasta AWS IAM Identity Center y agregue una nueva aplicación administrada personalizada.

  Seleccione el tipo de aplicación -> luego seleccione OAuth2.0 -> Siguiente

  

  Si no puede encontrar la opción de crear una nueva aplicación administrada personalizada, habilite Organizaciones con IAM Identity Center.

• Proporcione un nombre y una descripción de la aplicación y seleccione la siguiente opción como se muestra en la imagen

  

• Ahora cree un emisor de tokens confiable

  

• En la URL del emisor -> proporcione la TrustedIssuerUrl del paso 1, proporcione un nombre del emisor y mantenga los atributos del mapa como Correo electrónico

  

• Luego regrese a la configuración de autenticación de la aplicación IAM Identity Center, seleccione el emisor de token confiable creado en el paso anterior [actualícelo si no lo ve en la lista] y agregue el reclamo Aud -> proporcione la audiencia del paso 1, luego haga clic Próximo

  

• En Especificar las credenciales de la aplicación, ingrese los roles de IAM -> proporcione RoleArn desde el Paso 1

  

• Luego revise todos los pasos y cree la aplicación.

• Una vez creada la aplicación, vaya a la aplicación y -> Usuarios y grupos asignados.

  

• Luego configure la aplicación confiable para la propagación de identidades, siga los pasos a continuación para Amazon Q como aplicaciones confiables para la propagación de identidades.

  

Paso 4: Una vez creada la aplicación IAM Identity Center, copie el ARN de la aplicación y navegue hasta Cloudformation para actualizar la pila creada anteriormente. Ingrese el ARN de la aplicación Identity Center en el parámetro IdcApplicationArn y ejecute la pila.

Paso 5: una vez que se complete la actualización, navegue hasta la pestaña de salida de Cloudformation para copiar la URL y abrir la URL en un navegador.

Paso 6: La aplicación Streamlit le pedirá que se conecte con Cognito . Para el primer intento de inicio de sesión, intente registrarse, use la misma identificación de correo electrónico y contraseña para el usuario que ya existe en IAM Identity Center.

⚡ Para eliminar la necesidad de aprovisionar usuarios tanto en el grupo de usuarios de Cognito como en el Centro de identidad, puede seguir el enlace a continuación para crear una segunda aplicación personalizada (SAML) en el Centro de identidad. Esta aplicación personalizada actuará como proveedor de identidad para el grupo de usuarios de Cognito.

? Video

? Instrucciones

Conéctese al EC2 a través de AWS Session Manager [Opcional]:

 sudo -i
cd /opt/custom-web-experience-with-amazon-q-business

Solución de problemas

Consulte SOLUCIÓN DE PROBLEMAS para obtener más información.

Seguridad

Consulte CONTRIBUCIÓN para obtener más información.

Licencia

Esta biblioteca tiene la licencia MIT-0. Ver el archivo de LICENCIA.