Clientes de autenticación

En Jutro, se proporcionan dos clientes de autenticación: un cliente Okta nativo y un cliente de autenticación genérico OpenID Connect (OIDC).

Okta es un proveedor de identidad (IdP) que sigue el estándar OIDC, y el cliente nativo de Okta está diseñado para admitirlo específicamente. Puede usar el cliente OIDC genérico para autenticarse con cualquier otro IdP que admita el estándar de OIDC.

Funciones de clientes

Los clientes de autenticación de Jutro proporcionados en el paquete @jutro/auth ofrecen las siguientes funciones:

• Inicio de sesión en la aplicación.
• Cierre de sesión de la aplicación.
• Cuando se abre una nueva pestaña con la aplicación, se comparten los tokens.
• Cuando el usuario cierra sesión en una pestaña, se cierra la sesión en todas las demás.
• El cliente actualiza el token un número determinado de segundos antes de que caduque.
• El cliente coordina la actualización del token entre las pestañas.

Desde el punto de vista del desarrollador, existen algunas funciones más específicas:

• Compatibilidad con el flujo de código de autorización de OIDC con la extensión PKCE.
• Gestión de tokens como almacenamiento, recuperación y validación.
• Capacidad para definir ámbitos.
• Garantizar la seguridad.
• Manejo de errores.
• Acceso a la información de los usuarios.

Dependencia de autenticación opcional

La dependencia @jutro/auth ahora es opcional para los paquetes @jutro/router y @jutro/components. Sin embargo, ciertos componentes requieren que esto se agregue a las dependencias de la aplicación para utilizarlos. La siguiente lista de componentes requiere que se agregue @jutro/auth:

Componente	Importar desde
ApplicationRoot	@jutro/app
Avatar	@jutro/components
DropdownMenuAvatar	@jutro/components
DropdownMenuAvatarContent	@jutro/components
AppFloorPlan	@jutro/floorplan
MicroFrontend	@jutro/micro-frontends
SecureRoute	@jutro/router

Configuración

Toda la configuración se realiza usando variables de entorno de tiempo de ejecución. Las siguientes variables son obligatorias:

• Enable Jutro authorization client usage: REACT_APP_JUTRO_AUTH_ENABLED=true
• Select the client to use:
  • Okta client: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT=true
  • Generic OIDC client: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT=false
• Add IDP configuration variables:
  • REACT_APP_JUTRO_AUTH_ISSUER=https://{your-provider}.com/oauth2/{key}
  • REACT_APP_JUTRO_AUTH_CLIENT_ID={your client ID goes here}
  • REACT_APP_JUTRO_AUTH_REDIRECT_PATH=/auth/callback
  • REACT_APP_JUTRO_AUTH_SCOPE=openid,tenant_id,email,profile,offline_access
  • JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true
  • JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=true
• The native Okta client handles silent logins, but if you are using the Generic OIDC client and you are using this feature you will need to add two additional configuration variables:
  • REACT_APP_JUTRO_AUTH_SILENT_REDIRECT_PATH=/auth/silent/callback
  • REACT_APP_JUTRO_AUTH_SILENT_LOGIN_PATH=/auth/silent/login

Para obtener más información sobre los inicios de sesión silenciosos, consulte la documentación sobre inicio de sesión silencioso.

Si está utilizando una aplicación de inicio de Jutro, estas variables es todo lo que necesita para activar la autenticación. La lógica se maneja en la función start() de Jutro.

Tip: Algunas rutas abiertas

Si utiliza un AppFloorPlan con la autenticación habilitada, todas sus rutas son seguras. Si desea que ciertas rutas estén abiertas mientras que otras sean seguras, debe implementar su propio enrutador. Consulte nuestra documentación de autenticación personalizada para obtener más detalles.

Detección de OIDC (configuración de autoridad)

OpenID Connect (OIDC) define un mecanismo de detección que le permite configurar su aplicación sin la necesidad de conocer los terminales exactos de su IdP. El mecanismo de detección se basa en el terminal /.well-known/openid-configuration que devuelve un documento JSON con toda la información necesaria.

Para obtener más información, lea este artículo sobre la detección.

