okta auth js
7.8.1
Okta Auth JavaScript SDK สร้างขึ้นจาก Authentication 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 สามารถทำได้โดยการเพิ่ม polyfill/shims สำหรับออบเจ็กต์ต่อไปนี้:
crypto polyfills ไม่สามารถใช้ระบบปฏิบัติการเป็นแหล่งเอนโทรปีคุณภาพดีที่ใช้ในการสร้างตัวเลขสุ่มหลอกซึ่งเป็นกุญแจสำคัญในการเข้ารหัสที่ดี ด้วยเหตุนี้ เราจึงถือว่า crypto polyfills มีความปลอดภัยน้อยกว่า และเราขอแนะนำไม่ให้ใช้
โมดูลนี้จัดเตรียมจุดเริ่มต้นที่ใช้โพลีฟิลที่จำเป็นทั้งหมด
หากคุณใช้ JS บนหน้าเว็บจากเบราว์เซอร์ คุณสามารถคัดลอกเนื้อหา node_modules/@okta/okta-auth-js/dist ไปยังไดเร็กทอรีที่โฮสต์แบบสาธารณะ และรวมการอ้างอิงไปยัง okta-auth-js.polyfill.js ในแท็ก <script> ควรโหลดก่อนสคริปต์อื่นๆ ที่ขึ้นอยู่กับโพลีฟิล
หากคุณใช้บันเดิลเช่น Webpack หรือ Browserify คุณสามารถนำเข้าการนำเข้าหรือต้องการ @okta/okta-auth-js/polyfill ที่หรือใกล้กับจุดเริ่มต้นของโค้ดแอปพลิเคชันของคุณ:
import '@okta/okta-auth-js/polyfill' ;หรือ
require ( '@okta/okta-auth-js/polyfill' ) ;ชุด 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 >
เวอร์ชันที่แสดงในตัวอย่างนี้อาจเก่ากว่าเวอร์ชันปัจจุบัน เราขอแนะนำให้ใช้เวอร์ชันสูงสุดที่มีอยู่
เบราว์เซอร์จำนวนมากเริ่มบล็อกคุกกี้ข้ามต้นทางหรือคุกกี้ "บุคคลที่สาม" ตามค่าเริ่มต้น แม้ว่า Okta API ส่วนใหญ่ที่ SDK นี้รองรับจะไม่ต้องใช้คุกกี้ แต่ก็มีบางวิธีที่ใช้ได้ วิธีการเหล่านี้จะใช้งานไม่ได้หากคุกกี้ของบุคคลที่สามถูกบล็อก:
หากแอปพลิเคชันของคุณขึ้นอยู่กับวิธีการเหล่านี้ คุณควรพยายามเขียนแอปพลิเคชันของคุณใหม่เพื่อหลีกเลี่ยงการใช้วิธีการเหล่านี้ หรือสื่อสารกับผู้ใช้ของคุณว่าพวกเขาต้องเปิดใช้งานคุกกี้ของบุคคลที่สาม ขณะนี้วิศวกรของ Okta กำลังทำงานเพื่อแก้ไขปัญหานี้ในระยะยาวให้ดีขึ้น
การติดตั้ง Authentication SDK นั้นง่ายดาย คุณสามารถรวมไว้ในโปรเจ็กต์ของคุณผ่านแพ็คเกจ npm ของเรา @okta/okta-auth-js
คุณจะต้องมี:
เมื่อสร้างแอปพลิเคชัน Okta ใหม่ คุณสามารถระบุประเภทแอปพลิเคชันได้ SDK นี้ออกแบบมาเพื่อทำงานร่วมกับ SPA (แอปพลิเคชันหน้าเดียว) หรือแอปพลิเคชัน Web แอปพลิเคชัน SPA จะดำเนินการตรรกะและการอนุญาตโฟลว์ฝั่งไคลเอ็นต์ทั้งหมด Web แอปพลิเคชันจะดำเนินการขั้นตอนการอนุญาตบนเซิร์ฟเวอร์
จาก Okta Admin UI คลิก 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 ฉบับเต็มได้
⌛ เมธอด Async ส่งคืนสัญญาซึ่งจะแก้ไขเมื่อสำเร็จ สัญญาอาจปฏิเสธหากมีข้อผิดพลาดเกิดขึ้น
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 version ^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 หากต้องการเพิ่มการรองรับ เราขอแนะนำให้ใช้โพลีฟิล/ชิม เช่น การเข้ารหัสข้อความ
หากเบราว์เซอร์ของผู้ใช้ไม่รองรับ 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 และ responseMode "query" (นี่คือค่าเริ่มต้นสำหรับ PKCE) ด้วยโฟลว์โดยนัย โทเค็นในแฮชอาจทำให้เกิดผลลัพธ์ที่คาดเดาไม่ได้เนื่องจากเราเตอร์แฮชอาจเขียนแฟรกเมนต์ใหม่
TokenManager : tokenManager.setTokensอ้างอิง: DPoP (สาธิตหลักฐานการครอบครอง) - RFC9449
DPoP ในแอปพลิเคชัน Okta ของคุณ (คำแนะนำ: กำหนดค่า DPoP)https เป็นสิ่งจำเป็น จำเป็นต้องมีบริบทที่ปลอดภัยสำหรับ WebCrypto.subtleIndexedDB (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 หรือสำหรับการสื่อสารกับ Authentication 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 Flow หากต้องการใช้ Implicit Flow หรือ Authorization Code Flow ให้ตั้งค่า pkce เป็น false
dpop ค่าเริ่มต้นเป็น false ตั้งค่าเป็น true เพื่อเปิดใช้งาน DPoP (สาธิตหลักฐานการครอบครอง (RFC9449))
ดูคำแนะนำ: การเปิดใช้งาน DPoP
เมื่อร้องขอโทเค็นโดยใช้ค่า token.getWithRedirect จะถูกส่งกลับเป็นพารามิเตอร์ที่ต่อท้าย เปลี่ยนเส้นทาง Uri
ในกรณีส่วนใหญ่ คุณไม่จำเป็นต้องตั้งค่าสำหรับ responseMode ค่าเริ่มต้นจะถูกตั้งค่าตามข้อกำหนด OpenID Connect 1.0
สำหรับ PKCE OAuth Flow) รหัสการให้สิทธิ์จะอยู่ในคำค้นหาของ URL ไคลเอนต์ที่ใช้โฟลว์ PKCE สามารถเลือกรับรหัสการอนุญาตในส่วนแฮชแทนได้โดยการตั้งค่าตัวเลือก responseMode เป็น "แฟรกเมนต์"
สำหรับ Implicit OAuth Flow) โทเค็นจะอยู่ในส่วนแฮชของ URL สิ่งนี้ไม่สามารถเปลี่ยนแปลงได้
responseType ระบุประเภทการตอบสนองสำหรับการตรวจสอบสิทธิ์ OIDC เมื่อใช้ Implicit OAuth Flow ค่าเริ่มต้นคือ ['token', 'id_token'] ซึ่งจะขอทั้งโทเค็นการเข้าถึงและโทเค็น ID หาก pkce เป็น true ระบบจะขอทั้งโทเค็นการเข้าถึงและ ID และตัวเลือกนี้จะถูกละเว้น สำหรับแอปพลิเคชันบนเว็บ/เนทิฟที่ใช้โฟลว์ authorization_code ค่านี้ควรตั้งค่าเป็น "code" และควรตั้ง pkce เป็น false
authorizeUrlระบุ authorizeUrl ที่กำหนดเองเพื่อดำเนินการโฟลว์ OIDC ค่าเริ่มต้นคือผู้ออกบวก "/v1/authorize"
userinfoUrlระบุ userinfoUrl ที่กำหนดเอง ค่าเริ่มต้นเป็นผู้ออกบวก "/v1/userinfo"
tokenUrlระบุ tokenUrl ที่กำหนดเอง ค่าเริ่มต้นคือผู้ออกบวก "/v1/token"
ignoreSignature
ควรใช้ตัวเลือกนี้เพื่อการสนับสนุนเบราว์เซอร์และการทดสอบเท่านั้น
ลายเซ็นโทเค็น ID ได้รับการตรวจสอบตามค่าเริ่มต้นเมื่อมีการเรียก token.getWithoutPrompt , token.getWithPopup , token.getWithRedirect และ token.verify หากต้องการปิดใช้งานการตรวจสอบลายเซ็นโทเค็น ID สำหรับวิธีการเหล่านี้ ให้ตั้งค่านี้เป็น true
maxClockSkewค่าเริ่มต้นคือ 300 (ห้านาที) นี่คือความแตกต่างสูงสุดที่อนุญาตระหว่างนาฬิกาของลูกค้าและของ Okta ในหน่วยวินาทีเมื่อตรวจสอบโทเค็น ไม่แนะนำให้ตั้งค่านี้เป็น 0 เนื่องจากจะเพิ่มโอกาสที่โทเค็นที่ถูกต้องจะไม่ผ่านการตรวจสอบ
ignoreLifetime
ตัวเลือกนี้จะปิดใช้การตรวจสอบความถูกต้องตลอดอายุการใช้งานของโทเค็น ซึ่งอาจทำให้เกิดปัญหาช่องโหว่ด้านความปลอดภัยได้ ตัวเลือกนี้ควรใช้เพื่อการทดสอบ โปรดจัดการข้อผิดพลาดในแอปของคุณเองสำหรับสภาพแวดล้อมการใช้งานจริง
อายุการใช้งานโทเค็นได้รับการตรวจสอบโดยใช้ maxClockSkew หากต้องการแทนที่สิ่งนี้และปิดใช้การตรวจสอบอายุการใช้งานโทเค็น ให้ตั้งค่านี้เป็น true
transformAuthState ฟังก์ชั่นการโทรกลับ เมื่อเรียก updateAuthState วัตถุ authState ใหม่จะถูกสร้างขึ้น การระบุฟังก์ชัน transformAuthState ทำให้คุณสามารถแก้ไขหรือแทนที่อ็อบเจ็กต์นี้ก่อนที่จะจัดเก็บและปล่อยออกมา กรณีการใช้งานทั่วไปคือการเปลี่ยนความหมายของ isAuthenticated ตามค่าเริ่มต้น updateAuthState จะตั้ง authState.isAuthenticated เป็นจริง หากโทเค็นที่ยังไม่หมดอายุพร้อมใช้งานจาก tokenManager ตรรกะนี้สามารถปรับแต่งให้ต้องใช้เซสชัน 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 
