okta auth js
7.8.1
Пакет Okta Auth JavaScript SDK построен на основе нашего API аутентификации и API OpenID Connect & OAuth 2.0, что позволяет вам создать полностью фирменный интерфейс входа в систему с использованием JavaScript.
Подробную информацию вы можете узнать на странице Okta + JavaScript в нашей документации.
Эта библиотека использует семантическое управление версиями и соответствует политике версий библиотеки Okta.
️ ️ ️ ️ ️ ️ ️ ️ ️
️ ️ ️ ️ ️ ️ ️ ️ ️
✔️ Текущая стабильная основная серия версий: 7.x
| Версия | Статус |
|---|---|
7.x | ✔️ Стабильный |
6.x | Ушедший на пенсию |
5.x | Ушедший на пенсию |
4.x | Ушедший на пенсию |
3.x | Ушедший на пенсию |
2.x | Ушедший на пенсию |
1.x | Ушедший на пенсию |
0.x | Ушедший на пенсию |
Последний выпуск всегда можно найти на странице релизов.
Если у вас возникнут проблемы с использованием SDK, вы можете:
Пользователям, переходящим с предыдущих версий этого SDK, следует ознакомиться с Руководством по миграции, чтобы узнать, какие изменения необходимы.
Известно, что этот SDK работает с текущими версиями Chrome, Firefox и Safari на настольных компьютерах и мобильных устройствах.
Совместимость с IE 11/Edge может быть достигнута путем добавления полифилов/прокладок для следующих объектов:
️ криптополифилы не могут использовать операционную систему в качестве источника энтропии хорошего качества, используемой для генерации псевдослучайных чисел, которые являются ключом к хорошей криптографии. Таким образом, мы считаем, что криптополифилы менее безопасны, и не советуем их использовать.
Этот модуль предоставляет точку входа, которая реализует все необходимые полифилы.
Если вы используете JS на веб-странице из браузера, вы можете скопировать содержимое node_modules/@okta/okta-auth-js/dist в общедоступный каталог и включить ссылку на okta-auth-js.polyfill.js в теге <script> . Его следует загружать перед любыми другими скриптами, зависящими от полифила.
Если вы используете сборщик, такой как Webpack или Browserify, вы можете просто импортировать import или потребовать @okta/okta-auth-js/polyfill в начале кода вашего приложения или рядом с ним:
import '@okta/okta-auth-js/polyfill' ;или
require ( '@okta/okta-auth-js/polyfill' ) ;Встроенный пакет полифилов также доступен в нашей глобальной CDN. Включите следующий скрипт в свой HTML-файл, чтобы он загружался перед любыми другими скриптами:
< 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 >
️ Версия, показанная в этом примере, может быть старше текущей версии. Мы рекомендуем использовать самую последнюю доступную версию.
Многие браузеры по умолчанию начали блокировать файлы cookie перекрестного происхождения или «сторонние» файлы cookie. Хотя большинство API-интерфейсов Okta, поддерживаемых этим SDK, не полагаются на файлы cookie, существует несколько методов, которые это делают. Эти методы не будут работать, если сторонние файлы cookie заблокированы:
Если ваше приложение зависит от любого из этих методов, вам следует попытаться либо переписать свое приложение, чтобы избежать использования этих методов, либо сообщить своим пользователям, что они должны включить сторонние файлы cookie. Инженеры Okta в настоящее время работают над лучшим долгосрочным решением этой проблемы.
Установить Authentication SDK очень просто. Вы можете включить его в свой проект через наш пакет npm @okta/okta-auth-js.
Вам также понадобится:
При создании нового приложения Okta вы можете указать тип приложения. Этот SDK предназначен для работы с SPA (одностраничными приложениями) или Web -приложениями. Приложение SPA будет выполнять всю логику и потоки авторизации на стороне клиента. Web приложение будет выполнять потоки авторизации на сервере.
В пользовательском интерфейсе администратора Okta нажмите Applications и выберите свое приложение. Вы можете просматривать и редактировать конфигурацию приложения Okta на вкладке General приложения.
Строка, которая однозначно идентифицирует ваше приложение Okta.
Для входа пользователей ваше приложение перенаправляет браузер на страницу входа, размещенную на Okta. Затем Okta перенаправляет обратно в ваше приложение с информацией о пользователе. Вы можете узнать больше о том, как это работает в потоках, размещенных на Okta.
Вам необходимо внести в белый список URL-адрес перенаправления входа в настройки приложения Okta.
После того, как вы выведете пользователей из своего приложения и из Okta, вам необходимо перенаправить пользователей в определенное место в вашем приложении. Вам необходимо внести URL-адрес выхода из системы в белый список в настройках приложения Okta.
Использование нашего модуля npm — хороший выбор, если:
Чтобы установить @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 Если вы используете JS на веб-странице из браузера, вы можете скопировать содержимое node_modules/@okta/okta-auth-js/dist в общедоступный каталог и включить ссылку на okta-auth-js.min.js в теге <script> .
Пакет встроенной библиотеки также доступен в нашей глобальной CDN. Включите следующий сценарий в свой HTML-файл для загрузки перед сценарием приложения:
< 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 >
️ Версия, показанная в этом примере, может быть старше текущей версии. Мы рекомендуем использовать самую последнюю доступную версию.
Затем вы можете создать экземпляр объекта OktaAuth , доступный глобально.
const oktaAuth = new OktaAuth ( {
// config
} )Однако, если вы используете сборщик, такой как Webpack или Rollup, вы можете просто импортировать или запросить модуль.
// 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 */ ) ; Обзор функций клиента и потоков аутентификации можно найти в нашей документации для разработчиков. Там вы узнаете, как использовать Auth SDK на простой статической странице, чтобы:
️ Документы разработчика могут быть написаны для более ранней версии этой библиотеки. См. раздел Миграция с предыдущих версий.
Вы также можете просмотреть полную справочную документацию по API.
⌛ Асинхронные методы возвращают обещание, которое будет выполнено в случае успеха. Обещание может быть отклонено в случае возникновения ошибки.
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : 'GHtf9iJdr60A9IYrR0jw' ,
redirectUri : 'https://acme.com/oauth2/callback/home' ,
} ;
var authClient = new OktaAuth ( config ) ; По умолчанию создание нового экземпляра OktaAuth не создаст никаких асинхронных побочных эффектов. Однако некоторые функции, такие как автоматическое продление токена, автоматическое удаление токена и синхронизация между вкладками, требуют, чтобы OktaAuth работал как служба. Это означает, что в фоновом режиме устанавливаются тайм-ауты, которые будут продолжать работать до тех пор, пока служба не будет остановлена. Чтобы запустить службу OktaAuth , просто вызовите метод start сразу после создания и перед вызовом других методов, таких как handleRedirect. Чтобы завершить все фоновые процессы, вызовите stop . Дополнительную информацию см. в разделе Конфигурация службы.
var authClient = new OktaAuth ( config ) ;
await authClient . start ( ) ; // start the service
await authClient . stop ( ) ; // stop the serviceПримечание. При запуске службы также будет вызван authStateManager.updateAuthState.
Определения типов предоставляются неявно через запись types в package.json . На типы также можно ссылаться явно, импортируя их.
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 ) ;
} Версии Typescript до 3.6 не имеют определений типов для WebAuthn. Поддержка WebAuthn в IDX API была представлена в @okta/[email protected] . Чтобы решить эту проблему, установите пакет @types/webappsec-credential-management версии ^0.5.1 .
Веб-клиенты и собственные клиенты могут получать токены с помощью потока authorization_code , который использует секрет клиента, хранящийся в безопасном месте. (Приложения SPA должны использовать поток PKCE , который не использует секрет клиента). Чтобы использовать поток authorization_code , установите для responseType значение "code" и pkce значение 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 ) ; Поток PKCE OAuth будет использоваться по умолчанию. Эта библиотека поддерживает PKCE как для браузера, так и для приложений NodeJS. PKCE широко поддерживается большинством современных браузеров при работе по HTTPS-соединению. PKCE требует, чтобы браузер реализовал crypto.subtle (также известный как webcrypto ). Большинство современных браузеров обеспечивают это при работе в безопасном контексте (при соединении HTTPS). PKCE также требует объекта TextEncoder. Это доступно во всех основных браузерах, кроме IE 11 и Edge < v79. Чтобы добавить поддержку, мы рекомендуем использовать полифилл/прокладку, например text-encoding.
Если браузер пользователя не поддерживает PKCE, будет выдано исключение. Вы можете проверить, поддерживает ли браузер PKCE перед созданием с помощью этого статического метода:
OktaAuth.features.isPKCESupported()
️ Мы настоятельно не рекомендуем использовать неявный поток. Если возможно, используйте PKCE и/или учетные данные клиента.
Неявный поток OAuth доступен в качестве опции, если поток PKCE не поддерживается в вашем развертывании. Он широко поддерживается большинством браузеров и может работать через небезопасное HTTP-соединение. Обратите внимание, что неявный поток менее безопасен, чем поток PKCE, даже через HTTPS, поскольку необработанные токены отображаются в истории браузера. По этой причине мы настоятельно рекомендуем по возможности использовать поток PKCE.
Неявный поток можно включить, установив для параметра pkce значение false
var config = {
pkce : false ,
// other config
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
} ;
var authClient = new OktaAuth ( config ) ;Чтобы войти в систему, ваше приложение должно перенаправить браузер на страницу входа, размещенную на Okta.
Примечание. Первоначальное перенаправление на страницу входа, размещенную на Okta, запускает транзакцию со сроком действия stateToken, равным одному часу.
После успешной аутентификации браузер перенаправляется обратно в ваше приложение вместе с информацией о пользователе. В зависимости от ваших предпочтений можно использовать следующие стратегии обратного вызова.
Большинство приложений обрабатывают обратный вызов OAuth, используя специальный маршрут/страницу, отдельную от страницы входа. Однако некоторые SPA-приложения не имеют логики маршрутизации и хотят обрабатывать все на одной странице.
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
} В соответствии со спецификацией OAuth 2.0 URI перенаправления «НЕ ДОЛЖЕН содержать компонент фрагмента»: https://tools.ietf.org/html/rfc6749#section-3.1.2. При использовании стратегии маршрутизации хеша/фрагмента и OAuth 2.0 обратный вызов перенаправления будет основным маршрутом/маршрутом по умолчанию. Поток обратного вызова перенаправления будет очень похож на обработку обратного вызова без маршрутизации. Мы рекомендуем определить логику, которая будет анализировать URL-адрес перенаправления, в самом начале вашего приложения, до любых других проверок авторизации.
Кроме того, при использовании хэш-маршрутизации мы рекомендуем использовать PKCE и режим ответа «запрос» (это значение по умолчанию для PKCE). При неявном потоке токены в хеше могут привести к непредсказуемым результатам, поскольку хэш-маршрутизаторы могут перезаписать фрагмент.
TokenManager : tokenManager.setTokens.Ссылка: DPoP (демонстрация доказательства владения) — RFC9449.
DPoP должен быть включен в вашем приложении Okta (Руководство: Настройка DPoP)https обязателен. Для WebCrypto.subtle требуется безопасный контекст.IndexedDB (MDN, caniuse). const config = {
// other configurations
pkce : true , // required
dpop : true ,
} ;
const authClient = new OktaAuth ( config ) ; Ссылка: Схема аутентификации 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_nonceСсылка: Nonce, предоставляемый сервером ресурсов (RFC9449).
Серверы ресурсов также могут предоставить значение nonce, которое будет включено в отправляемые им доказательства DPoP. Они предоставляют nonce, используя заголовок DPoP-Nonce, точно так же, как это делают серверы авторизации...
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 требует определенных функций браузера. Пользователь, использующий браузер без необходимых функций, не сможет выполнить запрос на токены. Рекомендуется проверить поддержку браузера во время загрузки приложения.
// App.tsx
useEffect ( ( ) => {
if ( ! authClient . features . isDPoPSupported ( ) ) {
// user will be unable to request tokens
navigate ( '/unsupported-error-page' ) ;
}
} , [ ] ) ; DPoP требует создания пары CryptoKeyPair , которую необходимо сохранить в хранилище. Такие методы, как signOut() или revokeAccessToken() очищают пару ключей, однако пользователи не всегда выходят из системы явным образом. Поэтому рекомендуется очищать хранилище перед входом в систему, чтобы сбросить все потерянные пары ключей, сгенерированные из ранее запрошенных токенов.
async function login ( options ) {
await authClient . clearDPoPStorage ( ) ; // clear possibly orphaned key pairs
return authClient . signInWithRedirect ( options ) ;
} Независимо от того, используете ли вы этот SDK для реализации потока OIDC или для связи с API аутентификации, единственным обязательным параметром конфигурации является issuer , который является URL-адресом сервера авторизации Okta.
Вы можете использовать URL-адрес своей организации Okta в качестве эмитента. При этом будет применена политика авторизации по умолчанию и выданы токены, доступные на уровне организации.
var config = {
issuer : 'https://{yourOktaDomain}'
} ;
var authClient = new OktaAuth ( config ) ;Okta позволяет вам создавать несколько пользовательских серверов авторизации OAuth 2.0, которые вы можете использовать для защиты своих собственных серверов ресурсов. На каждом сервере авторизации вы можете определить свои собственные области действия, утверждения и политики доступа OAuth 2.0. Во многих организациях есть сервер авторизации «по умолчанию».
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default'
} ;
var authClient = new OktaAuth ( config ) ;Вы также можете создавать и настраивать дополнительные серверы авторизации.
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/custom-auth-server-id'
} ;
var authClient = new OktaAuth ( config ) ; Эти параметры можно включить при создании экземпляра Okta Auth JS ( new OktaAuth(config) ).
issuer
️ Эта опция обязательна
URL-адрес вашей организации Okta или сервера аутентификации Okta. Об эмитенте
clientIdИдентификатор клиента предварительно зарегистрирован в Okta для потока аутентификации OIDC. Создание приложения Okta
redirectUri URL-адрес, на который перенаправляется при использовании token.getWithRedirect . Это должно быть указано в URI перенаправления входа в систему вашего приложения Okta. Если redirectUri не указан, по умолчанию используется текущий источник ( window.location.origin ). Настройка приложения Okta
postLogoutRedirectUri Укажите URL-адрес, на который должен быть перенаправлен браузер после выхода из системы. Этот URL-адрес должен быть указан в URI перенаправления выхода из системы вашего приложения Okta. Если не указано, будет использоваться источник вашего приложения ( window.location.origin ). Настройка приложения Okta |
scopes Укажите, какую информацию следует сделать доступной в возвращаемом id_token или access_token . Для OIDC необходимо включить openid в качестве одной из областей. По умолчанию ['openid', 'email'] . Список доступных областей см. в разделе Области и утверждения.
stateСтрока, предоставленная клиентом, которая будет передана на конечную точку сервера и возвращена в ответе OAuth. Это значение можно использовать для проверки ответа OAuth и предотвращения подделки межсайтового запроса (CSRF). По умолчанию используется случайная строка.
pkce Значение по умолчанию — true , что включает поток PKCE OAuth. Чтобы использовать неявный поток или поток кода авторизации, установите для pkce значение false .
dpop Значение по умолчанию — false . Установите значение true , чтобы включить DPoP (демонстрация доказательства владения (RFC9449))
См. Руководство: Включение DPoP.
При запросе токенов с использованием token.getWithRedirect значения будут возвращены в виде параметров, добавленных к redirectUri.
В большинстве случаев вам не потребуется устанавливать значение для responseMode . Значения по умолчанию установлены в соответствии со спецификацией OpenID Connect 1.0.
Для PKCE OAuth Flow код авторизации будет указан в поисковом запросе URL-адреса. Клиенты, использующие поток PKCE, могут вместо этого получать код авторизации во фрагменте хэша, установив для параметра responseMode значение «фрагмент».
Для неявного потока OAuth) токены будут находиться в хеш-фрагменте URL-адреса. Это невозможно изменить.
responseType Укажите тип ответа для аутентификации OIDC при использовании неявного потока OAuth. Значением по умолчанию является ['token', 'id_token'] которое будет запрашивать как токен доступа, так и токен идентификатора. Если pkce имеет true , токен доступа и идентификатора будут запрошены, и этот параметр будет игнорироваться. Для веб-приложений и собственных приложений, использующих поток authorization_code , для этого значения должно быть установлено значение "code" , а для pkce должно быть установлено значение false .
authorizeUrlУкажите собственный авторизационный URL для выполнения потока OIDC. По умолчанию указывается эмитент плюс «/v1/authorize».
userinfoUrlУкажите пользовательский userinfoUrl. По умолчанию указан эмитент плюс «/v1/userinfo».
tokenUrlУкажите собственный tokenUrl. По умолчанию указывается эмитент плюс «/v1/token».
ignoreSignature
️ Эту опцию следует использовать только для поддержки браузера и целей тестирования.
Подписи токена идентификатора проверяются по умолчанию при вызове token.getWithoutPrompt , token.getWithPopup , token.getWithRedirect и token.verify . Чтобы отключить проверку подписи токена идентификатора для этих методов, установите для этого значения значение true .
maxClockSkewПо умолчанию 300 (пять минут). Это максимальная разница в секундах между часами клиента и Okta при проверке токенов. Установка значения 0 не рекомендуется, так как это увеличивает вероятность того, что действительные токены не пройдут проверку.
ignoreLifetime
️ Этот параметр отключает проверку срока действия токена, что может привести к проблемам с уязвимостями безопасности. Эту опцию следует использовать в целях тестирования. Пожалуйста, устраните ошибку в своем приложении для производственной среды.
Срок действия токена проверяется с помощью maxClockSkew. Чтобы переопределить это и отключить проверку срока действия токена, установите для этого значения значение true .
transformAuthState Функция обратного звонка. Когда вызывается updateAuthState, создается новый объект authState. Предоставление функции transformAuthState позволяет вам изменять или заменять этот объект перед его сохранением и отправкой. Распространенным вариантом использования является изменение значения isAuthenticated. По умолчанию updateAuthState установит для authState.isAuthenticated значение true, если в tokenManager доступны токены с неистекшим сроком действия. Эту логику можно настроить так, чтобы она также требовала действующего сеанса единого входа Okta:
const config = {
// other config
transformAuthState : async ( oktaAuth , authState ) => {
if ( ! authState . isAuthenticated ) {
return authState ;
}
// extra requirement: user must have valid Okta SSO session
const 
