@kong/kong-auth-elements

Vue 3 Plugin and Native HTML Web Components used for KAuth UI implementation in Kong apps


- @kong/kong-auth-elements
- Installation
- npm
- CDN
- CDN Example
- Usage
- Vue 3 Plugin
- Vue 2 or no framework via native web components
- Teleport Wrapper
- Options
- TypeScript
- Custom Error Handler
- Inject CSS
- Events
- Theming with CSS Variables
- Webpack
- Testing in your app
- Cypress
- Custom Elements
- kong-auth-login
- Props
- Emits Events
- Query String Parameters
- IdP Login
- Auto-initialization
- userEntity = 'user'
- userEntity = 'developer'
- Logging back in
- kong-auth-forgot-password
- Props
- Emits Events
- kong-auth-reset-password
- Props
- Emits Events
- Query String Parameters
- kong-auth-change-password
- Props
- Emits Events
- kong-auth-register
- Props
- Query String Parameters
- Emits Events
- kong-auth-accept-invitation
- Props
- Emits Events
- Query String Parameters
- Contributing
- Creating a New Custom Element
- Requirements
- Custom Element Styles and the shadow DOM
- Committing Changes
- Enforcing Commit Format
- Local Development
- Configure Environment Variables
- Install dependencies
- Components Sandbox
- Compile Components and hot-reload for development
- Build Components Sandbox and preview
- Elements Sandbox
- Compile Custom Elements and hot-reload for development
- Build Elements Sandbox and preview
- Web Components Sandbox
- Build Web Components Sandbox and preview
- Compile and minify for production
- Link the local @kong/kong-auth-elements package into another local project for testing
- Current Issues
- Props
- Axios

Installation

$3

Install the package as a dependency in your app

``sh
yarn add @kong/kong-auth-elements
`

$3

The default exports have a bundle filename of *.vue.{umd|es}.js where we internalize Vue for consumption by the plugin (i.e. the bundle includes the Vue core).

We also provide kong-auth-elements.{umd|es}.js bundles that do NOT internalize (bundle) the Vue core along with it. These bundles can can be imported via

`

Usage

$3

Import the package (and TypeScript types, if desired) inside of your App's entry file (e.g. for Vue, main.ts). Set the plugin options, and tell Vue to use the plugin.

`js
// main.ts

import App from './App.vue'
import { KongAuthElementsPlugin } from '@kong/kong-auth-elements/dist/kong-auth-elements.es'
import type { KongAuthElementsOptions } from '@kong/kong-auth-elements/dist/types'
import '@kong/kong-auth-elements/dist/style.css'

const app = createApp(App)

const pluginOptions: KongAuthElementsOptions = {
// Unless using an absolute URL, this base path MUST start with a leading slash (if setting the default) in order to properly resolve within container applications, especially when called from nested routes(e.g. /organizations/users)
apiBaseUrl: 'https://global.api.konghq.com/kauth',
userEntity: 'user',
shadowDom: false, // We are using the Vue plugin, so the shadow DOM isn't needed
}

// Register the plugin
app.use(KongAuthElementsPlugin, pluginOptions)

app.mount('#app')
`

Now that the plugin is globally registered, simply include a component just like you would any other Vue component, utilizing any props as needed

`html
show-forgot-password-link
@login-success="onLoginSuccess"
@click-forgot-password-link="onUserClickForgotPassword"
@click-register-link="onUserClickRegister">
`

---

$3

Import the package (and TypeScript types, if desired) inside of your App's entry file (e.g. for Vue, main.ts), set up the options, and call the provided registerKongAuthNativeElements function.

`ts
// main.ts

import registerKongAuthNativeElements from '@kong/kong-auth-elements'
import type { KongAuthElementsOptions } from '@kong/kong-auth-elements'
import '@kong/kong-auth-elements/dist/style.css'

const options: KongAuthElementsOptions = {
// Unless using an absolute URL, this base path MUST start with a leading slash (if setting the default) in order to properly resolve within container applications, especially when called from nested routes(e.g. /organizations/users)
apiBaseUrl: 'https://us.api.konghq.com/kauth',
userEntity: 'user',
shadowDom: true,
injectCss: ['.kong-auth-login-form .k-input#email { background-color: #ff0000 }'],
lang: 'en', // Exclude to default to English
}

// Call the registration function to automatically register all custom elements for usage
registerKongAuthNativeElements(options)
`

