okta auth js
7.8.1
Okta Auth JavaScript SDK は、認証 API、OpenID Connect および OAuth 2.0 API の上に構築されており、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 との互換性は、次のオブジェクトにポリフィル/シムを追加することで実現できます。
️ 暗号ポリフィルは、優れた暗号化の鍵となる疑似乱数を生成するために使用される高品質のエントロピーのソースとしてオペレーティング システムを使用できません。そのため、私たちは暗号ポリフィルの安全性が低いという立場をとっており、それらを使用しないことをお勧めします。
このモジュールは、必要なすべてのポリフィルを実装するエントリポイントを提供します。
ブラウザーから Web ページ上で JS を使用している場合は、 node_modules/@okta/okta-auth-js/dist内容をパブリックにホストされているディレクトリにコピーし、 okta-auth-js.polyfill.jsファイルを<script>タグ内に記述します。これは、ポリフィルに依存する他のスクリプトよりも前にロードする必要があります。
Webpack や Browserify などのバンドラーを使用している場合は、アプリケーションのコードの先頭またはその近くで import または require @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 をデフォルトでブロックし始めています。この SDK でサポートされる Okta API のほとんどは Cookie に依存しませんが、Cookie に依存するメソッドがいくつかあります。サードパーティ Cookie がブロックされている場合、これらのメソッドは壊れます。
アプリケーションがこれらのメソッドのいずれかに依存している場合は、これらのメソッドの使用を避けるようにアプリケーションを書き直すか、サードパーティ Cookie を有効にする必要があることをユーザーに伝える必要があります。 Okta のエンジニアは現在、この問題に対するより良い長期的な解決策に取り組んでいます。
認証 SDK のインストールは簡単です。 npm パッケージ @okta/okta-auth-js を介してプロジェクトにこれを含めることができます。
以下も必要になります。
新しい Okta アプリケーションを作成するときに、アプリケーションの種類を指定できます。この SDK は、 SPA (シングルページ アプリケーション) またはWebアプリケーションで動作するように設計されています。 SPAアプリケーションは、すべてのロジックと認可フローをクライアント側で実行します。 Webアプリケーションはサーバー上で認証フローを実行します。
Okta 管理 UI からApplicationsをクリックし、アプリケーションを選択します。 Okta アプリケーションの構成は、アプリケーションのGeneralタブで表示および編集できます。
Okta アプリケーションを一意に識別する文字列。
ユーザーをサインインするために、アプリケーションはブラウザーを Okta がホストするサインイン ページにリダイレクトします。その後、Okta はユーザーに関する情報を使用してアプリケーションにリダイレクトします。 Okta でホストされるフローでこれがどのように機能するかについて詳しく学ぶことができます。
Okta アプリケーション設定でログイン リダイレクト URL をホワイトリストに登録する必要があります。
ユーザーをアプリおよび Okta からサインアウトした後、ユーザーをアプリケーション内の特定の場所にリダイレクトする必要があります。 Okta アプリケーション設定でサインアウト後の URL をホワイトリストに登録する必要があります。
次の場合は、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ブラウザーから Web ページ上で 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 リファレンス ドキュメントを参照することもできます。
⌛ 非同期メソッドは、成功時に解決される Promise を返します。エラーが発生した場合、Promise は拒否される可能性があります。
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : 'GHtf9iJdr60A9IYrR0jw' ,
redirectUri : 'https://acme.com/oauth2/callback/home' ,
} ;
var authClient = new OktaAuth ( config ) ;デフォルトでは、 OktaAuthの新しいインスタンスを作成しても、非同期の副作用は発生しません。ただし、トークンの自動更新、トークンの自動削除、クロス集計同期などの特定の機能では、 OktaAuthサービスとして実行されている必要があります。これは、タイムアウトがバックグラウンドで設定され、サービスが停止されるまで動作し続けることを意味します。 OktaAuthサービスを開始するには、作成直後、handleRedirect などの他のメソッドを呼び出す前に、 startメソッドを呼び出すだけです。すべてのバックグラウンド プロセスを終了するには、 stop呼び出します。詳細については、「サービス構成」を参照してください。
var authClient = new OktaAuth ( config ) ;
await authClient . start ( ) ; // start the service
await authClient . stop ( ) ; // stop the service注:サービスを開始すると、authStateManager.updateAuthState も呼び出されます。
型定義は、 package.jsonのtypesエントリを通じて暗黙的に提供されます。型をインポートすることで明示的に参照することもできます。
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 ) ;
} 3.6 より前の Typescript バージョンには、WebAuthn の型定義がありません。 IDX API での WebAuthn のサポートは@okta/[email protected]で導入されました。この問題を解決するには、パッケージ@types/webappsec-credential-managementバージョン^0.5.1をインストールしてください。
Web クライアントとネイティブ クライアントは、安全な場所に保存されているクライアント シークレットを使用する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 フローがデフォルトで使用されます。このライブラリは、ブラウザーと NodeJS アプリケーションの両方で PKCE をサポートします。 PKCE は、HTTPS 接続で実行する場合、ほとんどの最新ブラウザで広くサポートされています。 PKCE では、ブラウザがcrypto.subtle ( webcryptoとも呼ばれる) を実装する必要があります。最新のブラウザのほとんどは、安全なコンテキスト (HTTPS 接続上) で実行するときにこれを提供します。 PKCE には TextEncoder オブジェクトも必要です。これは、IE 11 および Edge < v79 を除くすべての主要なブラウザーで利用できます。サポートを追加するには、テキスト エンコーディングなどのポリフィル/シムを使用することをお勧めします。
ユーザーのブラウザが PKCE をサポートしていない場合、例外がスローされます。次の静的メソッドを使用して、構築前にブラウザが PKCE をサポートしているかどうかをテストできます。
OktaAuth.features.isPKCESupported()
️ 暗黙的なフローの使用は強くお勧めしません。可能であれば、PKCE および/またはクライアント認証情報を使用してください。
導入環境で PKCE フローをサポートできない場合は、オプションとして暗黙的 OAuth フローを使用できます。これはほとんどのブラウザで広くサポートされており、安全でない HTTP 接続でも動作します。暗黙的フローは、未加工のトークンがブラウザーの履歴に公開されるため、HTTPS 上であっても PKCE フローよりも安全性が低いことに注意してください。このため、可能であれば PKCE フローを使用することを強くお勧めします。
暗黙的フローは、 pkceオプションをfalseに設定することで有効にできます。
var config = {
pkce : false ,
// other config
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
} ;
var authClient = new OktaAuth ( config ) ;ユーザーをサインインするには、アプリケーションでブラウザーを Okta がホストするサインイン ページにリダイレクトする必要があります。
注: Okta でホストされるサインイン ページへの最初のリダイレクトでは、stateToken の有効期間が 1 時間に設定されたトランザクションが開始されます。
認証が成功すると、ブラウザはユーザーに関する情報とともにアプリケーションにリダイレクトされます。好みに応じて、次のコールバック戦略を使用できます。
ほとんどのアプリケーションは、サインイン ページとは別の特別なルート/ページを使用して OAuth コールバックを処理します。ただし、一部の SPA アプリケーションにはルーティング ロジックがなく、すべてを 1 つのページで処理する必要があります。
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 および応答モード "query" を使用することをお勧めします (これは PKCE のデフォルトです)。暗黙的なフローでは、ハッシュ ルーターがフラグメントを書き換える可能性があるため、ハッシュ内のトークンによって予測できない結果が生じる可能性があります。
TokenManagerにトークンを追加します: tokenManager.setTokens参照: DPoP (所有証明のデモンストレーション) - RFC9449
DPoP有効にする必要があります (ガイド: 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)
リソース サーバーは、送信される DPoP プルーフに含まれる nonce 値を提供することを選択することもできます。認可サーバーと同じ方法で、DPoP-Nonce ヘッダーを使用して 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のみです。これは、Okta 認可サーバーへの URL です。
Okta 組織の URL を発行者として使用できます。これにより、デフォルトの認可ポリシーが適用され、組織レベルにスコープされたトークンが発行されます。
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
️ このオプションは必須です
Okta 組織または Okta 認証サーバーの URL。発行者について
clientIdOIDC 認証フロー用に Okta に事前登録されたクライアント ID。 Okta アプリケーションの作成
redirectUri token.getWithRedirectを使用するときにリダイレクトされる URL。これは、Okta アプリケーションのログイン リダイレクト URI にリストされている必要があります。 redirectUriが指定されていない場合、デフォルトは現在の原点 ( window.location.origin ) になります。 Okta アプリケーションの構成
postLogoutRedirectUriサインアウト後にブラウザがリダイレクトされる URL を指定します。この URL は、Okta アプリケーションのログアウト リダイレクト URI にリストされている必要があります。指定しない場合は、アプリケーションの原点 ( window.location.origin ) が使用されます。 Okta アプリケーションの構成 |
scopes返されたid_tokenまたはaccess_tokenで利用できるようにする情報を指定します。 OIDC の場合、スコープの 1 つとしてopenid含める必要があります。デフォルトは['openid', 'email']です。使用可能なスコープのリストについては、「スコープとクレーム」を参照してください。
stateサーバーエンドポイントに渡され、OAuth 応答で返されるクライアント提供の文字列。この値は、OAuth 応答を検証し、クロスサイト リクエスト フォージェリ (CSRF) を防止するために使用できます。デフォルトはランダムな文字列です。
pkceデフォルト値はtrueで、PKCE OAuth フローが有効になります。暗黙的フローまたは認可コード フローを使用するには、 pkce falseに設定します。
dpopデフォルト値はfalseです。 DPoP (所有証明のデモンストレーション (RFC9449)) を有効にするにはtrueに設定します。
ガイドを参照してください: DPoP の有効化
token.getWithRedirect を使用してトークンをリクエストすると、値が redirectUri に追加されるパラメーターとして返されます。
ほとんどの場合、 responseModeの値を設定する必要はありません。デフォルトは、OpenID Connect 1.0 仕様に従って設定されます。
PKCE OAuth Flow) の場合、認証コードは URL の検索クエリに含まれます。 PKCE フローを使用するクライアントは、responseMode オプションを「fragment」に設定することで、代わりにハッシュ フラグメントで認証コードを受信することを選択できます。
Implicit OAuth Flow) の場合、トークンは URL のハッシュ フラグメントに含まれます。これは変更できません。
responseType Implicit OAuth Flowを使用する場合のOIDC認証の応答タイプを指定します。デフォルト値は['token', 'id_token']で、アクセス トークンと ID トークンの両方が要求されます。 pkceがtrueの場合、アクセス トークンと ID トークンの両方が要求され、このオプションは無視されます。 authorization_codeフローを使用する Web/ネイティブ アプリケーションの場合、この値を"code"に設定し、 pkce falseに設定する必要があります。
authorizeUrlOIDC フローを実行するカスタム authorizeUrl を指定します。デフォルトは、発行者に「/v1/authorize」を加えたものです。
userinfoUrlカスタム userinfoUrl を指定します。デフォルトは、発行者に「/v1/userinfo」を加えたものです。
tokenUrlカスタム tokenUrl を指定します。デフォルトは発行者に「/v1/token」を加えたものです。
ignoreSignature
️ このオプションは、ブラウザのサポートとテストの目的でのみ使用してください。
ID トークンの署名は、 token.getWithoutPrompt 、 token.getWithPopup 、 token.getWithRedirect 、およびtoken.verifyが呼び出されたときにデフォルトで検証されます。これらのメソッドの ID トークン署名の検証を無効にするには、この値をtrueに設定します。
maxClockSkewデフォルトは 300 (5 分) です。これは、トークンの検証時にクライアントのクロックと Okta のクロックの間で許容される最大差 (秒単位) です。これを 0 に設定すると、有効なトークンが検証に失敗する可能性が高くなるため、お勧めできません。
ignoreLifetime
️ このオプションはトークンの有効期間検証を無効にするため、セキュリティの脆弱性の問題が発生する可能性があります。このオプションはテスト目的で使用する必要があります。実稼働環境用の独自のアプリでエラーを処理してください。
トークンの有効期間は、maxClockSkew を使用して検証されます。これをオーバーライドしてトークンの有効期間検証を無効にするには、この値をtrueに設定します。
transformAuthStateコールバック関数。 updateAuthState が呼び出されると、新しい authState オブジェクトが生成されます。 transformAuthState関数を提供すると、このオブジェクトを保存および発行する前に変更または置換できます。一般的な使用例は、isAuthenticated の意味を変更することです。デフォルトでは、有効期限が切れていないトークンが tokenManager から入手できる場合、 updateAuthState authState.isAuthenticated true に設定します。このロジックは、有効な 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 