En los casos en los que el terminal de detección automática no funcione como desearía, necesita las siguientes variables de entorno de tiempo de ejecución para la configuración manual de la autoridad.

• REACT_APP_JUTRO_AUTH_AUTHORIZATION_ENDPOINT
• REACT_APP_JUTRO_AUTH_TOKEN_ENDPOINT
• REACT_APP_JUTRO_AUTH_REVOCATION_ENDPOINT
• REACT_APP_JUTRO_AUTH_END_SESSION_ENDPOINT
• REACT_APP_JUTRO_AUTH_USERINFO_ENDPOINT

Por ejemplo, es posible que deba configurar lo siguiente:

REACT_APP_JUTRO_AUTH_AUTHORIZATION_ENDPOINT=https://YOUR_DOMAIN/authorize
REACT_APP_JUTRO_AUTH_TOKEN_ENDPOINT=https://YOUR_DOMAIN/oauth/token
REACT_APP_JUTRO_AUTH_REVOCATION_ENDPOINT=https://YOUR_DOMAIN/oauth/revoke
REACT_APP_JUTRO_AUTH_END_SESSION_ENDPOINT=https://YOUR_DOMAIN/oidc/logout
REACT_APP_JUTRO_AUTH_USERINFO_ENDPOINT=https://YOUR_DOMAIN/userinfo

Warning: Si establece alguna de estas variables, tendrá que establecer todas las demás.

Configuración del método de actualización de tokens

Jutro ofrece dos métodos para la actualización de tokens: la renovación pasiva de tokens y el inicio de sesión silencioso (también conocido como renovación activa de tokens). Utilice las siguientes opciones de configuración para establecer el método de renovación de tokens:

Para la renovación pasiva de tokens, debe establecer la propiedad JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS en true.

JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true

Para el inicio de sesión silencioso, debe configurar una ruta de redireccionamiento y una ruta de inicio de sesión con este método.

REACT_APP_JUTRO_AUTH_SILENT_REDIRECT_PATH=/auth/silent/callback
REACT_APP_JUTRO_AUTH_SILENT_LOGIN_PATH=/auth/silent/login

Para obtener más información sobre los métodos de renovación de tokens y cómo configurarlos, consulte la sección sobre opciones de actualización de tokens.

Warning: No se pueden usar ambos métodos al mismo tiempo. Debe eliminar la opción de configuración JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS si desea utilizar el inicio de sesión silencioso.

Parámetros de consulta personalizados

Puede establecer los parámetros de consulta personalizados que desee aplicar en todas las solicitudes de inicio de sesión utilizando la variable de entorno REACT_APP_JUTRO_AUTH_LOGIN_QUERY_EXTRAS:

Note: El cliente OIDC genérico aporta compatibilidad para parámetros de consulta personalizados a las solicitudes de cierre de sesión. Puede definirlos mediante la variable de entorno REACT_APP_JUTRO_AUTH_LOGOUT_QUERY_EXTRAS.

Los valores que proporcione deben ser JSON válidos. Se analizarán y se agregarán al string de consulta de la solicitud de inicio o cierre de sesión.

Por ejemplo, puede agregar un parámetro prompt a la solicitud de autorización para forzar al usuario a iniciar sesión otra vez.

REACT_APP_JUTRO_AUTH_LOGIN_QUERY_EXTRAS={"prompt":"login"}

Tenga en cuenta que estas son variables de entorno de tiempo de ejecución, por ello, se aplican a todas las solicitudes de inicio de sesión y (si utiliza el cliente OIDC genérico) de cierre de sesión en la aplicación. Para agregar parámetros de consulta personalizados a una solicitud de inicio de sesión específica, consulte la sección inicio y cierre de sesión.

Tokens de cierre de sesión que se deben invalidar

A veces, necesitará invalidar solo algunos tokens al cerrar la sesión. Por ejemplo, su proveedor de OIDC puede invalidar automáticamente todos los tokens relacionados con uno de actualización determinado. Al cerrar sesión en la aplicación, le recomendamos invalidar solo el token de actualización, ya que el token de acceso se invalida automáticamente. En este caso, debe configurar lo siguiente:

REACT_APP_JUTRO_AUTH_LOGOUT_TOKENS_TO_INVALIDATE=refresh_token

