okta auth js
7.8.1
El SDK de JavaScript de Okta Auth se basa en nuestra API de autenticación y la API OpenID Connect y OAuth 2.0 para permitirle crear una experiencia de inicio de sesión de marca completa utilizando JavaScript.
Puede obtener más información en la página Okta + JavaScript en nuestra documentación.
Esta biblioteca utiliza versiones semánticas y sigue la política de versiones de la biblioteca de Okta.
️ ️ ️ ️ ️ ️ ️ ️ ️
️ ️ ️ ️ ️ ️ ️ ️ ️
✔️ La serie de versiones principales estables actuales es: 7.x
| Versión | Estado |
|---|---|
7.x | ✔️ Estable |
6.x | Jubilado |
5.x | Jubilado |
4.x | Jubilado |
3.x | Jubilado |
2.x | Jubilado |
1.x | Jubilado |
0.x | Jubilado |
La última versión siempre se puede encontrar en la página de versiones.
Si tiene problemas al utilizar el SDK, puede:
Los usuarios que migren desde versiones anteriores de este SDK deben consultar la Guía de migración para saber qué cambios son necesarios.
Se sabe que este SDK funciona con las versiones actuales de Chrome, Firefox y Safari en computadoras de escritorio y dispositivos móviles.
La compatibilidad con IE 11/Edge se puede lograr agregando polyfill/shims para los siguientes objetos:
️ Los criptopolyfills no pueden utilizar el sistema operativo como fuente de entropía de buena calidad utilizada para generar números pseudoaleatorios que son la clave para una buena criptografía. Como tal, adoptamos la postura de que los criptopolyfills son menos seguros y desaconsejamos su uso.
Este módulo proporciona un punto de entrada que implementa todos los polyfills necesarios.
Si está utilizando JS en una página web desde el navegador, puede copiar el contenido de node_modules/@okta/okta-auth-js/dist en un directorio alojado públicamente e incluir una referencia a okta-auth-js.polyfill.js en una etiqueta <script> . Debe cargarse antes que cualquier otro script que dependa del polyfill.
Si está utilizando un paquete como Webpack o Browserify, simplemente puede importar o solicitar @okta/okta-auth-js/polyfill al principio o cerca del código de su aplicación:
import '@okta/okta-auth-js/polyfill' ;o
require ( '@okta/okta-auth-js/polyfill' ) ;El paquete Polyfill integrado también está disponible en nuestra CDN global. Incluya el siguiente script en su archivo HTML para cargarlo antes que cualquier otro script:
< script src =" https://global.oktacdn.com/okta-auth-js/7.5.1/okta-auth-js.polyfill.js " type =" text/javascript " integrity =" sha384-EBFsuVdi4TGp/DwS7b+t+wA8zmWK10omkX05ZjJWQhzWuW31t7FWEGOnHQeIr8+L " crossorigin =" anonymous " > </ script >
️ La versión que se muestra en este ejemplo puede ser anterior a la versión actual. Recomendamos utilizar la versión más alta disponible.
Muchos navegadores han comenzado a bloquear las cookies de origen cruzado o de "terceros" de forma predeterminada. Aunque la mayoría de las API de Okta compatibles con este SDK no dependen de cookies, existen algunos métodos que sí lo hacen. Estos métodos dejarán de funcionar si se bloquean las cookies de terceros:
Si su aplicación depende de cualquiera de estos métodos, debe intentar reescribirla para evitar el uso de estos métodos o comunicar a sus usuarios que deben habilitar las cookies de terceros. Los ingenieros de Okta están trabajando actualmente en una mejor solución a largo plazo para este problema.
Instalar el SDK de autenticación es sencillo. Puede incluirlo en su proyecto a través de nuestro paquete npm, @okta/okta-auth-js.
También necesitarás:
Al crear una nueva aplicación Okta, puede especificar el tipo de aplicación. Este SDK está diseñado para funcionar con SPA (aplicaciones de una sola página) o aplicaciones Web . Una aplicación SPA realizará todos los flujos de lógica y autorización del lado del cliente. Una aplicación Web realizará flujos de autorización en el servidor.
Desde la interfaz de usuario de Okta Admin, haga clic en Applications y luego seleccione su aplicación. Puede ver y editar la configuración de su aplicación Okta en la pestaña General de la aplicación.
Una cadena que identifica de forma única su aplicación Okta.
Para iniciar sesión en los usuarios, su aplicación redirige el navegador a una página de inicio de sesión alojada en Okta. Okta luego redirige a su aplicación con información sobre el usuario. Puede obtener más información sobre cómo funciona esto en flujos alojados en Okta.
Debe incluir la URL de redireccionamiento de inicio de sesión en la lista blanca en la configuración de su aplicación Okta.
Después de cerrar la sesión de los usuarios en su aplicación y en Okta, debe redirigir a los usuarios a una ubicación específica en su aplicación. Debe incluir en la lista blanca la URL de cierre de sesión posterior en la configuración de su aplicación Okta.
Usar nuestro módulo npm es una buena opción si:
Para instalar @okta/okta-auth-js:
# Run this command in your project root folder.
# yarn
yarn add @okta/okta-auth-js
# npm
npm install --save @okta/okta-auth-js Si está utilizando JS en una página web desde el navegador, puede copiar el contenido de node_modules/@okta/okta-auth-js/dist en un directorio alojado públicamente e incluir una referencia a okta-auth-js.min.js en una etiqueta <script> .
El paquete de biblioteca creado también está disponible en nuestra CDN global. Incluya el siguiente script en su archivo HTML para cargarlo antes del script de su aplicación:
< script src =" https://global.oktacdn.com/okta-auth-js/7.5.1/okta-auth-js.min.js " type =" text/javascript " integrity =" sha384-6epSwnIDkI5zFNEVNjEYy3A7aSZ+C7ehmEyG8zDJZfP9Bmnxc51TK8du+2me4pjb " crossorigin =" anonymous " > </ script >
️ La versión que se muestra en este ejemplo puede ser anterior a la versión actual. Recomendamos utilizar la versión más alta disponible.
Luego puedes crear una instancia del objeto OktaAuth , disponible globalmente.
const oktaAuth = new OktaAuth ( {
// config
} )Sin embargo, si está utilizando un paquete como Webpack o Rollup, simplemente puede importar o solicitar el módulo.
// ES module
import { OktaAuth } from '@okta/okta-auth-js'
const authClient = new OktaAuth ( /* configOptions */ ) // CommonJS
var OktaAuth = require ( '@okta/okta-auth-js' ) . OktaAuth ;
var authClient = new OktaAuth ( /* configOptions */ ) ; Para obtener una descripción general de las funciones del cliente y los flujos de autenticación, consulte nuestros documentos para desarrolladores. Allí, aprenderá a utilizar el SDK de autenticación en una página estática simple para:
️ Los documentos para desarrolladores pueden estar escritos para una versión anterior de esta biblioteca. Consulte Migración desde versiones anteriores.
También puede explorar la documentación de referencia de API completa.
⌛ Los métodos asíncronos devuelven una promesa que se resolverá con éxito. La promesa puede rechazarse si se produce un error.
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : 'GHtf9iJdr60A9IYrR0jw' ,
redirectUri : 'https://acme.com/oauth2/callback/home' ,
} ;
var authClient = new OktaAuth ( config ) ; De forma predeterminada, la creación de una nueva instancia de OktaAuth no creará ningún efecto secundario asincrónico. Sin embargo, ciertas características como la renovación automática de tokens, la eliminación automática de tokens y la sincronización entre pestañas requieren que OktaAuth se ejecute como un servicio. Esto significa que los tiempos de espera se establecen en segundo plano y seguirán funcionando hasta que se detenga el servicio. Para iniciar el servicio OktaAuth , simplemente llame al método start justo después de la creación y antes de llamar a otros métodos como handleRedirect. Para finalizar todos los procesos en segundo plano, llame stop . Consulte Configuración del servicio para obtener más información.
var authClient = new OktaAuth ( config ) ;
await authClient . start ( ) ; // start the service
await authClient . stop ( ) ; // stop the serviceNota: Al iniciar el servicio también se llamará a authStateManager.updateAuthState.
Las definiciones de tipos se proporcionan implícitamente a través de la entrada types en package.json . También se puede hacer referencia explícita a los tipos importándolos.
import {
OktaAuth ,
OktaAuthOptions ,
TokenManagerInterface ,
AccessToken ,
IDToken ,
UserClaims ,
TokenParams
} from '@okta/okta-auth-js' ;
const config : OktaAuthOptions = {
issuer : 'https://{yourOktaDomain}'
} ;
const authClient : OktaAuth = new OktaAuth ( config ) ;
const tokenManager : TokenManagerInterface = authClient . tokenManager ;
const accessToken : AccessToken = await tokenManager . get ( 'accessToken' ) as AccessToken ;
const idToken : IDToken = await tokenManager . get ( 'idToken' ) as IDToken ;
const userInfo : UserClaims = await authClient . token . getUserInfo ( accessToken , idToken ) ;
if ( ! userInfo ) {
const tokenParams : TokenParams = {
scopes : [ 'openid' , 'email' , 'custom_scope' ] ,
} ;
authClient . token . getWithRedirect ( tokenParams ) ;
} Las versiones de Typecript anteriores a la 3.6 no tienen definiciones de tipos para WebAuthn. La compatibilidad con WebAuthn en la API IDX se introdujo en @okta/[email protected] . Para resolver este problema, instale el paquete @types/webappsec-credential-management versión ^0.5.1 .
Los clientes web y nativos pueden obtener tokens utilizando el flujo de authorization_code que utiliza un secreto de cliente almacenado en una ubicación segura. (Las aplicaciones SPA deben usar el flujo PKCE que no usa un secreto de cliente) Para usar el flujo de authorization_code , establezca responseType en "code" y pkce en false :
var config = {
// Required config
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : 'GHtf9iJdr60A9IYrR0jw' ,
redirectUri : 'https://acme.com/oauth2/callback/home' ,
// Use authorization_code flow
responseType : 'code' ,
pkce : false
} ;
var authClient = new OktaAuth ( config ) ; El flujo PKCE OAuth se utilizará de forma predeterminada. Esta biblioteca es compatible con PKCE tanto para aplicaciones de navegador como de NodeJS. PKCE es ampliamente compatible con la mayoría de los navegadores modernos cuando se ejecuta en una conexión HTTPS. PKCE requiere que el navegador implemente crypto.subtle (también conocido como webcrypto ). La mayoría de los navegadores modernos ofrecen esto cuando se ejecutan en un contexto seguro (en una conexión HTTPS). PKCE también requiere el objeto TextEncoder. Está disponible en todos los navegadores principales excepto IE 11 y Edge <v79. Para agregar soporte, recomendamos usar un polyfill/shim como codificación de texto.
Si el navegador del usuario no es compatible con PKCE, se generará una excepción. Puede probar si un navegador admite PKCE antes de la construcción con este método estático:
OktaAuth.features.isPKCESupported()
️ Desaconsejamos encarecidamente el uso del flujo implícito. Utilice PKCE y/o credenciales de cliente si es posible.
El flujo OAuth implícito está disponible como opción si el flujo PKCE no es compatible con su implementación. Es ampliamente compatible con la mayoría de los navegadores y puede funcionar a través de una conexión HTTP insegura. Tenga en cuenta que el flujo implícito es menos seguro que el flujo PKCE, incluso a través de HTTPS, ya que los tokens sin procesar están expuestos en el historial del navegador. Por este motivo, recomendamos encarecidamente utilizar el flujo PKCE si es posible.
El flujo implícito se puede habilitar configurando la opción pkce en false
var config = {
pkce : false ,
// other config
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
} ;
var authClient = new OktaAuth ( config ) ;Para iniciar sesión como usuario, su aplicación debe redirigir el navegador a la página de inicio de sesión alojada en Okta.
Nota: El redireccionamiento inicial a la página de inicio de sesión alojada en Okta inicia una transacción con una duración de stateToken establecida en una hora.
Después de una autenticación exitosa, el navegador es redirigido a su aplicación junto con información sobre el usuario. Dependiendo de sus preferencias, es posible utilizar las siguientes estrategias de devolución de llamada.
La mayoría de las aplicaciones manejarán una devolución de llamada de OAuth utilizando una ruta/página especial, separada de la página de inicio de sesión. Sin embargo, algunas aplicaciones SPA no tienen lógica de enrutamiento y querrán manejar todo en una sola página.
async function main ( ) {
// create OktaAuth instance
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : 'GHtf9iJdr60A9IYrR0jw' ,
redirectUri : 'https://acme.com/oauth2/callback/home' ,
} ;
authClient = new OktaAuth ( config ) ;
// Subscribe to authState change event.
authClient . authStateManager . subscribe ( function ( authState ) {
// Logic based on authState is done here.
if ( ! authState . isAuthenticated ) {
// render unathenticated view
return ;
}
// Render authenticated view
} ) ;
// Handle callback
if ( authClient . token . isLoginRedirect ( ) ) {
const { tokens } = await authClient . token . parseFromUrl ( ) ; // remember to "await" this async call
authClient . tokenManager . setTokens ( tokens ) ;
}
// normal app startup
authClient . start ( ) ; // will update auth state and call event listeners
} Según la especificación de OAuth 2.0, el URI de redireccionamiento "NO DEBE contener un componente de fragmento": https://tools.ietf.org/html/rfc6749#section-3.1.2 Cuando se utiliza una estrategia de enrutamiento de hash/fragmento y OAuth 2.0, el La devolución de llamada de redirección será la ruta principal/predeterminada. El flujo de devolución de llamada de redireccionamiento será muy similar a manejar la devolución de llamada sin enrutamiento. Recomendamos definir la lógica que analizará la URL de redireccionamiento al principio de su aplicación, antes de cualquier otra verificación de autorización.
Además, si utiliza enrutamiento hash, recomendamos usar PKCE y la "consulta" del modo de respuesta (este es el valor predeterminado para PKCE). Con el flujo implícito, los tokens en el hash podrían causar resultados impredecibles ya que los enrutadores de hash pueden reescribir el fragmento.
TokenManager : tokenManager.setTokensReferencia: DPoP (Demostración de prueba de posesión) - RFC9449
DPoP debe estar habilitado en su aplicación Okta (Guía: Configurar DPoP)https . Se requiere un contexto seguro para WebCrypto.subtleIndexedDB (MDN, caniuse) const config = {
// other configurations
pkce : true , // required
dpop : true ,
} ;
const authClient = new OktaAuth ( config ) ; Referencia: El esquema de autenticación DPoP (RFC9449)
GET /protectedresource HTTP/1.1
Host: resource.example.org
Authorization: DPoP Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsIm...
async function dpopAuthenticatedFetch ( url , options ) {
const { method } = options ;
const dpop = await authClient . getDPoPAuthorizationHeaders ( { url , method } ) ;
// dpop = { Authorization: "DPoP token****", Dpop: "proof****" }
const headers = new Headers ( { ... options . headers , ... dpop } ) ;
return fetch ( url , { ... options , headers } ) ;
} use_dpop_nonceReferencia: Nonce proporcionado por el servidor de recursos (RFC9449)
Los servidores de recursos también pueden optar por proporcionar un valor nonce para incluirlo en las pruebas DPoP que se les envíen. Proporcionan el nonce utilizando el encabezado DPoP-Nonce de la misma manera que lo hacen los servidores de autorización...
HTTP/1.1 401 Unauthorized
WWW-Authenticate: DPoP error="use_dpop_nonce",
error_description="Resource server requires nonce in DPoP proof"
DPoP-Nonce: eyJ7S_zG.eyJH0-Z.HX4w-7v
async function dpopAuthenticatedFetch ( url , options ) {
// ...previous example...
const resp = await fetch ( url , { ... options , headers } ) ;
// resp = HTTP/1.1 401 Unauthorized...
if ( ! resp . ok ) {
const nonce = authClient . parseUseDPoPNonceError ( resp . headers ) ;
if ( nonce ) {
const retryDpop = await authClient . getDPoPAuthorizationHeaders ( { url , method , nonce } ) ;
const retryHeaders = new Headers ( { ... options . headers , ... retryDpop } ) ;
return fetch ( url , { ... options , headers : retryHeaders } ) ;
}
}
return resp ;
} DPoP requiere ciertas funciones del navegador. Un usuario que utilice un navegador sin las funciones requeridas no podrá completar una solicitud de tokens. Se recomienda verificar la compatibilidad del navegador durante el arranque de la aplicación.
// App.tsx
useEffect ( ( ) => {
if ( ! authClient . features . isDPoPSupported ( ) ) {
// user will be unable to request tokens
navigate ( '/unsupported-error-page' ) ;
}
} , [ ] ) ; DPoP requiere la generación de un CryptoKeyPair que debe conservarse en el almacenamiento. Métodos como signOut() o revokeAccessToken() borrarán el par de claves, sin embargo, los usuarios no siempre cierran sesión explícitamente. Por lo tanto, es una buena práctica borrar el almacenamiento antes de iniciar sesión para eliminar cualquier par de claves huérfanos generado a partir de tokens solicitados previamente.
async function login ( options ) {
await authClient . clearDPoPStorage ( ) ; // clear possibly orphaned key pairs
return authClient . signInWithRedirect ( options ) ;
} Ya sea que esté utilizando este SDK para implementar un flujo OIDC o para comunicarse con la API de autenticación, la única opción de configuración requerida es issuer , que es la URL a un servidor de autorización de Okta.
Puede utilizar la URL de su organización Okta como emisor. Esto aplicará una política de autorización predeterminada y emitirá tokens con alcance a nivel de organización.
var config = {
issuer : 'https://{yourOktaDomain}'
} ;
var authClient = new OktaAuth ( config ) ;Okta le permite crear múltiples servidores de autorización OAuth 2.0 personalizados que puede usar para proteger sus propios servidores de recursos. Dentro de cada servidor de autorización, puede definir sus propios alcances, reclamaciones y políticas de acceso de OAuth 2.0. Muchas organizaciones tienen un servidor de autorización "predeterminado".
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default'
} ;
var authClient = new OktaAuth ( config ) ;También puede crear y personalizar servidores de autorización adicionales.
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/custom-auth-server-id'
} ;
var authClient = new OktaAuth ( config ) ; Estas opciones se pueden incluir al crear una instancia de Okta Auth JS ( new OktaAuth(config) ).
issuer
️ Esta opción es obligatoria
La URL de su organización Okta o un servidor de autenticación de Okta. Sobre el emisor
clientIdID de cliente prerregistrado con Okta para el flujo de autenticación OIDC. Creando tu aplicación Okta
redirectUri La URL a la que se redirige cuando se usa token.getWithRedirect . Esto debe aparecer en los URI de redireccionamiento de inicio de sesión de su aplicación Okta. Si no se proporciona redirectUri , el valor predeterminado es el origen actual ( window.location.origin ). Configurando su aplicación Okta
postLogoutRedirectUri Especifique la URL a la que se debe redirigir el navegador después de cerrar sesión. Esta URL debe aparecer en los URI de redirección de cierre de sesión de su aplicación Okta. Si no se especifica, se utilizará el origen de su aplicación ( window.location.origin ). Configurando su aplicación Okta |
scopes Especifique qué información poner a disposición en el id_token o access_token devuelto. Para OIDC, debe incluir openid como uno de los ámbitos. El valor predeterminado es ['openid', 'email'] . Para obtener una lista de los alcances disponibles, consulte Ámbitos y reclamaciones.
stateUna cadena proporcionada por el cliente que se pasará al punto final del servidor y se devolverá en la respuesta de OAuth. El valor se puede utilizar para validar la respuesta de OAuth y evitar la falsificación de solicitudes entre sitios (CSRF). El valor predeterminado es una cadena aleatoria.
pkce El valor predeterminado es true , lo que habilita el flujo PKCE OAuth. Para utilizar el flujo implícito o el flujo de código de autorización, establezca pkce en false .
dpop El valor predeterminado es false . Establezca en true para habilitar DPoP (Demostración de prueba de posesión (RFC9449))
Ver Guía: Habilitar DPoP
Al solicitar tokens utilizando token.getWithRedirect, los valores se devolverán como parámetros agregados a la redirecciónUri.
En la mayoría de los casos, no necesitará establecer un valor para responseMode . Los valores predeterminados se establecen de acuerdo con la especificación OpenID Connect 1.0.
Para PKCE OAuth Flow), el código de autorización estará en la consulta de búsqueda de la URL. Los clientes que utilizan el flujo PKCE pueden optar por recibir el código de autorización en el fragmento hash configurando la opción ResponseMode en "fragmentar".
Para el flujo implícito de OAuth), los tokens estarán en el fragmento hash de la URL. Esto no se puede cambiar.
responseType Especifique el tipo de respuesta para la autenticación OIDC cuando utilice el flujo OAuth implícito. El valor predeterminado es ['token', 'id_token'] que solicitará tanto un token de acceso como un token de identificación. Si pkce es true , se solicitarán tanto el token de acceso como el de identificación y se ignorará esta opción. Para aplicaciones web/nativas que utilizan el flujo de authorization_code , este valor debe establecerse en "code" y pkce debe establecerse en false .
authorizeUrlEspecifique una URL de autorización personalizada para realizar el flujo OIDC. El valor predeterminado es el emisor más "/v1/authorize".
userinfoUrlEspecifique una URL de información de usuario personalizada. El valor predeterminado es el emisor más "/v1/userinfo".
tokenUrlEspecifique una URL de token personalizada. El valor predeterminado es el emisor más "/v1/token".
ignoreSignature
️ Esta opción debe utilizarse únicamente para fines de prueba y soporte del navegador.
Las firmas de tokens de ID se validan de forma predeterminada cuando se llaman a token.getWithoutPrompt , token.getWithPopup , token.getWithRedirect y token.verify . Para deshabilitar la validación de la firma del token de ID para estos métodos, establezca este valor en true .
maxClockSkewEl valor predeterminado es 300 (cinco minutos). Esta es la diferencia máxima permitida entre el reloj de un cliente y el de Okta, en segundos, al validar tokens. No se recomienda establecer esto en 0, porque aumenta la probabilidad de que los tokens válidos no superen la validación.
ignoreLifetime
️ Esta opción deshabilita la validación de la duración del token, lo que puede introducir problemas de vulnerabilidad de seguridad. Esta opción debe utilizarse con fines de prueba. Maneje el error en su propia aplicación para el entorno de producción.
La vida útil de los tokens se valida mediante maxClockSkew. Para anular esto y deshabilitar la validación de duración del token, establezca este valor en true .
transformAuthState Función de devolución de llamada. Cuando se llama a updateAuthState, se produce un nuevo objeto authState. Proporcionar una función transformAuthState le permite modificar o reemplazar este objeto antes de almacenarlo y emitirlo. Un caso de uso común es cambiar el significado de isAuthenticated. De forma predeterminada, updateAuthState establecerá authState.isAuthenticated en verdadero si hay tokens no vencidos disponibles en tokenManager. Esta lógica podría personalizarse para requerir también una sesión SSO de Okta válida:
const config = {
// other config
transformAuthState : async ( oktaAuth , authState ) => {
if ( ! authState . isAuthenticated ) {
return authState ;
}
// extra requirement: user must have valid Okta SSO session
const 