The function will register all custom elements for usage as native web components.

Wherever you want to utilze a custom element, you must wrap it with an element (e.g. a div) with a unique id attribute, and then simply include the element in your HTML just like you would any other element, utilizing any props as needed

`html


For the current implementation, it is REQUIRED to wrap the element with a tag with a unique id attribute so the custom element can be "teleported" out of the shadow DOM to enable password manager support.

The id attribute should then be passed to each Custom Element in the wrapperId prop so the element can be properly teleported out of the shadow DOM. For more information refer to the Vue Teleport docs. There are default wrapperId prop values provided; however to utilize them you still must wrap the custom element in an element with the corresponding id.

---

$3

Regardless if you're using in Vue 3, Vue 2, or the native web components, an identical set of options exist for configuring the kong-auth-elements.

| Option | Type | Default | Description |
| :------------------- | :---------------- | :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apiBaseUrl | string | /kauth | The basePath of the internal axios instance.

Unless using an absolute URL, this base path must start with a leading slash (if setting the default) in order to properly resolve within container applications, especially when called from nested routes(e.g. /organizations/users) |
| userEntity | string | user | The user entity for authentication; one of user or developer. |
| developerConfig | DeveloperConfig | { portalId: string } | The developer config object. |
| customErrorHandler | Function | (event: CustomEndpointErrorEvent) => '' | Supply a custom error handler to use when utilizing an element that allows providing a custom request endpoint. See the example below |
| injectCss | string[] | [] | Pass an array of inlined CSS strings that will be injected into the DOM. See the example below |
| lang | string | en | Set the language to use for the component message strings. See /src/locales/ |

#### TypeScript

You can import the TypeScript interfaces from the package if desired.

`ts
// List of user entities
export type UserEntities = 'user' | 'developer'

// List of custom elements that accept a custom error handler
export type CustomEndpointElement = 'kong-auth-login' | 'kong-auth-forgot-password' | 'kong-auth-register' | 'kong-auth-reset-password' | 'kong-auth-change-password'

// List of requests that support custom endpoints
export type CustomEndpointRequest = 'authenticate-request' | 'verify-email-request' | 'reset-password-request' | 'change-password-request' | 'register-request' | 'set-new-password-request'

export interface CustomEndpointErrorEvent = {
error: AxiosError
request: CustomEndpointRequest
element: CustomEndpointElement
}

// Developer config options
export interface DeveloperConfig {
portalId: string
}

// Supported languages
export type SupportedLanguages = 'en'

export interface KongAuthElementsOptions {
apiBaseUrl?: string
userEntity?: UserEntities
developerConfig?: DeveloperConfig
customErrorHandler?: (event: CustomEndpointErrorEvent) => string
shadowDom?: boolean
injectCss?: string[]
lang?: SupportedLanguages
}
`

#### Custom Error Handler

You can customize the logic in your error handler to only respond to the requests or elements you wish to target.

If an error message string is not returned from the customErrorHandler based on the error/request/element logic then the default error handler and messaging will be used.

`ts
const pluginOptions: KongAuthElementsOptions = {
apiBaseUrl: 'https://us.api.konghq.com/kauth',
userEntity: 'developer',
customErrorHandler: ({ error, request, element }): string => {
// Access the original error
console.log('error', error)

// ... or the element name that the event was triggered by
console.log('element', element)

// Or perform different logic based on the request that errored
if (request === 'reset-password-request') {
return 'Custom reset error message.'
} else if (request === 'register-request') {
return 'Custom registration error message.'
}
},
}
`


#### Inject CSS

`ts
// Pass in inlined CSS strings as needed