Así, la función logout invalidará solo el token de actualización. Si no establece explícitamente JUTRO_AUTH_LOGOUT_TOKENS_TO_INVALIDATE, la función logout invalida todos los tokens, porque el valor predeterminado es access_token,refresh_token.

Proveedor de contexto AuthProvider

El AuthProvider es el proveedor de contexto que puede utilizar para encapsular su aplicación. Para obtener más información, consulte la página API de cliente de autenticación.

Si desea que toda su aplicación esté protegida por inicio de sesión, no tiene que preocuparse por el AuthProvider, ya que esto se implementa de forma predeterminada en la función de Jutro start().

Gancho useAuth

El gancho useAuth proporciona acceso al estado de autenticación. Para obtener más información, consulte la página API de cliente de autenticación.

Errores de autenticación

Los códigos de error de autenticación de Jutro se exponen a través de puntos de entrada públicos como AuthErrorCodes.

Existen seis códigos de error de autenticación de Jutro:

Error	Causa
JUTRO_AUTH_LOGIN_ERROR	La aplicación no pudo obtener los tokens de autenticación.
JUTRO_AUTH_REFRESH_ERROR	La aplicación no pudo renovar los tokens de autenticación.
JUTRO_AUTH_USER_INFO_ERROR	La aplicación no pudo recuperar la información del usuario.
JUTRO_AUTH_UNKNOWN_ERROR	Se produjo un error desconocido.
JUTRO_AUTH_ACCESS_DENIED_ERROR	El usuario no está asignado a la aplicación.
JUTRO_AUTH_LOGIN_REQUIRED_ERROR	La aplicación no pudo renovar los tokens mediante el método de inicio de sesión silencioso porque el navegador bloquea las cookies de terceros.

Si se está implementando una lógica de autenticación personalizada, es posible que tenga que agregar un manejo personalizado para algunos de estos errores. Para obtener más información, consulte la sección sobre manejo personalizado de errores de autenticación de la página Implementación de la lógica de autenticación personalizada.

Gestión de cookies de sesión de terceros

Las cookies de sesión de terceros pueden estar restringidas en algunos exploradores web, lo que puede causar problemas en el manejo de las sesiones con algunos clientes OIDC. Además, el método de actualización de token de inicio de sesión silencioso no funciona si las cookies de terceros están restringidas y generará un JUTRO_AUTH_LOGIN_REQUIRED_ERROR en esta situación.

Para asegurarse de que las sesiones de los usuarios se gestionen correctamente, debe realizar los siguientes cambios:

• Si usa el cliente OIDC genérico sin inicio de sesión silencioso, elimine las variables JUTRO_AUTH_SILENT_LOGIN_PATH y JUTRO_AUTH_SILENT_REDIRECT_PATH.

• Si usa el cliente OIDC genérico con inicio de sesión silencioso, migre a la renovación pasiva de tokens.

• Amplíe la variable de configuración REACT_APP_JUTRO_AUTH_SCOPE agregando offline_access. Por ejemplo: REACT_APP_JUTRO_AUTH_SCOPE=openid,tenant_id,email,profile,offline_access

• Actualice la configuración de su aplicación Keti para que incluya la concesión REFRESH_TOKEN en la matriz authSettings.grantTypes. Pasos para hacerlo:
  1. Haga una llamada GET a la API GET /applications/{appId} para obtener la configuración actual de la aplicación.
  2. Copie la carga útil de la aplicación devuelta.
  3. Agregue REFRESH_TOKEN a la sección grantTypes de la carga útil copiada.
  4. Realice una llamada PUT a la API PUT /applications/{appId} con la nueva carga útil para actualizar la configuración de la aplicación.

Autenticación personalizada

Si desea que toda su aplicación esté protegida por inicio de sesión, no necesita preocuparse por más personalización. La lógica de autenticación se maneja en la función start() de Jutro.

Si desea controlar cómo su aplicación emplea el inicio de sesión, por ejemplo, requerir el inicio de sesión solo para algunas páginas, debe implementar la lógica de autenticación personalizada. Para obtener más información, consulte la página Implementación de la lógica de autenticación personalizada.