Skip to content

Commit 3a3dc80

Browse files
wangsijiewangsijie
authored
feat: add wordpress integration (#657)
1 parent b1d7912 commit 3a3dc80

File tree

1 file changed

+119
-0
lines changed

1 file changed

+119
-0
lines changed

‎docs/quick-starts/framework/wordpress/README.mdx

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
slug: /quick-starts/framework/wordpress
3+
sidebar_label: WordPress
4+
---
5+
6+
import FurtherReadings from '../../fragments/_further-readings.md';
7+
8+
# WordPress guide
9+
10+
This tutorial will show you how to integrate Logto into your [Wordpress](https://wordpress.org) website.
11+
12+
## Prerequisites
13+
14+
- A [Logto Cloud](https://cloud.logto.io) account or a self-hosted Logto (Check out the [⚡ Get started](../../../docs/tutorials/get-started/) guide to create one if you don't have).
15+
- A Logto traditional application created.
16+
- A WordPress project: follow the official [Wordpress installation guide](https://wordpress.org/support/article/how-to-install-wordpress/) to set up your Wordpress website before proceeding.
17+
18+
## Integration
19+
20+
### Install the plugin
21+
22+
We will use the [OpenID Connect Generic](https://wordpress.org/plugins/generic-openid-connect/) plugin to integrate Logto via OIDC protocal into your Wordpress website.
23+
24+
1. Log in to your WordPress site.
25+
2. Navigate to "Plugins" and click "Add New".
26+
3. Search for "OpenID Connect Generic" and install the plugin by daggerhart.
27+
4. Activate the plugin.
28+
29+
### Configure redirect URI
30+
31+
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.
32+
33+
Switch to the Application details page of Logto Console. Add a Redirect URI, and click "Save Changes".
34+
35+
### Set up the plugin
36+
37+
Refer to the following table for the necessary configuration details:
38+
39+
| Plugin Field | Description |
40+
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41+
| Client ID | The app ID of your Logto application |
42+
| Client Secret | The app secret of your Logto application |
43+
| OpenID Scope | Enter `email profile openid offline_access` |
44+
| Login Endpoint URL | The 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. |
45+
| Userinfo Endpoint URL | The userinfo endpoint URL of your Logto application, which is https://[tenant-id].logto.app/oidc/me. |
46+
| Token Validation Endpoint URL | The token validation endpoint URL of your Logto application, which is https://[tenant-id].logto.app/oidc/token. |
47+
| End Session Endpoint URL | The end session endpoint URL of your Logto application, which is https://[tenant-id].logto.app/oidc/session/end. |
48+
| Identity Key | The unique key in the ID token that contains the user's identity, it can be email or sub, depending on your configuration. |
49+
| Nickname Key | The key in the ID token that contains the user's nickname, you can set it to sub and change it later. |
50+
51+
### Checkpoint: Test your application
52+
53+
Now, you can test your application:
54+
55+
1. Log out of your WordPress site.
56+
2. Visit the WordPress login page and click the "Sign in with Logto" button.
57+
3. You will be redirected to the Logto sign-in page.
58+
4. Sign in with your Logto account.
59+
5. You will be redirected back to the WordPress site and logged in automatically.
60+
61+
## Roles mapping
62+
63+
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.
64+
65+
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.
66+
67+
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.
68+
69+
### Prerequisites
70+
71+
- 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.
72+
73+
### Implement role mapping
74+
75+
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:
76+
77+
### Step 1: access your theme's functions.php
78+
79+
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.
80+
81+
### Step 2: write the role mapping function
82+
83+
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.
84+
85+
```php
86+
function logto_handler($user_login, $user = null) {
87+
if (!$user) {
88+
$user = get_user_by('login', $user_login);
89+
}
90+
91+
$oidc_claims = get_user_meta($user->ID, 'openid-connect-generic-last-user-claim', true);
92+
93+
if (in_array('group:editors', $oidc_claims['roles'])) {
94+
$user->set_role('editor');
95+
} else {
96+
$user->set_role('subscriber');
97+
}
98+
}
99+
100+
add_action('wp_login', 'logto_handler', 10, 2);
101+
```
102+
103+
### Step 3: understanding the code and customizing it
104+
105+
- `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.
106+
107+
- `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.
108+
109+
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.
110+
111+
You can find the list of WordPress roles and their capabilities [here](https://wordpress.org/support/article/roles-and-capabilities/).
112+
113+
### Step 4: test your setup
114+
115+
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.
116+
117+
## Further readings
118+
119+
<FurtherReadings />

0 commit comments

Comments
 (0)