const pluginOptions: KongAuthElementsOptions = {
apiBaseUrl: 'https://us.api.konghq.com/kauth',
userEntity: 'user',
injectCss: [
'.kong-auth-login-form .k-input#email { background-color: #ff0000 }',

.kong-auth-register-form .k-input {
width: 50%;
}
,
],
}
`

$3

Events are emitted for different component/element actions.

If using the Vue Plugin, you can listen to these events just like you would any other emitted event. (e.g. @login-success="successHandler") The payload of events follows the Record type in most cases.

`ts
const successHandler = (eventData: Record) => {
console.log(eventData.email) // => 'marty.mcfly@thepinheads.com'
}
`

If your app uses the native web components, the emitted events follow the CustomEvent() Web API spec.

An example of consuming the native web component events and CustomEvent.details (emitted data) in your Vue app can be seen here

`html
instruction-text="Enter your verified email address and we will send you a password reset link."
@forgot-password-success="onForgotPasswordSuccess"
>


`

If your app does not utilize Vue, you can respond to the custom events just like any other event listener

`js
// Add an appropriate event listener
document.querySelector('kong-auth-login').addEventListener('login-success', function (successEvent) {
const eventData = Array.isArray(successEvent.detail) ? successEvent.detail[0] : successEvent.detail

console.log('The user has successfully authenticated!')
})
`

$3

You may utilize any CSS variables included in the Kongponents component library.

In order to override the built-in CSS variables, you will need to scope your custom values to the .kong-auth-element selector as shown here

`css
.kong-auth-element {
--kui-color-text-primary: green;
}
`

$3

If utilizing the native web components inside of a Vue app with the register function (which forces use of the native web components), you will need to inform your consuming app (e.g. Vue) to recognize the custom elements defined outside of the framework (e.g. using the Web Components APIs).

If a component matches this condition, it won't need local or global registration and Vue won't throw a warning about an Unknown custom element.

Regardless of whether your consuming application is a Vue app, you will also need to add an entry to transpileDependencies.

If your consuming application is a Vue app, add the following code in vue.config.js

`js
// vue.config.js

module.exports = {
chainWebpack: (config) => {
config.module
.rule('vue')
.use('vue-loader')
.tap((options) => {
return {
...options,
compilerOptions: {
isCustomElement: (tag) => tag.startsWith('kong-auth'), // Tags with this prefix will be recognized as custom elements
},
}
})
},
transpileDependencies: ['@kong/kong-auth-elements'],
}
`

If your consuming app does not utilize vue.config.js file, you can transpile dependencies in your project's webpack config. As an example, if using babel-loader, you can include something like this in your webpack.config.js file

`js
// webpack.config.js

