# IndyKite Client UI SDK
IndyKite is a cloud identity platform built to secure and manage human & non-person (IoT) identities and their data. This repository containts the JavaScript Library packages for [IndyKite Platform](https://indykite.com/) Client SDK.
This library contains multiple client libraries for each service of the platform.
[](https://www.npmjs.com/package/@indykiteone/indykite-sdk-web)
[](https://codecov.io/gh/indykite/indykite-sdk-web)
In order to access to the platform you must obtain an API key first.
## Terminology
| Definition | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| Digital Twin | A digital twin is the digital identity of a physical entity on/in a software/identity system |
| Application Space ID | ID of the application where the digital twin belongs to |
| Application Agent ID | ID of the agent which makes the application available for the different calls |
| Tenant ID | ID of the tenant where the digital twin belongs to. The tenant is belong to an application space |
| Private Key and Settings | The secret which required to reach the system. Indykite provides the necessary secrets |
| Property | The digital twin's property (eg.: email, name) |
| JWT | JSON Web Tokens |
| Introspect | A process used to validate the token and to retrieve properties assigned to the token |
| Patch property | Add, change or delete a property of a digital twin |
## Documentation
Visit the IndyKite One Developer Community site for official [IndyKite documentation](https://indykite.one/blog?category=5e3e9297-3451-4b52-91ee-8027dcd1789c) and to find out how to use the entire platform for your project.
## Prerequisites
You need to have the following before using the Web SDK:
- An AppSpace, App, AppAgent, and AppAgent credentials
- A deployed authentication flow
## Installation
##### From [npm](https://www.npmjs.com/package/@indykiteone/indykite-sdk-web):
```
npm install @indykiteone/indykite-sdk-web
```
From [yarn](https://yarnpkg.com/):
```
yarn add @indykiteone/indykite-sdk-web
```
### Import version
You can use the Web SDK by importing the SDK as a package to your JavaScript framework. With this option, the source files are in a readable (unbuilt) form. Since this form is not prebuilt, it is necessary to build your application using tools such as webpack or babel.
`import { IKUIInit } from "@indykiteone/indykite-sdk-web";`
**Note**: If you are building apps with frameworks like React, Angular or Vue.js. You have most likely already setup
a build process (often automatically by the framework), and therefore do not need to do anything.
#### From CDN:
UNPKG
```javascript
```
jsDelivr
```javascript
```
### Browser support
**CDN .dist.js version** is built with support for all recent versions of major browsers (Chrome, Firefox, Safari, Edge, Opera).
## API
#### dist.js package
In case of using the dist package. All functions are exported under the `IK` keyword.
For example:
```html
You should use the `disableInlineStyles` property set to `true`, because inline styles are deprecated now. See the [CSS](#css) section in order to get more information.
### Core - UI API
To use the UI elements provided by the @indykiteone/indykite-sdk-web library, make sure you've completed initializing the library as described above.
As all render functions do network setup calls, they should be treated as side effects in the JS framework of your application.
## Rendering login/registration screen with different auth flows
### Simple registration
This authentication flow doesn't allow you to do anything special but registering a new user using username and password.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
});
}, []);
return (
);
};
```
### Simple login with no actions
This authetication flow lets you log in with a username and password.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now.
},
onFail: (error) => {
console.error(error);
},
});
}, []);
return (
);
};
```
### Simple login with some actions
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
actionLabels: {
KEY_FORGOTTEN: "Forgotten password?",
KEY_REGISTER: "Registration",
},
});
}, []);
return (
);
};
```
### Login flow with OIDC providers
#### When the flow doesn't continue after returning from the OIDC provider
You need to put the following code to your login page, e.g. `https://yourpage.com/login`:
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You will not get the access token here, because you will be redirected
// to an OIDC provider page (e.g. google.com) and then to your callback page
},
onFail: (error) => {
console.error(error);
},
});
}, []);
return (
);
};
```
This code will display a Google option to log in. After clicking the option, you will be redirected to the Google site where you will be authenticated. After that, you will be redirected back to your callback URL. Put the following code to your call back page, which can be, for example, `https://yourpage.com/callback`:
```ts
import React from "react";
import { IKUIOidc } from "@indykiteone/indykite-sdk-web";
// This is where Google and other providers can redirect you
const Callback = () => {
React.useEffect(() => {
// It's important that oidcCallback is called just once, multiple calls can end up with errors
IKUIOidc.oidcCallback()
.then((data) => {
// You can save the token in your app in case you need it but UISDK can handle all this for you
// so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
console.log(data);
})
.catch((e) => {
// The App developer is responsible for handling the error in this phase.
console.error(e);
});
}, []);
return (
general callback
);
};
```
#### When the flow continues after returning from the OIDC provider
You need to put this code in your login page, for example, `https://yourpage.com/login`:
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// After you finish your authentication with an OIDC provider you should be redirected
// back to this login page.
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
actionLabels: {
KEY_FINISH: "Finish",
},
});
}, []);
return (
);
};
```
And this code to your callback page you set as the Redirect URL in your OIDC provider, for example, `https://yourpage.com/callback`:
```ts
import React from "react";
import { IKUIOidc } from "@indykiteone/indykite-sdk-web";
// This is where FB, Google and other providers can redirect you
const Callback = () => {
React.useEffect(() => {
// It's important that oidcCallback is called just once, multiple calls can end up with errors
IKUIOidc.oidcCallback()
.then((data) => {
// In this case the data should contain a `redirect_to` property and you should redirect to this location.
if (data.redirect_to) {
window.location.href = data.redirect_to;
}
})
.catch((e) => {
// The App developer is responsible for handling the error in this phase.
console.error(e);
});
}, []);
return (
general callback
);
};
```
### Multiple login flows (using the Switch node)
Use the switch node to merge mutliple authentication flows into one. If you want to use the `Default` branch, you don't need to specify any new properties. This code will use the `Default` branch.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
actionLabels: {
KEY_REGISTER: "Registration",
},
});
}, []);
return (
);
};
```
The `register` branch will be used if the condition specified inside the Switch node is fulfilled. By default there's a following condition:
```
has(session.input) && has(session.input.flow) && session.input.flow=='register'
```
It checks whether the input object has a property `flow` set to `register`. You can define the input object with passing the `arguments` property to your `IKUICore.renderForm` call:
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
actionLabels: {
KEY_REGISTER: "Registration",
},
arguments: {
flow: "register",
},
});
}, []);
return (
);
};
```
### Forgotten password flow
#### Use an action (click the Did you forget your password? button)
In the beginning, you can call `IKUICore.renderForm` as usual. The login screen will contain an action "Forgotten password?".
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You will not end here in case a user wants to reset its password.
},
onFail: (error) => {
console.error(error);
},
actionLabels: {
KEY_FORGOTTEN: "Forgotten password?",
KEY_REGISTER: "Registration",
},
});
}, []);
return (
);
};
```
When a user sends a request to reset their password, they will get an email containing a reference ID in the link confirming the password resent. You need to extract this ID from the URL and pass it to the `IKUICore.renderForm` function as an `token` property.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKResetPasswordForm = ({ referenceId }) => {
React.useEffect(() => {
if (referenceId) {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
token: referenceId,
});
}
}, [referenceId]);
return (
);
};
```
#### Use a special URL
If you want to start your flow with the reset password screen, use the Switch node, as mentioned in the [Multiple login flows](#multiple-login-flows-using-the-switch-node) section. If you add the `flow` argument with a value specified by you (in the authentication flow builder) to your `IKUICore.renderForm` call, the Switch node will use the direct connection with the Forgotten Password node.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You will not end here in case a user wants to reset its password.
},
onFail: (error) => {
console.error(error);
},
actionLabels: {
KEY_FORGOTTEN: "Forgotten password?",
KEY_REGISTER: "Registration",
},
arguments: {
flow: "reset-password",
},
});
}, []);
return (
);
};
```
When a user sends a request to reset his password, he will get an email containing a reference ID in the link confirming the password resetting. You need to extract this ID from the URL and pass it to the `IKUICore.renderForm` function as an `token` property.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKResetPasswordForm = ({ referenceId }) => {
React.useEffect(() => {
if (referenceId) {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
token: referenceId,
});
}
}, [referenceId]);
return (
);
};
```
### Log in with tokens
#### OTP Token
A user can get an invitation email which contains a reference ID. You need to pass this ID the same way as you did in the [Reset password](#using-an-action-clicking-on-did-you-forgot-you-password-button) flow, and that's to use this ID as the `token` property. This will cause your authentication to start with the Input Invitation node.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKResetPasswordForm = ({ referenceId }) => {
React.useEffect(() => {
if (referenceId) {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
token: referenceId,
});
}
}, [referenceId]);
return (
);
};
```
#### Magic link
An authentication flow can also use a Magic Link. In this case a user is asked to enter a code they got in an email. The received email may contain a reference ID - very likely used in a clickable URL address. After this address is opened you need to ensure that the authentication flow is started with the `~token` property in the same way how it was used in the previous example.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKMagicLinkForm = ({ referenceId }) => {
React.useEffect(() => {
if (referenceId) {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
// You can store the access token from the data object, but the UISDK can handle
// all this for you so theoretically you don't need to manage tokens yourself.
// The authentication flow ended here and you can do a redirection to your application now
},
onFail: (error) => {
console.error(error);
},
token: referenceId,
});
}
}, [referenceId]);
return (
);
};
```
> Please note that in order to make this working you need to setup your email configuration.
> For more details see [this tutorial](https://docs.indykite.com/docs/developer-documentation/authentication/set-up-magic-link-flow.md#set-up-email).
## Custom OIDC provider
In case you want to act as an OIDC provider, you have to call the `IKUIOidc.handleOidcOriginalParamsAndRedirect` function before you start your auth flow.
```ts
import { IKUIOidc } from "@indykiteone/indykite-sdk-web";
const pathToLogin = "/login";
IKUIOidc.handleOidcOriginalParamsAndRedirect(pathToLogin);
```
This helps the SDK know that you are an OIDC provider, and after you authenticated, the SDK should return you back to the original application. The `pathToLogin` should point to an endpoint where you will call the `IKUICore.renderForm` as usual.
## Authentication status
After you have successfully finished the authentication flow, you don't have to store the access tokens on your own. The SDK does it for you. You can use the following functions to manage the authentication status.
- **`IKUIUserAPI.isAuthenticated()`**
- Check whether there's an authenticated user
- **`IKUIUserAPI.getValidAccessToken()`**
- Get the access token of currently logged user
- **`IKUIUserAPI.refreshAccessToken()`**
- Refresh the access token of currently logged user
- **`IKUIUserAPI.logoutUser()`**
- Logout currently logged user
## Customize components
### Replace a form component
#### Input
This example shows how to add a custom class name to the input element.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
},
onFail: (error) => {
console.error(error);
},
onRenderComponent: (component: HTMLElement, componentType: string) => {
if (componentType === "form") {
const inputs = component.getElementsByTagName("input");
// Should be always only one, but this is a general solution
if (inputs.length > 0) {
Array.from(inputs).forEach((input) => input.classList.add("my-input-class"));
}
return component;
}
return component;
},
});
}, []);
return (
);
};
```
#### Submit button
This example shows how to replace an original submit button element with a totally new one.
```ts
import ReactDOM from "react-dom";
import { IKUICore } from "@indykiteone/indykite-sdk-web";
const IKForm = () => {
React.useEffect(() => {
IKUICore.renderForm({
renderElementSelector: "#form-container",
onSuccess: (data) => {
console.log(data);
},
onFail: (error) => {
console.error(error);
},
onRenderComponent: (
component: HTMLElement,
componentType: string,
componentSubtype: string,
...rest: unknown[]
) => {
if (componentType === "form" && componentSubtype === "submit") {
const [clickHandler] = rest as [Function];
const newButton = document.createElement("button");
newButton.innerText = "Custom submit";
newButton.addEventListener("click", clickHandler as any);
return newButton;
}
return component;
},
});
}, []);
return (
);
};
```
### Replace an action button
Here you can see how to replace the default `` link with a custom `
