okta auth js
7.8.1
O Okta Auth JavaScript SDK baseia-se em nossa API de autenticação e API OpenID Connect e OAuth 2.0 para permitir que você crie uma experiência de login totalmente personalizada usando JavaScript.
Você pode aprender mais na página Okta + JavaScript em nossa documentação.
Esta biblioteca usa controle de versão semântico e segue a política de versão da biblioteca do Okta.
️ ️ ️ ️ ️ ️ ️ ️ ️
️ ️ ️ ️ ️ ️ ️ ️ ️
✔️ A atual série de versões principais estáveis é: 7.x
| Versão | Status |
|---|---|
7.x | ✔️ Estável |
6.x | Aposentado |
5.x | Aposentado |
4.x | Aposentado |
3.x | Aposentado |
2.x | Aposentado |
1.x | Aposentado |
0.x | Aposentado |
A versão mais recente sempre pode ser encontrada na página de lançamentos.
Se tiver problemas ao usar o SDK, você pode:
Os usuários que migram de versões anteriores deste SDK devem consultar o Guia de migração para saber quais alterações são necessárias.
Este SDK é conhecido por funcionar com as versões atuais do Chrome, Firefox e Safari em desktops e dispositivos móveis.
A compatibilidade com o IE 11/Edge pode ser obtida adicionando polyfill/shims para os seguintes objetos:
️ crypto polyfills são incapazes de usar o sistema operacional como fonte de entropia de boa qualidade usada para gerar números pseudo-aleatórios que são a chave para uma boa criptografia. Como tal, assumimos a postura de que os crypto polyfills são menos seguros e desaconselhamos a sua utilização.
Este módulo fornece um ponto de entrada que implementa todos os polyfills necessários.
Se você estiver usando o JS em uma página da web a partir do navegador, poderá copiar o conteúdo de node_modules/@okta/okta-auth-js/dist para um diretório hospedado publicamente e incluir uma referência ao okta-auth-js.polyfill.js em uma tag <script> . Deve ser carregado antes de qualquer outro script que dependa do polyfill.
Se você estiver usando um bundler como Webpack ou Browserify, você pode simplesmente importar import ou require @okta/okta-auth-js/polyfill no início do código do seu aplicativo ou próximo a ele:
import '@okta/okta-auth-js/polyfill' ;ou
require ( '@okta/okta-auth-js/polyfill' ) ;O pacote polyfill construído também está disponível em nosso CDN global. Inclua o seguinte script em seu arquivo HTML para carregar antes de qualquer outro 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 >
️ A versão mostrada neste exemplo pode ser mais antiga que a versão atual. Recomendamos usar a versão mais alta disponível
Muitos navegadores começaram a bloquear cookies de origem cruzada ou de “terceiros” por padrão. Embora a maioria das APIs Okta suportadas por este SDK não dependam de cookies, existem alguns métodos que o fazem. Estes métodos serão interrompidos se cookies de terceiros forem bloqueados:
Se o seu aplicativo depender de algum desses métodos, você deverá tentar reescrevê-lo para evitar o uso desses métodos ou comunicar aos usuários que eles devem ativar cookies de terceiros. Os engenheiros da Okta estão atualmente trabalhando em uma solução melhor e de longo prazo para esse problema.
Instalar o SDK de autenticação é simples. Você pode incluí-lo em seu projeto por meio de nosso pacote npm, @okta/okta-auth-js.
Você também precisará de:
Ao criar um novo aplicativo Okta, você pode especificar o tipo de aplicativo. Este SDK foi projetado para funcionar com SPA (aplicativos de página única) ou aplicativos Web . Um aplicativo SPA executará todos os fluxos lógicos e de autorização do lado do cliente. Uma aplicação Web executará fluxos de autorização no servidor.
Na UI do Okta Admin, clique em Applications e selecione seu aplicativo. Você pode visualizar e editar a configuração do seu aplicativo Okta na guia General do aplicativo.
Uma string que identifica exclusivamente seu aplicativo Okta.
Para fazer login dos usuários, seu aplicativo redireciona o navegador para uma página de login hospedada pelo Okta. Okta então redireciona de volta para seu aplicativo com informações sobre o usuário. Você pode aprender mais sobre como isso funciona em fluxos hospedados no Okta.
Você precisa colocar o URL de redirecionamento de login na lista de permissões nas configurações do aplicativo Okta.
Depois de desconectar os usuários do seu aplicativo e do Okta, você deverá redirecioná-los para um local específico no seu aplicativo. Você precisa colocar o URL de saída da postagem na lista de permissões nas configurações do aplicativo Okta.
Usar nosso módulo npm é uma boa escolha se:
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 Se você estiver usando o JS em uma página da web a partir do navegador, poderá copiar o conteúdo de node_modules/@okta/okta-auth-js/dist para um diretório hospedado publicamente e incluir uma referência ao okta-auth-js.min.js em uma tag <script> .
O pacote da biblioteca construída também está disponível em nosso CDN global. Inclua o seguinte script no seu arquivo HTML para carregar antes do script do seu aplicativo:
< 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 >
️ A versão mostrada neste exemplo pode ser mais antiga que a versão atual. Recomendamos usar a versão mais alta disponível
Então você pode criar uma instância do objeto OktaAuth , disponível globalmente.
const oktaAuth = new OktaAuth ( {
// config
} )No entanto, se estiver usando um bundler como Webpack ou Rollup, você pode simplesmente importar ou exigir o 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 uma visão geral dos recursos e fluxos de autenticação do cliente, confira nossos documentos para desenvolvedores. Lá, você aprenderá como usar o Auth SDK em uma página estática simples para:
️ Os documentos do desenvolvedor podem ser escritos para uma versão anterior desta biblioteca. Consulte Migrando de versões anteriores.
Você também pode navegar pela documentação completa de referência da API.
⌛ Os métodos assíncronos retornam uma promessa que será resolvida com sucesso. A promessa pode ser rejeitada se ocorrer um erro.
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : 'GHtf9iJdr60A9IYrR0jw' ,
redirectUri : 'https://acme.com/oauth2/callback/home' ,
} ;
var authClient = new OktaAuth ( config ) ; Por padrão, a criação de uma nova instância do OktaAuth não criará nenhum efeito colateral assíncrono. No entanto, certos recursos, como renovação automática de token, remoção automática de token e sincronização entre tabelas, exigem que OktaAuth seja executado como um serviço. Isso significa que os tempos limite são definidos em segundo plano e continuarão funcionando até que o serviço seja interrompido. Para iniciar o serviço OktaAuth , basta chamar o método start logo após a criação e antes de chamar outros métodos como handleRedirect. Para encerrar todos os processos em segundo plano, chame stop . Consulte Configuração de serviço para obter mais informações.
var authClient = new OktaAuth ( config ) ;
await authClient . start ( ) ; // start the service
await authClient . stop ( ) ; // stop the serviceObservação: iniciar o serviço também chamará authStateManager.updateAuthState.
As definições de tipo são fornecidas implicitamente por meio da entrada types em package.json . Os tipos também podem ser referenciados explicitamente importando-os.
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 ) ;
} Versões TypeScript anteriores a 3.6 não possuem definições de tipo para WebAuthn. O suporte para WebAuthn na API IDX foi introduzido em @okta/[email protected] . Para resolver esse problema, instale o pacote @types/webappsec-credential-management version ^0.5.1 .
Os clientes Web e nativos podem obter tokens usando o fluxo authorization_code que usa um segredo do cliente armazenado em um local seguro. (Aplicativos SPA devem usar o fluxo PKCE que não usa um segredo do cliente) Para usar o authorization_code , defina responseType como "code" e pkce como 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 ) ; O fluxo PKCE OAuth será usado por padrão. Esta biblioteca oferece suporte a PKCE para aplicativos de navegador e NodeJS. O PKCE é amplamente suportado pela maioria dos navegadores modernos quando executado em uma conexão HTTPS. O PKCE requer que o navegador implemente crypto.subtle (também conhecido como webcrypto ). A maioria dos navegadores modernos fornece isso quando executado em um contexto seguro (em uma conexão HTTPS). O PKCE também requer o objeto TextEncoder. Está disponível em todos os principais navegadores, exceto IE 11 e Edge <v79. Para adicionar suporte, recomendamos o uso de um polyfill/shim, como codificação de texto.
Se o navegador do usuário não suportar PKCE, uma exceção será lançada. Você pode testar se um navegador suporta PKCE antes da construção com este método estático:
OktaAuth.features.isPKCESupported()
️ Desencorajamos fortemente o uso do fluxo implícito. Use credenciais PKCE e/ou de cliente, se possível.
O fluxo OAuth implícito estará disponível como uma opção se o fluxo PKCE não puder ser suportado em sua implantação. É amplamente suportado pela maioria dos navegadores e pode funcionar em uma conexão HTTP insegura. Observe que o fluxo implícito é menos seguro que o fluxo PKCE, mesmo em HTTPS, uma vez que os tokens brutos são expostos no histórico do navegador. Por esse motivo, é altamente recomendável usar o fluxo PKCE, se possível.
O fluxo implícito pode ser ativado definindo a opção pkce como false
var config = {
pkce : false ,
// other config
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
} ;
var authClient = new OktaAuth ( config ) ;Para conectar um usuário, seu aplicativo deve redirecionar o navegador para a página de login hospedada pelo Okta.
Observação: o redirecionamento inicial para a página de login hospedada pelo Okta inicia uma transação com um tempo de vida stateToken definido como uma hora.
Após a autenticação bem-sucedida, o navegador é redirecionado de volta ao seu aplicativo junto com informações sobre o usuário. Dependendo das suas preferências é possível usar as seguintes estratégias de retorno de chamada.
A maioria dos aplicativos lidará com um retorno de chamada OAuth usando uma rota/página especial, separada da página de login. No entanto, alguns aplicativos SPA não possuem lógica de roteamento e desejarão lidar com tudo em uma única 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
} De acordo com a especificação do OAuth 2.0, o URI de redirecionamento "NÃO DEVE conter um componente de fragmento": https://tools.ietf.org/html/rfc6749#section-3.1.2 Ao usar uma estratégia de roteamento de hash/fragmento e OAuth 2.0, o o retorno de chamada de redirecionamento será a rota principal/padrão. O fluxo de retorno de chamada de redirecionamento será muito semelhante ao tratamento do retorno de chamada sem roteamento. Recomendamos definir a lógica que analisará o URL de redirecionamento logo no início do seu aplicativo, antes de qualquer outra verificação de autorização.
Além disso, se estiver usando roteamento hash, recomendamos usar PKCE e responseMode "query" (este é o padrão para PKCE). Com o fluxo implícito, os tokens no hash podem causar resultados imprevisíveis, uma vez que os roteadores de hash podem reescrever o fragmento.
TokenManager : tokenManager.setTokensReferência: DPoP (Demonstrando Prova de Posse) - RFC9449
DPoP deve estar habilitado em seu aplicativo Okta (Guia: Configurar DPoP)https é obrigatório. Um contexto seguro é necessário para WebCrypto.subtleIndexedDB (MDN, caniuse) const config = {
// other configurations
pkce : true , // required
dpop : true ,
} ;
const authClient = new OktaAuth ( config ) ; Referência: O esquema de autenticação 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_nonceReferência: Nonce fornecido pelo servidor de recursos (RFC9449)
Os servidores de recursos também podem optar por fornecer um valor nonce a ser incluído nas provas DPoP enviadas a eles. Eles fornecem o nonce usando o cabeçalho DPoP-Nonce da mesma forma que os servidores de autorização fazem...
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 requer certos recursos do navegador. Um usuário que usa um navegador sem os recursos necessários não conseguirá concluir uma solicitação de tokens. É recomendado verificar o suporte do navegador durante a inicialização do aplicativo.
// App.tsx
useEffect ( ( ) => {
if ( ! authClient . features . isDPoPSupported ( ) ) {
// user will be unable to request tokens
navigate ( '/unsupported-error-page' ) ;
}
} , [ ] ) ; DPoP requer a geração de um CryptoKeyPair que precisa ser persistido no armazenamento. Métodos como signOut() ou revokeAccessToken() limparão o par de chaves, mas os usuários nem sempre efetuam logout explicitamente. Portanto, é uma boa prática limpar o armazenamento antes do login para liberar quaisquer pares de chaves órfãos gerados a partir de tokens solicitados anteriormente.
async function login ( options ) {
await authClient . clearDPoPStorage ( ) ; // clear possibly orphaned key pairs
return authClient . signInWithRedirect ( options ) ;
} Esteja você usando este SDK para implementar um fluxo OIDC ou para se comunicar com a API de autenticação, a única opção de configuração necessária é issuer , que é a URL para um servidor de autorização Okta
Você pode usar o URL da sua organização Okta como emissor. Isto aplicará uma política de autorização padrão e emitirá tokens com escopo no nível da organização.
var config = {
issuer : 'https://{yourOktaDomain}'
} ;
var authClient = new OktaAuth ( config ) ;Okta permite criar vários servidores de autorização OAuth 2.0 personalizados que você pode usar para proteger seus próprios servidores de recursos. Dentro de cada servidor de autorização você pode definir seus próprios escopos, declarações e políticas de acesso do OAuth 2.0. Muitas organizações possuem um servidor de autorização "padrão".
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default'
} ;
var authClient = new OktaAuth ( config ) ;Você também pode criar e personalizar servidores de autorização adicionais.
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/custom-auth-server-id'
} ;
var authClient = new OktaAuth ( config ) ; Essas opções podem ser incluídas ao instanciar o Okta Auth JS ( new OktaAuth(config) ).
issuer
️ Esta opção é obrigatória
A URL da sua organização Okta ou de um servidor de autenticação Okta. Sobre o emissor
clientIdID do cliente pré-registrado no Okta para o fluxo de autenticação OIDC. Criando seu aplicativo Okta
redirectUri O URL para o qual é redirecionado ao usar token.getWithRedirect . Isso deve estar listado nos URIs de redirecionamento de login do seu aplicativo Okta. Se nenhum redirectUri for fornecido, o padrão é a origem atual ( window.location.origin ). Configurando seu aplicativo Okta
postLogoutRedirectUri Especifique a URL para onde o navegador deve ser redirecionado após sair. Esse URL deve estar listado nos URIs de redirecionamento de logout do seu aplicativo Okta. Se não for especificado, a origem do seu aplicativo ( window.location.origin ) será usada. Configurando seu aplicativo Okta |
scopes Especifique quais informações disponibilizar no id_token ou access_token retornado. Para OIDC, você deve incluir openid como um dos escopos. O padrão é ['openid', 'email'] . Para obter uma lista de escopos disponíveis, consulte Escopos e Declarações
stateUma string fornecida pelo cliente que será passada para o endpoint do servidor e retornada na resposta do OAuth. O valor pode ser usado para validar a resposta OAuth e evitar falsificação de solicitação entre sites (CSRF). O padrão é uma string aleatória.
pkce O valor padrão é true , o que ativa o fluxo PKCE OAuth. Para usar o fluxo implícito ou o fluxo de código de autorização, defina pkce como false .
dpop O valor padrão é false . Defina como true para ativar DPoP (Demonstrando Prova de Posse (RFC9449))
Consulte o Guia: Habilitando DPoP
Ao solicitar tokens usando token.getWithRedirect, os valores serão retornados como parâmetros anexados ao redirectUri.
Na maioria dos casos, você não precisará definir um valor para responseMode . Os padrões são definidos de acordo com a especificação OpenID Connect 1.0.
Para PKCE OAuth Flow), o código de autorização estará na consulta de pesquisa do URL. Os clientes que usam o fluxo PKCE podem optar por receber o código de autorização no fragmento de hash configurando a opção responseMode como "fragment".
Para fluxo OAuth implícito), os tokens estarão no fragmento hash da URL. Isto não pode ser alterado.
responseType Especifique o tipo de resposta para autenticação OIDC ao usar o fluxo OAuth implícito. O valor padrão é ['token', 'id_token'] que solicitará um token de acesso e um token de ID. Se pkce for true , tanto o token de acesso quanto o ID serão solicitados e esta opção será ignorada. Para aplicativos web/nativos que usam o fluxo authorization_code , esse valor deve ser definido como "code" e pkce deve ser definido como false .
authorizeUrlEspecifique um authorizeUrl personalizado para executar o fluxo OIDC. O padrão é o emissor mais "/v1/authorize".
userinfoUrlEspecifique um userinfoUrl personalizado. O padrão é o emissor mais "/v1/userinfo".
tokenUrlEspecifique um tokenUrl personalizado. O padrão é o emissor mais "/v1/token".
ignoreSignature
️ Esta opção deve ser usada apenas para fins de suporte e teste do navegador.
Assinaturas de token de ID são validadas por padrão quando token.getWithoutPrompt , token.getWithPopup , token.getWithRedirect e token.verify são chamados. Para desativar a validação de assinatura de token de ID para esses métodos, configure esse valor como true .
maxClockSkewO padrão é 300 (cinco minutos). Esta é a diferença máxima permitida entre o relógio de um cliente e o do Okta, em segundos, na validação de tokens. Definir isso como 0 não é recomendado, pois aumenta a probabilidade de tokens válidos falharem na validação.
ignoreLifetime
️ Esta opção desativa a validação do tempo de vida do token, o que pode introduzir problemas de vulnerabilidade de segurança. Esta opção deve ser usada para fins de teste. Trate o erro em seu próprio aplicativo para ambiente de produção.
A vida útil do token é validada usando maxClockSkew. Para substituir isso e desabilitar a validação do tempo de vida do token, defina esse valor como true .
transformAuthState Função de retorno de chamada. Quando updateAuthState é chamado, um novo objeto authState é produzido. Fornecer uma função transformAuthState permite modificar ou substituir esse objeto antes que ele seja armazenado e emitido. Um caso de uso comum é alterar o significado de isAuthenticated. Por padrão, updateAuthState definirá authState.isAuthenticated como true se tokens não expirados estiverem disponíveis no tokenManager. Essa lógica pode ser personalizada para exigir também uma sessão válida do Okta SSO:
const config = {
// other config
transformAuthState : async ( oktaAuth , authState ) => {
if ( ! authState . isAuthenticated ) {
return authState ;
}
// extra requirement: user must have valid Okta SSO session
const 