module.exports = {
module: {
loaders: [
{
test: /\.js$/,
include: /(node_modules)\/(@kong/kong-auth-elements)/,
loader: 'babel-loader'
}
]
}
}
`

$3

The custom elements have data attributes in place with a standard format of data-testid="kong-auth-{identifier}". If these test selectors are not sufficient, you should be able to create your tests by targeting a parent element and then searching downward through its child elements as needed.

If you have a specific use-case, submit a PR for a new attribute to be added and please add an example use-case as to why the existing attributes are not sufficient.

#### Cypress

If your app utilizes Cypress for testing, you will need to add an entry to your cypress.json configuration file to allow it to traverse the shadow DOM.

`json
{
"includeShadowDom": true
}
`

Alternatively, you can provide an options object to the .get() method with a includeShadowDom property set to true; however, you would have to replicate in every .get() reference, so it's easier to add to your cypress.json config file, if possible. Cypress also has a .shadow() command, but again, the config setting is the easier way to go.

Custom Elements

$3

- Provides a login UI along with corresponding kauth authentication (for user and developer entities)
- Provides Identity Provider (IdP) login, if enabled.
- Provides email verification, given a valid token in the query string.
- Sets the kauth cookies, along with the userStatus cookie (possibly unused).
- Consumes the options.developerConfig.portalId for developer entity authentication.

The login element must reside at the {window.location.origin}/login path in your application.

#### Props

| Prop | Type | Default | Description |
| :----------------------- | :------ | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| wrapperId | String | kong-auth-login-wrapper | Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
| instructionText | String | '' | Set the instruction text to display above the inputs. |
| showForgotPasswordLink | Boolean | false | Show a forgot password link under the password field. |
| forgotPasswordLinkText | String | Forgot your password? | Set the text for the forgot password link. |
| showRegisterLink | Boolean | false | Show a register link under the login button. |
| registerLinkHelpText | String | Don't have an account? | Set the register link help text. |
| registerLinkText | String | Sign Up | Set the text for the register link. |
| registerSuccessText | String | Successfully registered! | Set the text for the register success message. |
| basicAuthLoginEnabled | Boolean | false | Enable basic auth login. To set to false, simply do not add the prop |
| showBasicAuthLoginLink | Boolean | true | Show a link to log in with basic auth credentials on the IdP login form. |
| idpLoginEnabled | Boolean | false | Enable IdP login detection. |
| idpLoginCallbackUrl | URL | '' | Set the URL to return to in order to complete the OIDC flow. In most cases, this should be set to ${window.location.origin}/login |
| idpLoginReturnTo | URL | '' | Set the URL to return to upon successful IdP login. In most cases, this should be set to window.location.origin |
| idpFullScreenLoader | Boolean | true | Show the full screen loading skeleton when IdP login is processing |
| loginSsoButtonText | String | Continue with SSO | Set the text for the SSO login button. |
| loginButtonText | String | Log in | Set the text for the basic authentication login button. |

> Note: When utilizing the props as a native web component, you may need to use dot syntax, as shown here
>
> `html
>
>
>
>
>
> `


#### Emits Events

| Event | Payload | Description |
| :--------------------------- | :----------------------: | :---------------------------------------------- |
| login-success | | User successfully logged in. |
| verify-email-success | { email: String } | User successfully verified their email address. |
| click-forgot-password-link | | User clicked the included forgot password link. |
| click-register-link | | User clicked the included register link. |
| idp-is-loading | { isLoading: Boolean } | IdP authentication is processing. |

To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.

#### Query String Parameters

| Param | Required | Description |
| :-------------- | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token | true if email verification | Pass a valid token entry in the URL query string to verify the user's email address. |
| passwordReset | true if password reset | To show the Reset Password Confirmation, the consuming app URL must include passwordReset=true in the query string. You can choose to include the email parameter as well. |
| registered | true if register success (from register or invite) | To show the Register Confirmation, the consuming app URL must include registered=true in the query string. You can choose to include the email parameter as well. |
| email | false | Pass the user's URL encoded email address (e.g. email=user%40foo.com via encodeURIComponent()) in the query string to prepopulate the login form's email input. |
| basicAuth | false | To force displaying basic authentication (e.g. for organization owners) the URL should include basicAuth=true in the query string. |

#### IdP Login

##### Auto-initialization

###### userEntity = 'user'

When a user lands on your app on the route /login/{login-path} the element will automatically initialize IdP login if the idpLoginEnabled prop is set to true, and the idpLoginReturnTo prop contains a valid URL to redirect the user to after successful authentication.

###### userEntity = 'developer'

When a developer lands on your app on the route /login/sso the element will automatically initialize IdP login if the idpLoginEnabled prop is set to true, and the idpLoginReturnTo prop contains a valid URL to redirect the user to after successful authentication.

##### Logging back in

Upon logging out, if the user is sent to /login/{login-path}?logout=true (notice the logout query param) this will prevent IdP auto-initialization, and will hide the email and password fields and instead will show a Login button along with a separate link to login with credentials. This allows your app to log out the user, send them back to their organization's login path without actually logging them back in (preventing a loop).

If the user clicks the Login button, they will be sent to /login/{login-path} which will start auto-initialization.

If the user clicks the link to login with credentials, they will be sent to /login, and will be able to authenticate with an email and password (if they are an Organization Owner, or their organization allows credentialed login).

---

$3

- Provides a forgot password UI along with corresponding kauth functionality to allow the user to request a reset password email.

#### Props

| Prop | Type | Default | Description |
| :----------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| wrapperId | String | kong-auth-forgot-password-wrapper | Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
| showLoginLink | Boolean | false | Show a login link under the password fields. |
| loginLinkText | String | Return to log in | Set the text for the login link. |
| instructionText | String | '' | Set the instruction text to display above the inputs. |
| successText | String | Check your email for a link to reset your password. If it doesn’t appear within a few minutes, check your spam folder. | Set the text to display upon successful reset password request. |
| resetPasswordRequestEndpoint | String | '' | Set the URL (relative or absolute) endpoint for the password reset request. |

#### Emits Events

| Event | Payload | Description |
| :------------------------ | :-----------------: | :-------------------------------------------------- |
| wrapperId | String | kong-auth-reset-password-wrapper | Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
| forgot-password-success | { email: String } | User successfully requested a reset password email. |
| click-login-link | | User clicked the included login link. |

To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.

---

$3

- Provides a reset password UI along with corresponding kauth functionality to allow the user to reset their password when coming from the reset password email, provided a valid token is present in the query string.

#### Props

| Prop | Type | Default | Description |
| :---------------- | :----- | :------ | :--------------------------------------------------- |
| instructionText | String | '' | Set the instruction text to display above the input. |

#### Emits Events

| Event | Payload | Description |
| :----------------------- | :-----------------: | :-------------------------------------- |
| reset-password-success | { email: String } | User successfully reset their password. |

To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.

#### Query String Parameters

| Param | Required | Description |
| :------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| token | true | Pass a valid token entry in the URL query string to send to the reset password request. |
| email | false | Pass the user's URL encoded email address (e.g. email=user%40foo.com via encodeURIComponent()) in the query string to prepopulate the login form's email input on redirect. |

---

$3

- Provides a change password UI along with corresponding kauth functionality to allow the user to change their password when coming from the MyAccount UI.
Note: This component is only functional when userEntity === 'user'.

#### Props

| Prop | Type | Default | Description |
| :------------------------- | :----- | :---------------- | :--------------------------------------------------- |
| instructionText | String | '' | Set the instruction text to display above the input. |
| changePasswordButtonText | String | Change Password | Set the text for the change password button. |

#### Emits Events

| Event | Payload | Description |
| :------------------------ | :---------------------------------------------------------------------------: | :------------------------------------------------------- |
| change-password-success | | User successfully changed their password. |
| password-requirements | {uppercase: boolean, lowercase: boolean, number: boolean, special: boolean} | Password requirements met after user inputs new password |

To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.

---

$3

- Provides a registration UI along with corresponding kauth functionality to allow the user to register and sending the confirmation email.
- Checks the client config to determine if registration access codes are required.

#### Props

| Prop | Type | Default | Description |
| :------------------------ | :------ | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| wrapperId | String | kong-auth-register-wrapper | Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
| accessCodeRequired | Boolean | false | An access code is required for registration. |
| instructionText | String | '' | Set the instruction text to display above the form inputs. |
| registerButtonText | String | Sign up for Free | Set the text for the register button. |
| registerRequestEndpoint | String | '' | Set the URL (relative or absolute) endpoint for the registration request. |
| recaptcha | Boolean | false | Should reCAPTCHA be enabled for the register form. This feature is currently only available if the userEntity is set to user. |

#### Query String Parameters

| Param | Required | Description |
| :------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------- |
| selectRegion | false | Pass "selectRegion=true" in the URL to show the Konnect region selection during registration for userEntity === 'user'. |

#### Emits Events

| Event | Payload | Description |
| :----------------- | :-----------------------------------------------------------------: | :---------------------------- |
| register-success | { email: String, { organization: { id: String, name: String } } } | User successfully registered. |

To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.

$3

- Provides a UI to allow accepting an invitation. The user should arrive via an invite link with the required query string parameters (outlined below) in the URL. The form will be pre-populated with data and the user will just provide a new password.

#### Props

| Prop | Type | Default | Description |
| :-------------- | :----- | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| wrapperId | String | kong-auth-accept-invitation-wrapper | Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
| subheaderText | String | You've been invited to join | Set the subheader text that appears before the organization name above the form. |

#### Emits Events

| Event | Payload | Description |
| :-------------------------- | :-----------------: | :----------------------------------------- |
| accept-invitation-success | { email: String } | User successfully accepted the invitation. |

To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.

#### Query String Parameters

| Param | Required | Description |
| :--------- | :------- | :---------------------------------------------------------------------------------------------------------------------- |
| token | true | Pass an invite token in the query string. |
| email | true | Pass the user's URL encoded email address (e.g. email=user%40foo.com via encodeURIComponent()) in the query string. |
| fullName | true | Pass the user's URL encoded full name in the query string. |
| org | true | Pass the user's URL encoded organization in the query string. |

Contributing

$3

#### Requirements

1. Custom elements must follow the naming convention {PascalCaseName}.ce.vue
2. The only root-level tag within the