With previous versions of the Okta Widget, the approach used to make customizations that are outside of the built-in options was to use afterRender().
The preferred approach with the third-generation Okta Widget is to use the new afterTransform() hook.
- Okta Identity Engine (OIE)
- Okta-hosted Widget (third generation)
- Widget Customizations
Since the third-generation Widget is built on Preact, relying on the before/after render hooks to manipulate the DOM after page render will no longer work as expected.
The third-generation Widget introduces a new afterTransform() hook.
The hook takes two arguments - the name of the form to make customizations to and a function that receives a context argument to apply the changes on.
signIn.afterTransform('form_name', function (context) { }NOTE: Supplying wildcard (*) for the form_name will match all forms. A wildcard cannot be used for partial name matches, only * on its own.
Assigning multiple afterTransform functions to a single widget instance is valid.
The context has a formBag attribute which contains the components sent to the view to be rendered. Modifying this allows customization of the Widget appearance.
Examples:
Remove the "Sign in with PIV / CAC card" button from the Identify screen if present.
oktaSignIn.afterTransform('identify', function (context) {
context.formBag.uischema.elements = context.formBag.uischema.elements.filter((e) => e.label !== "Sign in with PIV / CAC card");
});
During Authenticator Selection, change the description/value for the Phone Authenticator.
oktaSignIn.afterTransform('select-authenticator-authenticate', function (context) {
const AuthList = context.formBag.uischema.elements.find((e) => e.type === "AuthenticatorButtonList");
if (AuthList === undefined) {
return;
}
const PhoneAuth = AuthList.options.buttons.find((e) => e.label === "Phone");
if (PhoneAuth === undefined) {
return;
}
PhoneAuth.translations[0].value = 'Test Translations';
PhoneAuth.options.description = '+1 123-456-7890';
});
Add a custom link to the bottom of every page the Widget renders.
signIn.afterTransform('*', function (context) {
var customLink = {
type: 'Link',
contentType: 'footer',
options: {
href: 'https://www.okta.com/terms-of-service/',
target: '_blank',
step: '',
label: 'Terms of Service',
dataSe: 'customLink',
},
};
context.formBag.uischema.elements.push(customLink);
});
Tip:
To discover the different formNames and how components are sent in context.formBag.uischema, the easiest approach would be to set up an afterTransform hook with the below.
oktaSignIn.afterTransform('*', function (context) {
console.log(context.formName);
console.log(context.formBag.uischema);
});When going through an authentication flow, observe the browser's dev console window or set up break points.
