Integrate with Drupal

Last updated on Aug 7, 2023

Make your Drupal admin login more secure!

This guide provides information on how to set up Beyond Identity as a passwordless authentication provider for a Drupal site.

In this guide, you'll:

1. Configure Beyond Identity as an Identity Provider
2. Install and configure the required module to support an OpenID Connect (OIDC) integration

Prerequisites

Before continuing, make sure that the following prerequisites have been met:

• A Beyond Identity developer account.

• A live Druapl site running and administrator privileges to install and configure modules.

Set up Beyond Identity as an Identity Provider

To set up Beyond Identity as an Identity Provider, you need to create a Realm to hold identities and configuration. Inside that realm, you'll need to create an Application that contains the authentication flow configuration. These can be configured in you admin console that was created for you when you signed up for a developer account.

Create a Realm

Creating a realm from the Beyond Identity Admin Console is easy.

1. In the Admin Console, under Tenant Management, select Go to realm > Create new realm.

   

2. Enter a name for your realm and click Create realm.

3. In the confirmation dialog, switch to the new realm.

   

Create an Application

1. From the Admin Console, under Authentication, select Apps > Add new app.

   

2. Give your application a name.

   

3. On the External Protocol tab, use the following values to complete this tab.

   
   

   Client Configuration

   Property	Value
   Protocol	OIDC Why OIDC? OAuth2 is primarily an authorization framework for resource access, while OIDC builds on OAuth2 to provide an identity layer for authentication, allowing client applications to obtain information about the authenticated user. Both protocols are often used together in modern applications to provide a comprehensive solution for secure authentication and authorization.
   Client Type	Confidential Why Confidential? A "confidential" client type is ideal when your application can securely store a client secret and requires enhanced security features for token exchange and accessing user-specific resources. If your application runs in an untrusted environment or you cannot securely manage a client secret, a "public" client type might be more appropriate.
   PKCE	Disabled
   Redirect URIs	This URL will also be generated for you in the OIDC module. You can always come back to change it. Your redirect URI follows the pattern: https://${your-website-domain.com}/openid-connect/${client_machine_name}
   Token Endpoint Auth Method	Client Secret Post
   Grant Type	Authorization Code Why Authorization Code? The "authorization_code" grant type is suitable for confidential clients, especially when your application needs to access user-specific resources, requires Single Sign-On (SSO) support, and prioritizes security in the authentication process. It provides a secure and standardized way to obtain access to user data and resources without exposing user credentials to the client application.
   All other options	Use the default values for the remaining options

   
   

4. Click the Authenticator Config tab and use the following values.

   Property	Value
   Configuration Type	Hosted Web Why Hosted Web? Hosted Web handles passkey registration and authentication for you, including generating new passkeys, presenting users with authenticator choice options as needed, and validating passkey assertions. With this model, your app simply needs to redirect to Beyond Identity's hosted web authenticator, and we do the rest.
   Authentication Profile	Use the recommended values for the remaining options

5. Click Submit to save the new app.

At this point, your Beyond Identity Admin Console should be configured with a realm and an application set up. The Hosted Web handles passkey registration and authentication for you, including generating new passkeys, presenting users with authenticator choice options as needed, and validating passkey assertions. You are now ready to configure the OpenID Connect Drupal module.

Configure the OpenID Connect Drupal module

This module allows you to use an external OpenID Connect login provider to authenticate and log in users on your site. Existing users are automatically logged into your Drupal site, while new users get created in Drupal.

note

User roles will need to be managed from your admin dashboard. New users created in your Drupal database will have a default "Authenticated" user role.

Install the OIDC module

This guide is based on the OpenID Connect / OAuth client and requires administrative privileges to install to your Drupal site.

Install the OIDC module as you would install a contributed Drupal module.

Configure the module

After you've installed and enabled the module, you'll add the required values from your application you created in the Beyond Identity Admin Console.

1. Log into you Drupal admin console.

2. Go to Home > Administration > Configuration > People > OpenID Connect clients.

3. Under the Clients tab, select and enable + Generic OAuth 2.0.

   

4. Navigate to Add OpenID Connect client.

5. Enter Beyond Identity for the name.

6. Enter the values from the External Protocol tab of the application you created in the Beyond Identity Admin Console.

   Property	Beyond Identity Admin Console value
   Client ID	Copy and paste the Client ID value from your application's External Protocol tab.
   Client Secret Key	Copy and paste the Client Secret value from your application's External Protocol tab.
   Allowed domains	Ignore this field
   Authorization endpoint	Copy and paste the Authorization Endpoint value from your application's External Protocol tab.
   Token endpoint	Copy and paste the Token Endpoint value from your application's External Protocol tab.
   Userinfo endpoint	Copy and paste the User Info Endpoint value from your application's External Protocol tab.
   End Session endpoint	Leave blank
   Scopes	email profile openid

7. Click Create OpenID Connect client.

   A redirect URL is generated.

   From the Beyond Identity Admin Console, under Applications, select your application, scroll down to the Redirect URIs field and paste the generated URL.

   

Allow exisiting users to login

You can allow existing users in your Drupal system to login.

1. Select the Settings tab and configure the plugin to the settings you prefer.

2. From the Advanced tab, select the Automatically connect exisiting users checkbox.

   

Enable new user creation on successful login

If you send a passkey to a user not in your Drupal system, the login fails. You can mitigate that by overriding a setting.

1. Select the Settings tab.

2. Select the Override registration settings checkbox.

   This assigns a new user as an Authenticated user with no other defined role. You can change the user's role in your Drupal admin settings.

   

Display login button on user login form

There are two ways to do this. You can either add a block provided by the module, or configure the openID button display in user login form in Settings. The easiest option is to configure the Settings.

Choose the option that works best for your site:

• Hidden: hides the login button and best to use when displaying a block

• Above: displays the login button above the login form

• Below: displays the login button below the login form

• Replace: hides the core login form and only shows the OIDC login option

Try logging in

Test the log in and verify successful authentication.

1. From the same browser where you generated a passkey, visit your /user/login admin page.

2. Click Login with Beyond Identity.

   You'll be redirected to the Beyond Identity Web Authenticator.

3. Depending on how Policy is set up for your tenant, you may see a step-up authentication prompt.

   Aftert a successful authentication, you'll be redirected to your Drupal site. You'll also see successful authentication events in the Beyond Identity Admin Console under Events.