Links

Web component (previous version)

This guide shows how to integrate the Corbado web component into your website.

Overview

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 use React or VanillaJS as your tech stack, we highly recommend to use the new React components or VanillaJS components.

Setup

1. Embed the web component into your site

You can install the Corbado web component via npm or add the JavaScript library via CDN.
Via NPM
Via CDN
Install the web component via NPM:
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 <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 -->

2. Add additional HTML attributes (optional)

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
This should be your Frontend API.
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
disable-input-animation
Remove the animation of the labels for input fields
no
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.

3. Adapt styling (optional)

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;
--email-link-resend-margin: 0px; // change margin of button at resend page
}
</style>
To adjust the styling, you can use a service like https://jsfiddle.net/ and see your results directly.

4. Add session management (optional)

4.1 Session refresh

If you want to use Corbado's session management, it is mandatory to include the JavaScript logic below on all of your pages. This ensures that session refresh functionality works seamlessly.

4.2 Session logout

Corbado provides functionality to logout the current user. The logout work as follows:
  1. 1.
    Corbado sends an AJAX call to your Frontend API.
  2. 2.
    The current session is revoked using your long-term session (represented as session ID with database entry).
  3. 3.
    In the response of the AJAX call, Corbado sends a delete cookie.
  4. 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:

5. Define Application URL

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.
Often, it is on the same domain like the authorized origin.
Application URL in developer panel

6. Define Redirect URL

Once a user has authenticated successfully (either with passkey, email magic link or password), the user redirected to the Redirect URL in the browser.
Provide the Redirect URL (incl. protocol, port and path) in "Settings" - "General" - "URLs", e.g.:
  • https://www.my-application.com/redirectUrl for a live application
  • http://localhost:8080/redirectUrl for localhost
Redirect URL in developer panel

7. Verify Relying Party ID

By default the WebAuthn Relying Party ID will be set to <project ID>.preview.corbado.io 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.com for a live application
  • localhost for localhost
If you develop locally on http://localhost:<port>, please set the Relying Party ID to localhost.
We highly recommend to take at our detailed blog post about the Relying Party ID.

Next steps

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.