Arquitectura · Identidad de aplicación
Arquitectura de identidad de Cognito para operar WordPress
Trate Cognito como un subsistema de identidad, no solo como una pantalla de acceso: la autenticación del navegador, la federación, los grupos, el contexto de token y las credenciales AWS opcionales permanecen separados del contenido y las sesiones de WordPress.
Página WordPress → interfaz Gatey
↓ navegador
Amazon Cognito User Pool
├→ proveedores sociales / SAML / OIDC
├→ MFA + flujos de perfil
├→ grupos / contexto de token
└→ Identity Pool opcional
↓
API protegidas / acceso estático
Frontera de identidad
WordPress representa la experiencia; Cognito posee la identidad de la aplicación
Gatey proporciona la experiencia del frontend, mientras Cognito autentica a los usuarios y emite artefactos de identidad que otros servicios pueden validar. Así, el acceso funciona en WordPress dinámico o estático sin convertir la tabla de usuarios de WordPress en la fuente de identidad de la aplicación.
Navegador del visitante
→ autenticador Gatey
→ Cognito User Pool
├→ acceso / registro / MFA / perfil
├→ federación SAML / OIDC / social
└→ contexto de grupos y token
├→ API autorizadas mediante JWT
├→ credenciales IAM opcionales
└→ decisión del firmante para acceso estático protegido
Frontera de autorización Una autenticación correcta no concede acceso universal. Las API y los recursos estáticos protegidos deben aplicar sus propios scopes, políticas IAM o acceso firmado utilizando el contexto de identidad que proporciona Cognito.
Qué aprovisiona la plantilla
La pila de identidad incluye más que un User Pool. Este inventario muestra el cliente de navegador, las opciones de federación y dominio, los triggers de ciclo de vida, las credenciales AWS opcionales y los outputs que forman la frontera de identidad.
| Componente | Por qué existe | Decisión de diseño principal | Nota operativa |
|---|---|---|---|
| User Pool + App Client | Directorio principal y cliente OAuth para el acceso de WordPress desde el navegador | Sin client secret; cliente público compatible con código o SRP | La pila puede crearlo o conectarse a un pool existente según el modo de la plantilla. |
| Dominio personalizado opcional | Acceso con marca y callbacks OAuth | Certificado ACM y alias Route53 opcional cuando esté disponible la hosted zone | La propiedad de DNS y del certificado debe quedar explícita antes de producción. |
| Identity Pool | Intercambia usuarios Cognito autenticados por credenciales AWS cuando se necesitan API firmadas con IAM | Separar AuthenticatedRole de RegisteredRole | Útil para llamadas a API Gateway protegidas por IAM desde frontends estáticos. |
| Custom Email Sender | Sustituye correos simples de Cognito por plantillas HTML y flujos de marca | Las plantillas viven en S3; se usa SES cuando está configurado y Cognito puede ser fallback | Trate las plantillas como activos versionados, no como texto introducido en la consola. |
| Trigger Pre Sign-Up | Valida la calidad del registro antes de que el usuario entre en el pool | reCAPTCHA opcional, dominios de confianza y vinculación de IdP externos por correo | Los fallos deben ser claros para el frontend y estar suficientemente registrados. |
| Trigger Pre Token Generation | Proyecta la pertenencia a grupos en scopes del access token | Añadir scopes como sc.group.registered o sc.group.admin | Hace más declarativas las comprobaciones de scopes en API Gateway. |
| Trigger Post Confirmation | Mueve usuarios confirmados al grupo Registered | Procesar confirmaciones reales de registro, no cualquier evento de confirmación | Separa «autenticado» de «registrado para llamar a las API». |
| Outputs | Permiten que otras pilas y plugins consuman artefactos de identidad | Exponer IDs del pool y cliente, dominio, roles, grupos y ARN de funciones | Los outputs son el contrato entre esta pila y el resto de la plataforma. |
Modelo de tokens y autorización
Cognito expone varios artefactos de identidad, cada uno con una función distinta. Esta tabla separa autenticación del navegador, grupos, scopes, credenciales AWS temporales y autorización del servicio.
| Capa | Artefacto | Qué demuestra | Qué no debe hacer |
|---|---|---|---|
| Gatey / navegador | Tokens Cognito y estado local de autenticación | El usuario completó el flujo Cognito configurado | Guardar secretos en el servidor WordPress o transmitir contraseñas mediante PHP. |
| Grupos del User Pool | registered, admin o grupos específicos del proyecto | El usuario pertenece a un rol empresarial | Ser el único punto de aplicación durante la ejecución. |
| Scopes del access token | sc.group.<group> | El token contiene contexto de rol legible por la API | Sustituir la autorización backend cuando importa la propiedad del recurso. |
| Rol del Identity Pool | AuthenticatedRole o RegisteredRole | El navegador puede obtener credenciales AWS temporales para acciones permitidas | Conceder permisos amplios a nivel de cuenta. |
| Método de API Gateway | Scope de Cognito o autorización IAM | La ruta aplica la identidad en la frontera del servicio | Depender de botones ocultos o restricciones solo mediante CSS. |
Modos de fallo operativos
Los fallos de identidad suelen parecer problemas genéricos de acceso aunque la causa sea el correo, la federación, los scopes o DNS. Esta tabla vincula los síntomas con la frontera operativa que debe revisarse.
| Fallo | Síntoma visible | Causa probable | Dirección del runbook |
|---|---|---|---|
| reCAPTCHA rechaza el registro | El usuario no puede crear una cuenta | Site key o secreto incorrecto, token obsoleto, puntuación baja o action distinta | Revise la ruta del token en clientMetadata, el secreto SSM, el umbral y los logs de Lambda. |
| El correo personalizado no llega | No llega el correo de confirmación o contraseña | Identidad SES no verificada, sandbox, error al leer plantilla o FROM distinto | Revise identidad SES, logs de CloudWatch, clave S3 de la plantilla y fallback. |
| El acceso social crea usuarios duplicados | El mismo correo aparece bajo identidades de proveedor separadas | Vinculación del IdP externo desactivada o fallida | Revise logs de Pre Sign-Up y permisos AdminLinkProviderForUser. |
| La API se deniega tras iniciar sesión | El frontend autentica, pero la API devuelve 401/403 | Usuario fuera de Registered, scopes ausentes, rol sin asignar o authorizer incorrecto | Revise scopes, grupos, logs de Post Confirmation y authorizer de API Gateway. |
| Falla el dominio personalizado | Hosted UI o dominio de callback no resuelve | Región o validación del certificado, zona Route53 distinta o destino del alias | Valide certificado ACM, propiedad de la zona DNS y estado del dominio Cognito. |
Ruta de implementación
Construya la identidad alrededor de la frontera de la aplicación, no de una sesión WordPress
El trabajo operativo relevante comienza después de crear el User Pool: federación, ciclo de vida, autorización y configuración repetible.
- Defina quién posee la identidad — Mantenga WordPress centrado en contenido y presentación. Use Cognito cuando la misma identidad del visitante deba extenderse a páginas estáticas, API u otras superficies de aplicación.
- Configure las rutas necesarias de acceso y federación — Active mediante Cognito y Gatey únicamente los flujos de acceso, registro, MFA, perfil, proveedores sociales, SAML u OIDC que el proyecto realmente necesite.
- Asigne la identidad a permisos de ejecución — Use claims, scopes, grupos o credenciales IAM opcionales para que los servicios backend autoricen acciones independientemente de la visibilidad del frontend.
- Pruebe el ciclo de vida y los fallos — Verifique confirmación, recuperación de contraseña, MFA, acceso de proveedor, cambios de grupo, caducidad del token y denegación de API por separado del renderizado de páginas.
Cuándo debe Cognito poseer la capa de identidad de la aplicación
Buena opción
La identidad debe extenderse más allá de WordPress
- Los mismos usuarios necesitan acceder a un frontend estático o a páginas donde WordPress PHP no atiende la solicitud.
- La identidad del frontend debe autorizar API, recursos protegidos u otras superficies de la aplicación.
- La organización ya tiene o prevé requisitos de federación social, SAML u OIDC.
Conservar la autenticación nativa de WordPress
Las sesiones de WordPress pueden ser más sencillas cuando
- solo wp-admin o páginas dinámicas normales de WordPress necesitan usuarios autenticados.
- ninguna aplicación externa, API protegida o frontend estático necesita la misma identidad.
- los plugins existentes dependen directamente del usuario y la sesión de WordPress y no existe motivo empresarial para introducir otro subsistema.
Guías de problemas
Decisiones de identidad que respalda esta arquitectura
¿Cuándo debe Amazon Cognito sustituir a WordPress como capa de identidad?
Consulte Amazon Cognito como capa de identidad en lugar de WordPress. WordPress sigue siendo el CMS y Cognito posee la identidad de los visitantes para la aplicación más amplia.
¿Cómo conecto proveedores SAML u OIDC existentes?
Consulte Conectar WordPress con proveedores SAML y OIDC existentes. Cognito actúa como centro de federación y Gatey conserva una experiencia de acceso única en el frontend.
¿Cómo funciona en WordPress estático?
Consulte Añadir acceso a WordPress estático sin recuperar sesiones PHP. El acceso Cognito en el navegador sobrevive a la publicación estática porque no depende de una sesión PHP de WordPress.
¿En qué se diferencian los archivos estáticos protegidos y las API protegidas?
Para la entrega estática, consulte WordPress estático seguro con cookies firmadas de CloudFront. Las API deben validar de forma independiente JWT, IAM u otro mecanismo admitido.
Empiece por la decisión de identidad
Use Cognito cuando la identidad del visitante deba durar más que la solicitud de WordPress
Elija la guía de identidad de aplicación para la decisión principal o la guía SSO cuando el requisito central sea federarse con proveedores de identidad existentes.