Skip to main content

WordPress guide

This tutorial will show you how to integrate Logto into your Wordpress website.

Prerequisites​

  • A Logto Cloud account or a self-hosted Logto (Check out the ⚡ Get started guide to create one if you don't have).
  • A Logto traditional application created.
  • A WordPress project: follow the official Wordpress installation guide to set up your Wordpress website before proceeding.

Integration​

Install the plugin​

We will use the OpenID Connect Generic plugin to integrate Logto via OIDC protocal into your Wordpress website.

  1. Log in to your WordPress site.
  2. Navigate to "Plugins" and click "Add New".
  3. Search for "OpenID Connect Generic" and install the plugin by daggerhart.
  4. Activate the plugin.

Configure redirect URI​

First, let’s configure the redirect URI. You can find it in the plugin settings, scroll down to the "Notes" section, and copy the "Redirect URI" value.

Switch to the Application details page of Logto Console. Add a Redirect URI, and click "Save changes".

Set up the plugin​

Refer to the following table for the necessary configuration details:

Plugin FieldDescription
Client IDThe app ID of your Logto application
Client SecretThe app secret of your Logto application
OpenID ScopeEnter email profile openid offline_access
Login Endpoint URLThe authorization endpoint URL of your Logto application, which is https://[tenant-id].logto.app/oidc/auth, you can click "show endpoint details" in the Logto application page to get the URL.
Userinfo Endpoint URLThe userinfo endpoint URL of your Logto application, which is https://[tenant-id].logto.app/oidc/me.
Token Validation Endpoint URLThe token validation endpoint URL of your Logto application, which is https://[tenant-id].logto.app/oidc/token.
End Session Endpoint URLThe end session endpoint URL of your Logto application, which is https://[tenant-id].logto.app/oidc/session/end.
Identity KeyThe unique key in the ID token that contains the user's identity, it can be email or sub, depending on your configuration.
Nickname KeyThe key in the ID token that contains the user's nickname, you can set it to sub and change it later.

Checkpoint: Test your application​

Now, you can test your application:

  1. Log out of your WordPress site.
  2. Visit the WordPress login page and click the "Sign in with Logto" button.
  3. You will be redirected to the Logto sign-in page.
  4. Sign in with your Logto account.
  5. You will be redirected back to the WordPress site and logged in automatically.

Roles mapping​

WordPress has a built-in user role management system that defines what actions (capabilities) a user can perform on a site. The default user roles include Administrator, Editor, Author, Contributor, and Subscriber, each with its own set of capabilities.

Logto employs Role-Based Access Control (RBAC) as its authorization model, utilizing "scopes" as the smallest unit of permission. These scopes define the specific actions that an authenticated user is allowed to perform within an application. However, WordPress operates on a different principle for managing user permissions, relying on predefined "roles" that bundle various capabilities together.

Given this fundamental difference, we suggest creating special roles within Logto that correspond to the roles defined in WordPress. Thoes roles may not have any scopes, they are only used as a reference for mapping users to WordPress roles.

Prerequisites​

  • Setup roles in Logto that correspond to the roles in WordPress. For example, if you have an 'editor' role in WordPress, create a 'group:editors' role in Logto.

Implement role mapping​

To implement role mapping, we will add custom code to the WordPress theme's functions.php file. This involves using the wp_login action hook, which triggers when a user logs in. Here's a step-by-step guide on how to set this up:

Step 1: access your theme's functions.php​

Open your theme’s functions.php file. You can access this file through the WordPress admin panel by navigating to Appearance > Theme Editor and selecting functions.php from the right-hand side files list. Or in the source code, navigate to your WordPress theme directory and locate the functions.php file. This file allows you to add custom PHP functions that extend the functionality of your WordPress site.

Step 2: write the role mapping function​

Below is a simple example of a function that you might add to functions.php. This function will be triggered upon user login, and it will assign roles based on the user's roles claim fetched from Logto.

function logto_handler($user_login, $user = null) {
	if (!$user) {
		$user = get_user_by('login', $user_login);
	}

	$oidc_claims = get_user_meta($user->ID, 'openid-connect-generic-last-user-claim', true);

	if (in_array('group:editors', $oidc_claims['roles'])) {
		$user->set_role('editor');
	} else {
		$user->set_role('subscriber');
	}
}

add_action('wp_login', 'logto_handler', 10, 2);

Step 3: understanding the code and customizing it​

  • logto_handler function: This function takes two parameters: $user_login (username) and $user (user object). It retrieves roles from Logto which stored in user meta as openid-connect-generic-last-user-claim, maps this role to a corresponding WordPress role, and assigns it to the user.

  • add_action: This line hooks the logto_handler function to the wp_login action, which is triggered after a user logs in. The 10 is the priority (default), and 2 indicates the number of arguments the function accepts.

The example above assigns the 'editor' role to users authenticated via Logto with role name group:editors. However, in a real-world scenario, you'll likely need to implement more kinds of role mappings.

You can find the list of WordPress roles and their capabilities here.

Step 4: test your setup​

Now, let's test the role mapping function by logging in with a user that has the group:editors role in Logto. After logging in, check the user's role in WordPress to ensure that the mapping is working correctly.

Further readings​