okta signin widget
7.25.1
Okta登录小部件是一个JavaScript小部件，可提供完整的特色且可自定义的登录体验，可用于在Web和移动应用程序中身份验证和注册用户。
该小部件在Okta的默认签名页面上使用，以启动Okta SSO会话，并在Web浏览器中设置Okta Session Cookie。它还可以执行OIDC流程，以轻松将您的Web或移动应用程序集成到Okta平台中。
可以配置自定义OKTA托管的标志页面，以使用组织的域名和品牌。
该小部件还可以直接嵌入组织的网络或移动应用程序中，以获得无缝的用户体验。
有关如何使用登录小部件开始使用的更多信息，请参见使用指南。
yarn link的本地开发工作流程Okta身份引擎（OIE）是一种平台服务，允许企业构建根据其组织需求量身定制的更灵活的访问体验。 OKTA登录小部件在所有使用方案中都支持OIE。
注意：除非另有说明，否则此读书我假设您正在使用身份引擎。可以在本文档中找到有关与经典引擎一起使用小部件的信息
登录小部件是独立的，在运行时不需要其他框架。但是，您的应用程序需求可能会有某些功能，例如代币存储，续订或验证，而小部件不提供这些功能。
这些SDK与Okta登录小部件完全兼容，并提供实用程序，以帮助将OKTA身份验证在您自己的应用程序中端到端集成。
完整的示例应用程序显示了Okta登录小部件在Okta托管和嵌入式方案中的使用情况。
有几种使用Okta登录小部件的方法：
OKTA为您的组织提供了默认的登录页面，该页面托管在您组织的Okta URL上。
OKTA支持一个选项，可以使用高度可自定义的OKTA托管页面创建自定义域。
您可以将小部件直接嵌入您的应用程序中。
OKTA提供了一个登录页面，可在您的组织的URL上找到，该页面允许用户完成整个授权流，启动SSO（单登录）会话，并在Web浏览器中设置Okta会话Cookie。您可以使用背景图像和徽标自定义此页面。默认情况下，在此页面上登录将用户重定向到Okta用户仪表板。
默认的OKTA托管登录页面还可以在OIDC应用程序中验证用户。您的应用程序可以重定向到登录页面以执行身份验证流，然后OKTA将用户重定向到应用程序回调。 OKTA提供多种语言的SDK，以帮助构建重定向URL并作为托管流的一部分处理登录回调。
OKTA提供了几个完整的示例应用程序，这些应用程序演示了如何使用Okta托管流程。
Okta还提供了一个可以自定义的托管登录页面，以便在自定义域下可用，该域是您公司顶级域的子域。尽管该页面是由Okta托管的，但您可以以许多强大的方式自定义此页面的模板。
就您的应用程序而言，自定义的小部件的行为与默认的OKTA托管小部件相同，您可以使用相同的托管流程。
注意：页面上将有一个配置对象，其中包含所有必需的值和启用功能。您很可能不需要修改此对象。如果您发现确实需要修改此配置，请注意不要覆盖或删除任何必需的值。
对于完全无缝的体验，可以进行最高的自定义水平，您可以将登录小部件直接嵌入到应用程序中。这允许完全使用小部件的配置和API。
在许多情况下，使用嵌入式小部件，客户端网络和本机应用程序可以避免托管流的往返重定向。请参阅Shownignin。
服务器端Web应用程序将接收OAuth令牌服务器端，因此他们必须处理重定向回调。这些应用程序应使用showigninandredirect。
您可以通过包括从OKTA CDN中拉动小部件的脚本标签，或将NPM模块捆绑到应用程序中，将登录小部件嵌入到您的应用程序中。
如果您想要一种简单的方法来开始使用小部件，那么直接从CDN加载我们的资产是一个不错的选择，没有现有的构建过程，该过程利用了NPM或纱线来用于外部依赖项，或任何其他原因'想将登录小部件捆绑到您的应用程序中。
标准捆绑包（ okta-sign-in.min.js ）包括对经典引擎和身份引擎的支持。它还包括一个多填充，以确保与旧浏览器（例如IE11）的兼容性。如果您的应用程序不需要支持IE11，则可以包含no-polyfill捆绑包，而是减少首次用户的加载时间。只有在必要时，可以将独立的polyfill束有条件地包含在页面上，以添加对较旧浏览器的支持。
如果您的组织已升级到身份引擎，则可以使用较小的oie捆绑包。
| 捆 | 文件名 | 大约尺寸 | 经典引擎 | 身份引擎 | 多填充 | 笔记 |
|---|---|---|---|---|---|---|
| 标准 | Okta-sign-in.min.js | 1.7 MB | ✅ | ✅ | ✅ | 标准捆绑包包括所有内容 |
| 没有polyfill | okta-sign-in.no-polyfill.min.js | 1.7 MB | ✅ | ✅ | 没有多填充的标准捆绑包 | |
| OIE | Okta-sign-in.oie.min.js | 1.3 MB | ✅ | 启用OIE的组织较小的捆绑包 | ||
| 经典的 | Okta-sign-in.classic.min.js | 1.1 MB | ✅ | 仅用于经典引擎的较小捆 | ||
| 多填充 | Okta-sign-in.polyfill.min.js | 108KB | ✅ | 独立的聚填充束。可以与不包括多填充的小部件捆绑包一起使用。 |
要通过CDN嵌入登录小部件，请在HTML中包含指向JS和CSS文件的链接：
<!-- Latest CDN production Javascript and CSS -->
< script src =" https://global.oktacdn.com/okta-signin-widget/7.25.1/js/okta-sign-in.min.js " type =" text/javascript " integrity =" sha384-8QHSy1n8imbyR7imair5z4njOEYiZZk5gqBOJYbbUN3W6HQwW3PZ9lYQiybespeW " crossorigin =" anonymous " > </ script >
< link href =" https://global.oktacdn.com/okta-signin-widget/7.25.1/css/okta-sign-in.min.css " type =" text/css " rel =" stylesheet " integrity =" sha384-63aTBe2wMqzMRsDHNmlF/FreSWmf3p08BhUDoPlzVf3d+stbkfWtqmdyJ4He5m3m " crossorigin =" anonymous " />注意： CDN URL包含一个版本号。此数字对于JavaScript和CSS文件都应该相同，并匹配版本页面上的一个版本。我们建议使用最新的小部件版本。
当使用包含多填充的一个捆绑包时，您可能需要有条件地加载独立的聚填充束。多填充应在小部件束之前加载：
<!-- Polyfill for older browsers -->
< script src =" https://global.oktacdn.com/okta-signin-widget/7.25.1/js/okta-sign-in.polyfill.min.js " type =" text/javascript " integrity =" sha384-QzQIGwIndxyBdHRQOwgjmQJLod6LRMchZyYg7RUq8FUECvPvreqauQhkU2FF9EGD " crossorigin =" anonymous " > </ script >
<!-- Widget bundle for Okta Identity Engine -->
< script src =" https://global.oktacdn.com/okta-signin-widget/7.25.1/js/okta-sign-in.oie.min.js " type =" text/javascript " integrity =" sha384-T4d68QBaFQ/b3kDy8qubuXDALwWgBRfP0JsfZsYRzZNlIXflVE2svwIHrPaivLyd " crossorigin =" anonymous " > </ script >
<!-- CSS for widget -->
< link href =" https://global.oktacdn.com/okta-signin-widget/7.25.1/css/okta-sign-in.min.css " type =" text/css " rel =" stylesheet " integrity =" sha384-63aTBe2wMqzMRsDHNmlF/FreSWmf3p08BhUDoPlzVf3d+stbkfWtqmdyJ4He5m3m " crossorigin =" anonymous " />使用我们的NPM模块是一个不错的选择：
安装 @Okta/Okta-Signin-Widget：
# Run this command in your project root folder
# yarn
yarn add @okta/okta-signin-widget
# npm
npm install @okta/okta-signin-widget --save这将在您的项目的node_modules目录中安装最新版本的登录小部件。
注意：如果您使用的是打字稿，则需要在tsconfig.json中启用合成导入。
{
...
"compilerOptions" : {
"allowSyntheticDefaultImports" : true ,
...
}
} Angular（打字）项目需要Simliar配置，也需要在您的tsconfig.json中
{
...
"angularCompilerOptions" : {
"allowSyntheticDefaultImports" : true ,
...
}
}小部件源文件和资产已安装到node_modules/@okta/okta-signin-widget/dist ，并具有此目录结构：
node_modules/@okta/okta-signin-widget/dist/
├── css/
│ │ # Main CSS file for widget styles
│ └── okta-sign-in.min.css
│
│ # Base font and image files that are used in rendering the widget
├── font/
│
├── img/
│
├── js/
│ │ # CDN JS file that exports the OktaSignIn object in UMD format. This is
│ │ # packaged with everything needed to run the widget, including 3rd party
│ │ # vendor files and polyfills.
│ ├── okta-sign-in.min.js
| |
│ │ # CDN JS file bundled without polyfills.
│ ├── okta-sign-in.no-polyfill.min.js
│ │
│ │ # Development version of okta-sign-in.min.js. Equipped with helpful
│ │ # console warning messages for common configuration errors.
│ └── okta-sign-in.js
│
│ # Localized strings that are used to display all text and labels in the
│ # widget. Three output formats are included - json and properties
├── labels/
│
│ # Sass files that are used to generate the widget css. If you are already
│ # using Sass in your project, you can include these helper files to make
│ # generating your custom theme easier
└── sass/安装后：
将资产复制到将分发给您的公开托管站点的文件夹。您需要复制的文件夹是css ， font ， img ， js和labels 。
如果您使用WebPack，浏览器或另一个了解node_modules格式的模块捆绑系统，则无需将js目录复制在页面中，而是将其包含在您的页面中，而是在构建中需要登录小部件。
// Load the Sign-In Widget module
var OktaSignIn = require ( '@okta/okta-signin-widget' ) ;
// Use OktaSignIn
var signIn = new OktaSignIn ( /* configOptions */ ) ;源地图作为外部.map文件提供。如果您使用的是WebPack，则可以使用源映射插件加载这些插件。
如果要使用style-loader或mini-css-tracktract-plugin中包含窗口小部件样式，请使用以下导入：
import '@okta/okta-signin-widget/css/okta-sign-in.min.css' ;注意：如果使用浏览器将应用程序捆绑在一起，则需要使用--noparse选项：
browserify main.js
--noparse= $PWD /node_modules/@okta/okta-signin-widget/dist/js-okta-sign-in.entry.js
--outfile=bundle.js如果您需要支持IE11，请确保将ES6 polyfills与Bundler一起使用。小部件通过导出提供所有必要的多填充：
const polyfill = require('@okta/okta-signin-widget/polyfill');
或者
import polyfill from '@okta/okta-signin-widget/polyfill';
这些简单的示例应该可以帮助您开始使用登录小部件。有关完整的端到端解决方案，请查看我们的示例应用程序。
单页应用程序（SPA）在浏览器中完全运行。 SPA应用程序使用客户端流并将OAuth代币存储在基于浏览器的存储中。
注意：有关这些配置值的更多信息，请参见配置
var signIn = new OktaSignIn (
{
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
}
) ;
signIn . showSignIn ( {
// Assumes there is an empty element on the page with an id of 'osw-container'
el : '#osw-container'
} ) . then ( function ( res ) {
// Most flows will not require any redirection. In these cases, tokens will be returned directly.
// res.tokens is an object
oktaSignIn . authClient . handleLoginRedirect ( res . tokens ) ;
} ) . catch ( function ( error ) {
// This function is invoked with errors the widget cannot recover from:
// Known errors: CONFIG_ERROR, UNSUPPORTED_BROWSER_ERROR
} ) ; Web应用程序主要运行在服务器上。执行客户端的小部件将嵌入到HTML页面中，该页面包括配置和渲染小部件的脚本块。 OAuth令牌将在应用程序的登录重定向回调上接收服务器端。
注意：有关这些配置值的更多信息，请参见配置
var signIn = new OktaSignIn (
{
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
state : '{{state passed from backend}}' , // state can be any string, it will be passed on redirect callback
codeChallenge : '{{PKCE code challenge from backend}}' , // PKCE is required for interaction code flow
}
) ;
// When the authorization flow is complete there will be a redirect to Okta.
// Okta's servers will process the information and then redirect back to your application's `redirectUri`
// If successful, an authorization code will exist in the URL as the "code" query parameter
// If unsuccesful, there will be an "error" query parameter in the URL
signIn . showSignInAndRedirect ( {
// Assumes there is an empty element on the page with an id of 'osw-container'
el : '#osw-container'
} ) . catch ( function ( error ) {
// This function is invoked with errors the widget cannot recover from:
// Known errors: CONFIG_ERROR, UNSUPPORTED_BROWSER_ERROR
} ) ; 除默认身份验证流外，小部件还支持几个预定义的流，这使您可以为几个常见用例提供单用途的HTML页面。
默认情况下，Okta登录小部件将进行当前流程或开始新的身份验证流。该flow选项允许将小部件引导到特定视图中，例如寄存器，解锁或重置密码。支持流：
注意：仅当管理员配置组织以允许所需的操作时，特定流程才能起作用（例如：如果不启用了管理控制台中的配置文件注册（用户注册），请以流量为
flow: 'signup'导致错误）
// login.html
new OktaSignIn ( {
flow : 'login'
} ) ;
// signup.html
new OktaSignIn ( {
flow : 'signup'
} ) ;
// reset_password.html
new OktaSignIn ( {
flow : 'resetPassword'
} ) ;
// unlock_account.html
new OktaSignIn ( {
flow : 'unlockAccount'
} ) ; 当您的应用程序在浏览器中重新加载作为流程的一部分时，会发生重定向回调。在重定向回调期间，该应用程序是在OKTA应用程序配置中定义的特定URL路径上加载的。大多数回调只能处理一次，如果尝试处理两次，将产生错误。通常，在处理回调逻辑之后，该应用程序将自身重定向到已知或先前保存的URL路径，以避免在重新加载页面上错误。
注意：大多数应用程序都应准备处理一个或多个重定向回调。根据应用程序登录策略的配置方式，某些水疗应用程序可能可以在没有任何重定向的情况下接收令牌。但是，如果策略包括与社交 / IDP提供商签署或允许使用电子邮件验证验证或帐户恢复，则需要添加逻辑。
OAuth回调是交互代码流的最后一步。关于成功的身份验证，浏览器将通过信息重定向到Okta，以开始新的会话。 Okta的服务器处理信息，然后将其重定向到您的应用程序的redirectUri 。如果成功，则在URL中以相互作用代码为互动码，作为interaction_code查询参数。如果不成功，则URL中有一个error和error_description查询参数。无论是否成功，最初通过您的应用程序传递给小部件的state参数也将在重定向上返回。这可以由服务器端Web应用程序使用，以将回调与正确的用户会话匹配。
所有Web应用程序都将处理OAuth回调。对于水疗应用程序，在许多情况下，登录策略将不需要重定向，并且这些应用程序可以直接从Shownignin接收令牌。但是，如果出于任何原因（例如与社交 / IDP提供商集成），Spa应用程序需要重定向，则需要处理OAuth回调。因此，我们建议所有水疗应用程序都应准备处理OAuth回调。
注意：小部件不能直接处理OAuth回调。服务器端Web应用程序可以使用我们的SDK之一来帮助处理回调。 SPA应用程序可以使用Okta-Auth-JS SDK，该应用程序包含在登录小部件作为
authClient属性中。
Spa应用程序可以使用内置的authClient处理OAuth回调客户端：
// https://myapp.mycompany.com/login/callback?interaction_code=ABC&state=XYZ
if ( signIn . authClient . isLoginRedirect ( ) ) {
await signIn . authClient . handleLoginRedirect ( ) ;
} 与第三方IDP签署后，用户将重定向回到应用程序的redirectUri 。如果用户不需要进一步的输入，那么这将是包含interaction_code参数的OAUTH回调。如果需要进一步的输入，则回调将包含一个带有value interaction_required error参数。在这种情况下，应再次加载登录小部件，以便流量可以继续。
服务器端Web和Spa应用程序都应查找error查询参数，如果值是interaction_required ，则应使用与第一个渲染相同的配置再次渲染窗口小部件。 state参数还将在回调上传递，该回调可用于将请求与用户的应用程序会话匹配。小部件将自动进行交易。
如果您的登录策略使用电子邮件魔术链接/OTP，则您的应用程序将需要实现电子邮件验证回调。用户单击电子邮件中的链接后，将它们重定向回到应用程序的email verify callback URI 。传递给应用程序的查询参数包括state和otp 。与Social/IDP回调一样，应使用相同的配置再次渲染小部件。此外， otp应传递给小部件的构造函数。
注意：有关这些配置值的更多信息，请参见配置
var signIn = new OktaSignIn (
{
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
state : '{{state from URL}}' ,
otp : '{{otp from URL}}'
}
) ; 使用提供的选项创建一个新的实例。
对于使用自定义的Okta托管小部件的应用程序，页面上将有一个配置对象，其中包含所有必需的值。您很可能不需要修改此对象。
对于使用嵌入式小部件的应用程序，您需要提供OIDC配置：
注意：有关这些配置值的更多信息，请参见配置
var signIn = new OktaSignIn (
{
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
}
) ;将小部件渲染到DOM。关于成功，承诺决心。错误，承诺拒绝。如果登录策略需要重定向到OKTA或其他身份提供商（IDP），则浏览器将重定向，并且承诺将无法解决。响应和错误与Renderel相同。
注意：这是为水疗应用程序渲染小部件的推荐方法。服务器端Web应用程序应改用ShowignInAndRedirect方法。
showSignIn接受与小部件构造函数相同的选项。传递给该方法的选项将覆盖构造函数的选项。
注意：有关这些配置值的更多信息，请参见配置
var signIn = new OktaSignIn ( {
issuer : 'https://{yourOktaDomain}/oauth2/default'
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
} ) ;
oktaSignIn . showSignIn ( {
// Assumes there is an empty element on the page with an id of ‘osw-container’
el : ‘ # osw - container’ ,
} ) . then ( response => {
oktaSignIn . authClient . handleLoginRedirect ( res . tokens ) ;
} ) . catch ( function ( error ) {
// This function is invoked with errors the widget cannot recover from:
// Known errors: CONFIG_ERROR, UNSUPPORTED_BROWSER_ERROR
console . log ( 'login error' , error ) ;
} ) ;将小部件渲染到DOM。关于成功的身份验证，浏览器将通过信息重定向到Okta，以开始新的会话。 Okta的服务器将处理信息，然后将其重定向回到您的应用程序的redirectUri 。如果成功，则在URL中作为interaction_code查询参数存在一个交互代码。如果不成功，则URL中会有error和error_description查询参数。无论是否成功，传递给小部件的state参数也将在重定向上返回。这可以由您的服务器端Web应用程序使用，以将回调与正确的用户会话匹配。
showSignInAndRedirect接受与小部件构造函数相同的选项。传递给该方法的选项将覆盖构造函数的选项。
注意：有关这些配置值的更多信息，请参见配置
var signIn = new OktaSignIn ( {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
state : '{{state passed from backend}}' , // state can be any string, it will be passed on redirect callback
codeChallenge : '{{PKCE code challenge from backend}}' , // PKCE is required for interaction code flow
} ) ;
signIn . showSignInAndRedirect ( {
// Assumes there is an empty element on the page with an id of 'osw-container'
el : '#osw-container'
} ) . catch ( function ( error ) {
// This function is invoked with errors the widget cannot recover from:
// Known errors: CONFIG_ERROR, UNSUPPORTED_BROWSER_ERROR
} ) ;隐藏小部件，但将小部件保留在DOM中。
signIn . hide ( ) ;如果隐藏，则显示小部件。
signIn . show ( ) ;完全从DOM上卸下小部件。
signIn . remove ( ) ;订阅小部件发布的事件。
event - 订阅的活动callback - 函数 // Handle a 'ready' event using an onReady callback
signIn . on ( 'ready' , onReady ) ;退订小部件事件。如果没有提供回调，请取消订阅活动中的所有听众。
event - 可选活动要取消订阅callback - 用于订阅活动的可选回调 // Unsubscribe all listeners from all events
signIn . off ( ) ;
// Unsubscribe all listeners that have been registered to the 'ready' event
signIn . off ( 'ready' ) ;
// Unsubscribe the onReady listener from the 'ready' event
signIn . off ( 'ready' , onReady ) ;提供对登录小部件使用的对象的基础[@okta/okta-auth-js] []的访问权限。所有方法均在API参考中记录。
使用传递给小部件的值（例如clientId ， issuer ， redirectUri ， state和scopes配置了authClient 。小部件不直接支持的选项可以使用authParams对象传递给AUTHJS。
还可以在小部件之外创建和配置authClient ，并将其传递给小部件作为authClient选项。如果传递了authClient选项，则将忽略authParams 。
注意：有关这些配置值的更多信息，请参见配置
var authClient = new OktaAuth ( {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{yourClientId}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
} ) ;
var config = {
baseUrl : 'https://{yourOktaDomain}' ,
authClient : authClient ,
} ;
var signIn = new OktaSignIn ( config ) ;
// signIn.authClient === authClient如果未设置authClient选项，则将使用传递给窗口小部件和authParams选项创建一个实例：
注意：使用
authClient配置选项时，请确保安装和使用与已安装窗口小部件使用的@okta/okta-auth-js相同的版本。可以在已安装的小部件的package.json文件中找到此版本。
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{yourClientId}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
authParams : {
ignoreSignature : true
}
} ;
var signIn = new OktaSignIn ( config ) ;
// signIn.authClient.options.clientId === '{yourClientId}'
// signIn.authClient.options.ignoreSignature === true'添加一个异步挂钩函数，该功能将在视图呈现之前执行。
注意：有关这些配置值的更多信息，请参见配置
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{yourClientId}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
} ;
var signIn = new OktaSignIn ( config ) ;
signIn . before ( 'success-redirect' , async ( ) => {
// custom logic can go here. when the function resolves, execution will continue.
} ) ;注意：仅在使用OKTA身份引擎时支持此功能
添加一个异步挂钩函数，在视图呈现后将执行。
注意：有关这些配置值的更多信息，请参见配置
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{yourClientId}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
} ;
var signIn = new OktaSignIn ( config ) ;
signIn . after ( 'identify' , async ( ) => {
// custom logic can go here. when the function resolves, execution will continue.
} ) ; 如果您使用的是默认的OKTA托管标志页，则通过管理UI的Customization部分处理所有配置。
如果您使用的是自定义OKTA托管标志页，则页面上包含一个配置对象，其中包含所有必要的值。您可能不需要修改此对象，但是您可以将此对象用作起点并添加其他自定义。
对于嵌入式窗口小部件，您应该设置issuer ， clientId和redirectUri 。默认情况下，小部件将使用交互代码流在身份引擎上运行。小部件还可以通过将UseClassicengine选项设置为true来与经典引擎相反。 （有关经典引擎中运行的更多详细信息，请参见此文档。
所有嵌入式小部件都应设置以下基本选项： issuer ， clientId和redirectUri 。
注意：Okta主持的小部件不应设置这些值。
授权服务器的URL将向您的应用程序发布OAuth代币。
注意：
https://{yourOktaDomain}可以是任何OKTA组织。请参阅我们的开发人员指南，以获取有关查找Okta域的帮助。
使用“默认”自定义授权服务器的基本配置：
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
}可以指定不同的自定义授权服务器：
var config = {
issuer : 'https://{yourOktaDomain}/oauth2/custom' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
}某些应用程序，例如需要访问OKTA用户API的应用程序，将希望将Okta组织授权服务器用作发行人。在这种情况下， issuer与您的Okta域匹配：
var config = {
issuer : 'https://{yourOktaDomain}' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
}注意：OKTA组织授权服务器仅用于访问OKTA用户API，并且不支持标准自定义授权服务器的所有功能，例如访问令牌上的自定义范围。通常建议使用自定义授权服务器来保护对组织资源的访问。
注意：此配置值可以在Okta Admin UI中找到。请参阅我们的开发人员指南以寻求找到应用程序客户端的帮助
应用程序的客户ID。
注意：此配置值可以在应用程序的“常规设置”下的Okta Admin UI中找到
用于OAuth回调的URI。
默认为false 。默认情况下，小部件将使用身份引擎上的交互代码流。将useClassicEngine选项设置为true将导致小部件反对经典引擎。 （有关配置经典引擎中运行的小部件的更多详细信息，请参见此文档）。
注意：此选项以及对经典引擎的支持，将在未来的小部件版本中删除。鼓励所有客户从经典引擎迁移到身份引擎。访问迁移到OIE，以获取有关迁移到身份引擎的更多详细信息。
PKCE代码挑战。温泉应用程序将不需要此选项，因为小部件将管理整个交易。 Web应用程序应生成自己的代码挑战和代码秘密。代码挑战将传递给小部件，并将代码秘密保存为服务器端，以在重定向登录回调上获取令牌。
注意：查看我们的示例应用程序，以获取使用PKCE的完整互动代码流的示例
在重定向登录回调期间，将作为查询参数返回的应用程序提供的值，或发送电子邮件验证回调。如果未设置值，则将创建一个随机值。处理电子邮件验证回调时，查询参数的state值应作为配置选项（以及OTP）传递给小部件。这将确保小部件可以加载和恢复当前交易。
处理电子邮件验证回调时，查询参数中的otp值应作为配置选项（以及状态）传递给小部件。这将确保小部件可以加载和恢复当前交易。
默认为['openid', 'email'] 。指定在返回的id_token或access_token中提供哪些信息。对于OIDC，您必须将openid作为范围之一。有关可用范围的列表，请参见范围和索赔。
相对于OKTA登录表单，显示外部身份提供商的顺序。默认为SECONDARY 。
PRIMARY - 在Okta登录表单上方显示外部IDP按钮SECONDARY - 显示OKTA登录表单下方的外部IDP按钮本地路径或徽标图像显示在登录小部件顶部的徽标图像
// Hosted on the same origin
logo: '/img/logo.png'
// Can also be a full url
logo: 'https://acme.com/img/logo.png' 徽标映像的alt属性文本，徽标文本仅在没有徽标图像时才显示
// Text to describe the logo
logoText: 'logo text' 由登录小部件呈现的消息中显示的品牌或公司名称（例如，“重置您的{ brandName }密码”）。如果未提供brandName ，则会呈现一般消息（例如，“重置您的密码”）。您可以进一步自定义使用语言和文本设置显示的文本。
brandName: 'Spaghetti Inc.' 这些选项可让您自定义登录小部件的外观。
如果您需要更多的自定义，则可以修改SASS源文件并构建小部件。
将品牌颜色设置为主要CTA按钮的背景颜色。颜色必须采用十六进制格式，例如#008000 。
colors: {
brand : '#008000'
}cs捷克da丹麦语de德语el希腊语en英语es西班牙语fi芬兰fr法国hu - 匈牙利人id印尼人it - 意大利语ja日语ko韩文ms马来西亚人nb挪威语nl-NL荷兰语pl抛光pt-BR葡萄牙（巴西）ro - 罗马尼亚人ru俄罗斯人sv瑞典人th泰国tr土耳其语uk - 乌克兰人zh-CN中文（PRC）zh-TW中国（台湾）可以使用Assets.Languages选项添加对其他语言的支持。
设置小部件的语言。如果未指定语言，则小部件将根据用户的浏览器首选项选择一种语言，如果支持该语言或默认为en 。
// You can simply pass the languageCode as a string:
language: 'ja'
// Or, if you need to determine it dynamically, you can pass a
// callback function:
language: ( supportedLanguages , userLanguages ) => {
// supportedLanguages is an array of languageCodes, i.e.:
// ['cs', 'da', ...]
//
// userLanguages is an array of languageCodes that come from the user's
// browser preferences
return supportedLanguages [ 0 ] ;
} 设置小部件的默认乡村代码。如果没有提供defaultCountryCode ，则将默认为US 。它设置了小部件中相应的电话号码的国家调用代码。
覆盖小部件中的文本。属性的完整列表可以在登录。Properties和country.properties文件中找到。
// The i18n object maps language codes to a hash of property keys ->
// property values.
i18n: {
// Overriding English properties
'en' : {
'primaryauth.title' : 'Sign in to Acme' ,
'primaryauth.username.placeholder' : 'Your Acme Username'
} ,
// Overriding Japanese properties
'ja' : {
'primaryauth.title' : 'ACMEにサインイン' ,
'primaryauth.username.placeholder' : 'ACMEのユーザー名'
}
}
// If you want to override any properties in the country.properties file,
// you will need to prefix the name with "country.":
i18n: {
'en' : {
// login.properties keys do not have a special prefix
'primaryAuth.title' : 'Sign in to Acme' ,
// country.properties keys are prefixed with 'country.'
'country.AF' : 'Afghanistan, edited' ,
'country.AL' : 'Albania, edited'
}
}覆盖基本网址该小部件从中摘下其语言文件。小部件仅按默认情况下用英语文本打包，并按需要从OKTA CDN加载其他语言。如果要从自己的服务器中使用语言文件，请更新此设置。
// Loading the assets from a path on the current domain
assets: {
baseUrl : '/path/to/dist'
} ,
// Full urls work as well
assets : {
baseUrl : 'https://acme.com/assets/dist'
}注意：可以从NPM模块中发布的
dist/labels/json文件夹访问JSON文件。
指定在{assets.baseUrl}/labels/json/路径下托管和访问的支持语言列表。此选项取代了支持语言的默认列表。如果请求不支持的语言（明确使用语言选项或自动通过浏览器检测），则将使用默认语言（ en ）。
您可以使用此功能重写资产路径和文件名。如果您将在自己的主机上托管资产文件，并计划更改资产的路径或文件名，请使用此功能。例如，如果您想缓存文件，这很有用。
assets: {
// Note: baseUrl is still needed to set the base path
baseUrl : '/path/to/dist' ,
rewrite : ( assetPath ) => {
// assetPath is relative to baseUrl
// Example assetPath to load login for 'ja': "/labels/json/login_ja.json"
return someCacheBust ( assetPath ) ;
}
}设置以下配置选项以覆盖背面以在链接URL中签名。如果未提供，小部件将导航到主auth。
backToSignInLink: 'https://www.backtosignin.com'注意：要与以前的小部件版本兼容，
signOutLink被接受为backToSignInLink的别名
您可以通过设置以下配置选项将注册链接添加到主验证页面。
单击注册链接时调用的函数。
// An example that adds a registration link underneath the login form on the primary auth page
registration: {
click : ( ) => {
window . location . href = 'https://acme.com/sign-up' ;
}
} 设置以下配置选项以覆盖主验证页面上的帮助链接URL。
// An example that overrides all help links, and sets two custom links
helpLinks: {
help : 'https://acme.com/help' ,
forgotPassword : 'https://acme.com/forgot-password' ,
unlock : 'https://acme.com/unlock-account' ,
custom : [
{
text : 'What is Okta?' ,
href : 'https://acme.com/what-is-okta'
} ,
{
text : 'Acme Portal' ,
href : 'https://acme.com' ,
target : '_blank'
}
]
} 自定义链接HREF用于“帮助”链接
“忘记密码”链接的自定义链接HREF
“解锁帐户”链接的自定义链接HREF。对于此链接以显示显示，必须将features.selfServiceUnlock设置为true ，并且必须在管理设置中启用自我服务解锁功能。
自定义链接对象的数组{text, href, target}将在“帮助”链接后添加。链接的target是可选的。
设置以下配置选项以自定义hCaptcha脚本URI：
// An example that uses cn1 host
hcaptcha : {
scriptSource : 'https://cn1.hcaptcha.com/1/api.js' ,
scriptParams : {
apihost : 'https://cn1.hcaptcha.com' ,
endpoint : 'https://cn1.hcaptcha.com' ,
assethost : 'https://assets-cn1.hcaptcha.com' ,
imghost : 'https://imgs-cn1.hcaptcha.com' ,
reportapi : 'https://reportapi-cn1.hcaptcha.com' ,
}
} , 设置以下配置选项以自定义reCAPTCHA脚本URI：
// An example that uses recaptcha.net
recaptcha : {
scriptSource : 'https://recaptcha.net/recaptcha/api.js'
} ,在呈现特定视图之前或之后，可以调用异步回调。挂钩可用于添加自定义逻辑，例如仪器，记录或其他用户输入。挂钩函数执行时，正常执行被阻止，并在挂钩函数返回的承诺解析后恢复。挂钩可以通过配置，如下所示，或使用前或之后的运行时添加。完整的视图列表可以在ResediationConstants.js中找到。
// Hooks can be set in config
hooks: {
'identify' : {
after : [
async function afterIdentify ( ) {
// custom logic goes here
}
]
} ,
'success-redirect' : {
before : [
async function beforeSuccessRedirect ( ) {
// custom logic goes here
}
]
}
}
// Hooks can also be added at runtime
signIn . before ( 'success-redirect' , async ( ) => {
// custom logic goes here
} ) ;
signIn . after ( 'identify' , async ( ) => {
// custom logic goes here
} ) ;在将用户名与Okta发送请求之前更改用户名。当您在用户输入与OKTA用户名之间进行内部映射时，这很有用。
// The callback function is passed two arguments:
// 1) username: The name entered by the user
// 2) operation: The type of operation the user is trying to perform:
// - PRIMARY_AUTH
// - FORGOT_PASSWORD
// - UNLOCK_ACCOUNT
transformUsername: ( username , operation ) => {
// This example will append the '@acme.com' domain if the user has
// not entered it
return username . includes ( '@acme.com' )
? username
: username + '@acme.com' ;
}可以提供回调功能，该功能将在注册过程中的特定时刻调用。
registration : {
parseSchema : ( schema , onSuccess , onFailure ) => {
// handle parseSchema callback
onSuccess ( schema ) ;
} ,
preSubmit : ( postData , onSuccess , onFailure ) => {
// handle preSubmit callback
onSuccess ( postData ) ;
} ,
postSubmit : ( response , onSuccess , onFailure ) => {
// handle postsubmit callback
onSuccess ( response ) ;
}
} , 回调用于更改Okta API返回的JSON模式。
parseSchema: ( schema , onSuccess ) => {
// This example will add an additional field to the registration form.
schema . push (
{
'name' : 'userProfile.address' ,
'type' : 'text' ,
'placeholder' : 'Enter your street address' ,
'maxLength' : 255 ,
'label-top' : true ,
'label' : 'Street Address' ,
'required' : true ,
}
) ;
onSuccess ( schema ) ;
} 回调主要用于修改发送到Okta API的请求参数。
preSubmit: ( postData , onSuccess ) => {
// This example will append the domain name to the email address if the user forgets to add it during registration.
if ( ! postData . userProfile . email . includes ( '@acme.com' ) ) {
postData . userProfile . email += '@acme.com' ;
}
}
onSuccess ( postData ) ;
} 回调用于主要获得控制并修改提交后的行为后，以注册API。
postSubmit: ( response , onSuccess ) => {
// This example will log the API request body to the browser console before completing registration.
console . log ( response ) ;
onSuccess ( response ) ;
} preSubmit: ( postData , onSuccess , onFailure ) => {
// A generic form level error is shown if no error object is provided
onFailure ( ) ;
} preSubmit: ( postData , onSuccess , onFailure ) => {
const error = {
"errorSummary" : "Custom form level error"
} ;
onFailure ( error ) ;
} preSubmit: ( postData , onSuccess , onFailure ) => {
const error = {
"errorSummary" : "API Error" ,
"errorCauses" : [
{
"errorSummary" : "Custom field level error" ,
"property" : "userProfile.email" ,
}
]
} ;
onFailure ( error ) ;
}您可以通过设置以下配置选项来添加主验证页面上登录表单下方的自定义按钮。如果您想更改分隔符文本，请使用i18n配置选项。
// An example that adds a custom button below the login form on the Sign in form
customButtons: [ {
title : 'Click Me' ,
className : 'btn-customAuth' ,
click : ( ) => {
// clicking on the button navigates to another page
window . location . href = 'https://www.example.com' ;
}
} ]
// An example that adds a custom button with a localized title below the Sign in form
i18n: {
en : {
'customButton.title' : 'Custom Button Title' ,
} ,
} ,
customButtons : [ {
i18nKey : 'customButton.title' ,
className : 'btn-customAuth' ,
click : ( ) => {
// clicking on the button navigates to another page
window . location . href = 'https://www.example.com' ;
}
} ] 将按钮文本设置为字符串（仅设置title或i18nKey之一）
在i18n配置选项中指定的按钮文本的自定义翻译键（仅设置title或i18nKey之一）
可以添加到按钮的可选类
单击按钮时调用的函数
使用以下选项启用或禁用窗口小部件功能。
features: {
showPasswordToggleOnSignInPage : true ,
hideSignOutLinkInMFA : false ,
rememberMe : true
} 默认为true 。显示眼图标以切换用户在OKTA登录页面上输入密码的可见性。默认情况下，即使启用了此标志，密码也会隐藏。密码可见30秒，然后自动隐藏。
默认为true 。用用户上下文显示在任何视图上显示用户的标识符。
默认为false 。掩盖了身份验证者注册和挑战流的“返回签名”链接。
默认为true 。使用先前使用的用户名预填充标识符字段。
默认为true 。显示时，会自动将任何形式的第一个输入字段注意到。
默认为false 。将输入字段上的自动完成属性设置为off 。
小部件在运行时为自定义目的注入安全的内线脚本/样式块，但是这些块可能违反了在托管网页中设置的CSP规则。
cspNonce允许将NONCE值设置为从Content-Security-Policy标头到注入的块，因此这些块的脚本/样式仍然可以执行。
注意： nonce指令已添加到CSP Level2中，如果在不支持的浏览器中使用了浏览器控制台中的CSP错误。
小部件发布的事件。使用ON订阅这些事件。
当小部件准备第一次接受用户输入时，触发。返回包含以下属性的context对象：
signIn . on ( 'ready' , function ( context ) {
// The Widget is ready for user input
} ) ;小部件将处理大多数类型的错误 - 例如，如果用户输入无效的密码或存在问题。要捕获身份验证状态更改错误后，该错误由小部件处理和渲染，请收听afterError事件。您还可以捕获OAuth和注册错误。对于其他错误类型，鼓励使用renderEl错误处理程序对其进行处理。
返回包含以下属性的context和error对象：
context ：error ： signIn . on ( 'afterError' , function ( context , error ) {
console . log ( context . controller ) ;
// reset-password
console . log ( error . name ) ;
// AuthApiError
console . log ( error . message ) ;
// The password does not meet the complexity requirements
// of the current password policy.
console . log ( error . statusCode ) ;
// 403
} ) ;当小部件过渡到新页面并完成动画完成时，触发了。返回包含以下属性的context对象：
// Overriding the "Back to sign in" click action on the Forgot Password page
signIn . on ( 'afterRender' , function ( context ) {
if ( context . controller !== 'forgot-password' ) {
return ;
}
var backLink = document . getElementsByClassName ( 'js-back' ) [ 0 ] ;
backLink . addEventListener ( 'click' , function ( e ) {
e . preventDefault ( ) ;
e . stopPropagation ( ) ;
// Custom link behavior
} ) ;
} ) ; 我们使用纱线作为我们的节点软件包管理器。要安装纱线，请查看其安装文档。
克隆此存储库并导航到新的okta-signin-widget文件夹。
git clone https://github.com/okta/okta-signin-widget.git
cd okta-signin-widget安装我们的节点依赖项。
yarn install使用okta-signin-widget配置创建一个.widgetrc.js文件：
module . exports = {
issuer : 'https://{yourOktaDomain}/oauth2/default' ,
clientId : '{{clientId of your OIDC app}}' ,
redirectUri : '{{redirectUri configured in OIDC app}}' ,
logoText : 'Windico' ,
features : {
rememberMe : true ,
} ,
}构建小部件，启动托管它的本地连接服务器，然后在运行窗口小部件的情况下启动浏览器窗口。
yarn start or start local connect server in watch mode, changes in src/ and assets/sass/ folders will trigger browser auto reload.
yarn start --watchFinally, enable CORS support for our new server by following these instructions. You can now authenticate to Okta using your very own, customizable widget!
| 命令 | 描述 |
|---|---|
yarn start | Build the widget, start the server, and open a browser window with the widget loaded |
yarn start --watch | Build the widget, start the server, and open a browser window with the widget loaded and watch on widget js and sass changes |
yarn build:dev | Build an unminified version of the widget |
yarn build:release | Build a minified, uglified version of the widget ( okta-sign-in.min.js ) and a non-minified development version of the widget ( okta-sign-in.js ). |
yarn test -t jest | Run unit tests using Jest |
yarn test -t jest --suiteHelp | Display optional test suite options |
yarn test -t testcafe <browser> | Run testcafe tests on selected browser (example: yarn test -t testcafe chrome ) |
yarn lint | Run eslint and scss linting tests |
yarn link When developing locally, you may want to test local changes to the widget in another project, which is also local. To use yarn link locally, follow these steps:
In okta-signin-widget directory:
yarn build:release
cd dist
yarn link
yarn build:webpack-dev --output-path ./dist/js --output-filename okta-sign-in.entry.js --watchThis will watch for changes in signin widget source code and automatically rebuild to the dist directory.
In your other local project directory:
yarn link @okta/okta-signin-widget
配x This tool requires access to Okta's internal registry via the VPN.
A pseudo-localized language is a test language created to identify issues with the internationalization process. Generated from login.properties English resources, the pseudo-loc properties file can be used to test UI's for English leaks and CSS layout issues caused due to localization.
To generate pseudo-loc, run the following command:
# Navigate into the pseudo-loc package
[okta-signin-widget]$ cd packages/@okta/pseudo-loc/
# Install all required dependencies and generate login_ok_PL.properties
# NOTE: This requires VPN access
[pseudo-loc]$ yarn install
[pseudo-loc]$ yarn pseudo-loc Finally, update the .widgetrc.js file to use the ok_PL language, and start the widget playground.
module . exports = {
// ...other widget config
// ...
language : 'ok-PL' ,
...
} Need to know if the Sign-In Widget supports your browser requirements? Please see Platforms, Browser, and OS Support.
We're happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.
