🌐 Web component
This guide shows how to integrate the Corbado web component into your website.
The following page shows how to set up the pre-built Corbado web component. Using the web component saves you a lot of engineering time, comes with many of out-of-the-box features and can be easily integrated with existing authentication solutions.
Before you start integrating, please follow Getting started to setup your project at the developer panel.
If you want to integrate your existing user base and want to test locally, please have a look at the Corbado CLI.
You can install the Corbado web component via npm or add the JavaScript library via CDN.
Via NPM
Via CDN
npm install @corbado/webcomponent
Next, include the package in the module where you plan to utilize the web component, and import the styling file accordingly:
import '@corbado/webcomponent/pkg/auth_cui.css'
import '@corbado/webcomponent'
To add the Corbado JavaScript library to your website, simply insert the following code on the same page where you want to add the web component.
Must be put in
<body>part, not in<head>!<script src="https://<Project ID>.frontendapi.corbado.io/auth.js"></script>
Embed the Corbado web component by adding the
<corbado-auth/> to your login page:<!-- Your website content -->
<corbado-auth project-id="<Project ID>" conditional="yes">
<input name="username" id="corbado-username"
required autocomplete="webauthn"/>
</corbado-auth>
<!-- Your website content -->
The following attributes for
<corbado-auth/> exist:Attribute | Explanation | Default value |
|---|---|---|
project-id | This should be the project ID of your project. | - |
company-image-url | You can provide a URL for the company logo which will be displayed in the top of the web component. For best performance the logo should have a maximum height of 80px. | - |
conditional | If you want to use Conditional UI, you need to set this attribute to "yes" and add the inner <input/> element. | no |
page | You can decide if "login" or "register" page should be displayed at first, when somebody sees the web component. | login |
register-title | Change the title of the sign-up screen of the web component. | null |
register-btn | Change the button text of the sign-up button of the web component. | null |
login-title | Change the title of the login screen of the web component. | null |
login-btn | Change the button text of the login button of the web component. | null |
sub-title | Change the sub tile of the login screen of the web component (it can also be empty). | Welcome back! Please enter your details |
endpoint | https://<project ID>.frontendapi.corbado.io | |
username | Pre-fill the username (email address) input field with a value of your choice. If there is no username HTML attribute set or it is empty, LocalStorage is searched for a key username that is then taken instead. If that doesn't exist, the pre-fill will be empty. | - |
user-full-name | Pre-fill the userFullName input field with a value of your choice. | - |
passkey-append-text | Change the text of the passkey-append-screen | Login event faster with Touch ID, Face ID or PIN |
The inner
<input/> element is needed to make Conditional UI available as some browsers currently do not support Conditional UI in web components.If you want to use Conditional UI (what we recommend for the best UX), just copy and paste the inner
<input/> element's attributes like shown above. If not, you don't need to insert the inner <input/> element at all.Remember that the
<corbado-auth/> web component varies in height depending on the number of textfields / buttons that are currently visible.To adapt Corbado web component to your UI, you can modify the following style properties. Do so by adding CSS for the
<corbado-auth/> web component:<style>
corbado-auth {
--primary-color: #1953ff;
--primary-color-rgb: 25, 83, 255;
--primary-background-color: #1953ff;
--primary-hover-color: #1145df;
--secondary-font-color: #59acff;
--secondary-background-color: transparent;
--secondary-border-color: #59acff;
--secondary-background-hover-color: transparent;
--secondary-border-hover-color: #59acff;
--secondary-font-hover-color: #59acff;
--heading-color: #fff;
--text-color: #d0d9f5;
--text-disabled-color: #999;
--light-color: #59acff; //also used for link colors
--error-color: #FF4C51;
--primary-font: 'Space Grotesk', sans-serif;
--secondary-font: 'Inter', sans-serif;
--border-color: rgba(143, 155, 191, 0.5);
--email-provider-btn-color: rgba(143, 155, 191, 0.5);
--border-radius: 25px;
--border-container-width: 0; // outer border container
--text-align: left;
}
</style>
To adjust the styling, you can use a service like https://jsfiddle.net/ and see your results directly.
If you want to use Corbado's session management, it is mandatory to include the following JavaScript logic on all of your pages. This ensures that session refresh functionality works seamlessly.
Corbado provides functionality to logout the current user. The logout work as follows:
- 1.
- 2.The current session is revoked using your long-term session (represented as session ID with database entry).
- 3.
- 4.The short-term session cookie (represented as JWT) is deleted via JavaScript.
React
Vue.js
HTML custom element
Vanilla HTML / JS
1
import { useEffect } from 'react';
2
import Corbado from '@corbado/webcomponent';
3
4
function App() {
5
const session = new Corbado.Session('<Project ID>');
6
7
useEffect(() => {
8
// Register a callback for session refresh
9
// in order to receive an authentication event
10
session.refresh(user => {
11
// Here, you can define what happens when the session is initialized
12
// if user is null, then the user is not logged in
13
});
14
}, [session]);
15
16
const handleLogout = () => {
17
session.logout()
18
.then(() => {
19
// Here, you can define what happens after the user is logged out
20
})
21
.catch(err => {
22
console.error(err);
23
});
24
}
25
26
return (
27
<div>
28
{/* Render your UI here */}
29
<button onClick={handleLogout}>Logout</button>
30
</div>
31
);
32
}
33
34
export default App;
1
<template>
2
<div>
3
<!-- Render your UI here -->
4
<button @click="handleLogout">Logout</button>
5
</div>
6
</template>
7
8
<script>
9
import Corbado from '@corbado/webcomponent';
10
11
export default {
12
name: 'App',
13
setup() {
14
return {
15
session: new Corbado.Session('<Project ID>'),
16
}
17
},
18
mounted() {
19
// Register a callback for session refresh
20
// in order to receive an authentication event
21
this.session.refresh(user => {
22
// Here, you can define what happens when the session is initialized
23
// if user is null, then the user is not logged in
24
});
25
},
26
methods: {
27
handleLogout() {
28
this.session.logout()
29
.then(() => {
30
// Here, you can define what happens after the user is logged out
31
})
32
.catch(err => {
33
console.error(err);
34
});
35
}
36
}
37
}
38
</script>
1
<!DOCTYPE html>
2
<html>
3
<head>
4
<title>Corbado</title>
5
</head>
6
<body>
7
<!-- Import Corbado SDK -->
8
<script src="https://<%= Project ID %>.frontendapi.corbado.io/auth.js"></script>
9
<!-- Use the corbado-auth-provider custom element in your HTML. -->
10
<corbado-auth-provider project-id="<%= Project ID %>">
11
<!-- Only displayed if the user is not logged in -->
12
<div slot="unauthed">
13
<corbado-auth
14
project-id="<%= Project ID %>"
15
conditional="yes"
16
>
17
<input name="username" id="corbado-username"
18
data-input="username" required
19
autocomplete="webauthn"/>
20
</corbado-auth>
21
</div>
22
23
<!-- Only displayed if the user is logged in -->
24
<div slot="authed">
25
You're logged in.
26
<!-- 'redirect-url' is the location where the logged out user
27
is forwared to -->
28
<corbado-logout-handler
29
project-id="<%= Project ID %>"
30
redirect-url="https://www.acme.com"
31
>
32
<button>Logout</button>
33
</corbado-logout-handler>
34
</div>
35
36
</corbado-auth-provider>
37
</body>
38
</html>
Please note that you have to add a second script, when using Vanilla HTML / JS:
<script src="https://<Project ID>.frontendapi.corbado.io/utility.js"></script>Be also aware that the
<button/> element MUST come before the corresponding <script/>, where it is referenced.The script must be put in
<body>part, not in<head>!<!DOCTYPE html>
<html>
<head>
<title>Corbado</title>
</head>
<body>
<!-- Import Corbado SDK -->
<script src="https://<Project ID>.frontendapi.corbado.io/auth.js"></script>
<script src="https://<Project ID>.frontendapi.corbado.io/utility.js"></script>
<!-- Logout button -->
<button id="logoutButton">Logout</button>
<script>
// Create a new session
const session = new Corbado.Session('<Project ID>');
// Register a callback for session refresh
// in order to receive an authentication event
session.refresh(user => {
// Here, you can define what happens when the session is initialized
// if user is null, then the user is not logged in
});
// Get logout button
const logoutButton = document.getElementById('logoutButton');
// Add event listener to logout button
logoutButton.addEventListener('click', function() {
session.logout()
.then(() => {
window.location.replace("/");
})
.catch(err => {
console.error(err);
});
});
</script>
</body>
</html>
If you want to find out how you can get data via Corbado session management, please see:
Please provide the URL where the web component runs (incl. protocol, port & path) as Application URL in "Settings" - "General" - "URLs". The Application URL is used, among others, to correctly direct users to the web component again, when they have clicked on an email magic link.
Application URL in developer panel
Once a user has authenticated successfully (either with passkey, email magic link or password), the user redirected to the Redirect URL in the browser.
https://www.my-application.com/redirectUrlfor a live applicationhttp://localhost:8080/redirectUrlfor localhost
Redirect URL in developer panel
By default the WebAuthn Relying Party ID will be set to
<project ID>.auth.corbado.com for previews and localhost for web component integration. This is where the passkeys are bound to. You can only use passkeys in a web component that runs in a matching domain of the Relying Party ID. Matching domains means that it's either the same or a subdomain of the Relying Party ID. Provide the Relying Party ID (without protocol, port and path) in "Settings" - "General" - "URLs", e.g.:
my-application.comfor a live applicationlocalhostfor localhost
After you made the inital settings for the web component, there are two ways depending on if you create an entirely new application (greenfield) without existing users or if you already have users that login with a password.
Last modified 5d ago