Overview

Web Component Flow Existing Users

Setup webhooks

Webhooks / Corbado CLI are only required if you connect your existing user base. If you create a new application without existing users, you do not need webhooks / Corbado CLI. In this case, please do the integration at New application (no existing users).

Corbado leverages webhooks to exchange data with your backend and current user management system. Corbado not only uses webhooks to push data to your backend but also uses the response from your backend to provide a smooth user experience (bi-directional data exchange).

Corbado’s usage of webhooks allows the lighweight integration of Corbado into existing systems without major changes to your current authentication and user management.

Webhooks URL configuration

You will need to configure the endpoints of your application which will receive the data from Corbado. You can do this by clicking on “Settings” - “Webhooks” - “Configuration”:

Please add a webhooks URL that will be the endpoint exposed by your backend which will process the data:

Webhooks Settings

Webhooks authentication configuration

To communicate securely with your backend, HTTP basic authentication is used. Please set an HTTP basic authentication username and password in the developer panel (this authentication information needs to be set up in your backend, e.g. via Node.js SDK,PHP SDK or Go SDK as well).

Webhooks Settings

Once you’re ready, click on “Save changes”.

Please have a look at webhooks for more details.

Get login information

  1. POST login information by username
  2. Login information

1. POST login information by username

Corbado sends to your webhooks URL a specific username.

Create an instance of the SDK first. Please add webhookUsername and webhookPassword to config.

//see details here: https://github.com/corbado/example-webcomponent-php-symfony/blob/a1ba00f5831a6a3b5fb7b29fa2ad371748766973/src/Controller/WebhookController.php#L42
$webhookUsername = 'webhookUsername'; // Fetch from configuration or database
$webhookPassword = 'webhookPassword'; // Fetch from configuration or database

// Create new webhook instance with "webhookUsername" and "webhookPassword". Both must be
// set in the developer panel (https://app.corbado.com) and are used to secure your
// webhook (this one here) with basic authentication.
$webhook = new Webhook($webhookUsername, $webhookPassword);

// Handle authentication so your webhook is secured (basic authentication). If username
// and/or password are invalid handleAuthentication() will send HTTP status code
// 401 (Unauthorized) and terminate/exit execution here.
$webhook->handleAuthentication();

// Check if request has been made with POST. For Corbado webhooks
// only POST is allowed/used.
if (!$webhook->isPost()) {
    throw new Exception('Only POST is allowed');
}

switch ($webhook->getAction()) {
    // Handle the "authMethods" action which basically checks
    // if a user exists on your side/in your database.
    case $webhook::ACTION_AUTH_METHODS:
        $request = $webhook->getAuthMethodsRequest();

        // Now check if the given user/username exists in your
        // database and send status. Implement getUserStatus()
        // function below.
        $status = $this->userStatus($userRepo, $request->data->username);
        $webhook->sendAuthMethodsResponse($status);

        break;
    
    // ...
}

/**
 * Detects user status
 *
 * @param UserRepository $userRepo
 * @param string $username
 * @return string
 */
private function userStatus(UserRepository $userRepo, string $username): string
{
    $user = $userRepo->findOneBy(['email' => $username]);

    // Look up in database if $username exists and if $username is blocked/not permitted to login

    if ($user == null) {
        return AuthMethodsDataResponse::USER_NOT_EXISTS;
    }

    if ($user->isBlocked()) {
        return AuthMethodsDataResponse::USER_BLOCKED;
    }

    return AuthMethodsDataResponse::USER_EXISTS;
}

2. Login information

The response status from the webhook should either be exists, not_exists or blocked:

{
	"responseID": "d5a80602-a771-4532-8cc8-6d4a9003d92a", // A response ID you can set in your backend for debugging 
	"data": {
		"status": "exists" // other values are "not_exists" and "blocked"
	}
}

Authenticate the user with passkeys / passwordless options

This authentication part is the same to authentication without an existing user base.

3.1 Redirect user to Redirect URL

4.1 Session management

3.1 Redirect user to Redirect URL

On successful authentication (e.g. with passkeys or email magic link), the user is redirected to the Redirect URL in the browser.

4.1 Session management

4.1.1 Corbado session management

Corbado offers secure and easy management that you can use out-of-the-box.

Depending on your application’s setup, you have different choices for protecting routes with Corbado’s session management. Please see Sessions - Protecting routes for details.

Sessions

4.1.2 Own session management

If you want to keep your existing session management, you can keep that of course and use Corbado only for authentication. Please see Own session management for details.

Own Session Management

Optional: Authenticate users with passwords

Corbado does not offer password login as authentication method on its own but lets you integrate your existing password login. To use it besides passkeys and other passwordless authentication methods, the web component flow looks as follows:

Webcomponent authentication flow

In order to allow password logins, steps 1 and 2 stay the same. If the user decides to use passwords or his device is technically not ready to use passkeys, steps 3.2 to 6.2 are conducted instead of steps 3.1 to 4.1.

3.2 POST password verify

The web component sends a webhook containing username and password directly to your webhooks URL.

Create an instance of the SDK first. Please add webhookUsername and webhookPassword to config.

// Details: https://github.com/corbado/example-webcomponent-nodejs/blob/c9aeef3f5ef43d529355e97c2cf3a39164767593/src/controllers/corbadoWebhookController.js#L55
// Get the webhook action and act accordingly. Every Corbado
// webhook has an action.
switch ($webhook->getAction()) {
    
    // ...
        
    // Handle the "passwordVerify" action which basically checks
    // if the given username and password are valid.
    case $webhook::ACTION_PASSWORD_VERIFY:
        $request = $webhook->getPasswordVerifyRequest();

        // Now check if the given username and password is
        // valid. Implement verifyPassword() function below.
        $webhook->sendPasswordVerifyResponse($this->verifyPassword($userRepo, $request->data->username, $request->data->password));

        break;
    
    // ...
}


/**
 * Verify given username and password.
 *
 * @param UserRepository $userRepo
 * @param string $username
 * @param string $password
 * @return bool
 */
private function verifyPassword(UserRepository $userRepo, string $username, string $password): bool
{
    $user = $userRepo->findOneBy(['email' => $username]);
    if ($user == null || $user->getPassword() == null) {
        return false;
    }

    return password_verify($password, $user->getPassword());
}

4.2 Password verify response

Only if the response indicates success, the web component will resume the authentication process.

{
	"responseID": "d5a80602-a771-4532-8cc8-6d4a9003d92a", // A response ID you can set in your backend for debugging 
	"data": {
		"success": true	// else false
	}
}

5.2 Redirect user to Redirect URL

On successful authentication (e.g. with passkeys or email magic link), the user is redirected to the Redirect URL in the browser.

6.2 Session management

6.2.1 Corbado session management

Corbado offers secure and easy management that you can use out-of-the-box.

Depending on your application’s setup, you have different choices for protecting routes with Corbado’s session management. Please see Sessions - Protecting routes for details.

Sessions

6.2.2 Own session management

If you want to keep your existing session management, you can keep that of course and use Corbado only for authentication. Please see Own session management for details.

Own session management