Adding guide for zitadel idp to the wiki

[mffap]

Review Wiki Please be sure to check the GitHub Wiki to see if your question has already been answered.

General usage questions Hi - Thanks for the great project! I was helping someone from our community setting up this plugin with ZITADEL as IDP. It works like a charm. I've written a short integration guide for the authentication part, similar to Keycloak, since it also describes a multi-tenancy setup. We're currently trying to figure out how to do role-mapping and might update the guide later on.

Could this guide be added to the Wiki? It seems like I'm not able to create a PR directly. Maybe I’ve overlooked something, thanks for the help in that case.

Thanks.

---

Overview

The settings outlined in this guide are a starting point reference of a known working ZITADEL OpenID Connect Application configuration for the OpenID Connect Generic plugin. This setup was performed on ZITADEL Cloud with a basic multi-tenancy setup, which requires you to setup a new organization first. The guide can also be followed for a single tenant setup, ignoring the organization specific scopes in the configuration.

Reference resources:

• ZITADEL Documentation
• ZITADEL Console - Applications Guide
• ZITADEL Console - Organizations Guide

ZITADEL Configuration

1. Login to Console with your Manager user and switch to the organization you will use for authentication. Navigate to Projects, then "Owned Projects", click "Create New Project", give your project a name. Save and continue on the next page.
2. Under "General" create a new application by clicking "New", select the box "I'm a pro. Skip this wizard". Provide a Name and select "Web" from Application Type.
   
3. Enter the information given below and make sure to replace {your_domain} with your actual domain name
4. Click create and save the Client ID and Client Secret
5. On the following screen click "Refresh Token" and then Save.

OIDC Client Configuration

• Grant Types: Authorization Code
• Response Types: Code
• Authentication Method: Basic
• Redirect URIs: https://{your_domain}/wordpress/wp-admin/admin-ajax.php?action=openid-connect-authorize
• Post Logout URIs: https://{your_domain}/wordpress/wp-login.php?loggedout=true&wp_lang=en_US

WordPress OpenID Connect Generic Plugin Configuration

Endpoints

When setting up the plugin on the WordPress site most of the key client configuration can be found from the ZITADEL OpenID Connect configuration endpoint.

Example: https://{your_domain}/.well-known/openid-configuration

This will provide all of the endpoints needed for configuring the plugin.

Scopes

Besides the standardized scopes email profile openid offline_access, you need to provide two reserved scopes to tell ZITADEL which organization your user should be logged into and to request the user roles.

With the scope urn:zitadel:iam:org:id:{your_organization_id} you tell ZITADEL to select a specified organization and the user must be a member of that organization. Make sure to replace {your_organization_id} with your organization's ID, which is labeled "Resource Id" in the Console.

You can request the user's roles in the project by passing the scope urn:zitadel:iam:org:project:roles

Wordpress Configuration

1. Enter the "Client ID" & "Client Secret Key" into the plugin settings screen.
2. Enter in the "OpenID Scopes" with the recommended list of email profile openid offline_access urn:zitadel:iam:org:id:{your_organization_id} urn:zitadel:iam:org:project:roles. Make sure to replace {your_organization_id} with your organization's ID.
3. Enter in all of the endpoints as found when viewing the client configuration endpoint URL.
4. "Identity Key" you can leave as preferred_username.
5. "Nickname Key" can be configured with preferred_username, name, or sub as they are generally all valid claims. You can confirm these in the client configuration endpoint.
6. "Email Formatting" should work as {email}.
7. "Enable Refresh Token" should be checked.
8. Select "Create user if does not exist" when you want to create the users automatically in Wordpress

With this setup you should now be able to login with your ZITADEL instance as the IDP and logout of WordPress & ZITADEL resulting in being taken back to the WordPress login screen.

[adamphetamine]

Thanks so much for all this work @mffap !

Looking at this a bit closer, here are my impressions- Language and formatting in your guide is pretty much perfect, I'd only change a few small things to make them more explicit (I have trouble following a lot of tutorials that infer info)

Regarding passing user roles and permissions- The author of the IODC plugin has decided that Roles etc. should not be part of the core plugin, and his solution is to have another plugin to do this, (needs to be added and marked as 'must use' in Wordpress). He has provided a sample that works with Keycloak here- https://github.com/timnolte/oidc-keycloak-sso/blob/main/oidc-keycloak-custom.php

I don't have the skills to re-write this for Zitadel but I may be able to sponsor some of the work?

The other alternative is this- https://wordpress.org/plugins/umich-oidc-login/

I had ignored this because of the massive branding, but it does appear to handle group based authorisations. I will give it a try and report back...

[adamphetamine]

ok this didn't go exactly as expected, but I hope I this info is useful-

I sent the example keycloak php plugin to a friend to see if he can re-do it for Zitadel, will let you know. Then I installed this plugin-

https://wordpress.org/plugins/oauth-client-for-user-authentication/

This seems to offer a lot of the features I wanted, but none of them are finished, a lot of the dialog boxes and input fields seem to be just placeholders. I wrote to the author and he wanted me to review it, but couldn't get answers about the missing features- meh, I know how long some stuff takes! One really cool feature of this plugin is that as part of the setup, it will display some of the variables in a pop up window- you input some basic stuff, then it will contact the Server (in this case Zitadel) then show you the results so you can add those variables into the SSO setup fields. Nice.

Now back to UMich plugin

https://wordpress.org/plugins/umich-oidc-login/

This plugin DOES seem to support assertion of user roles via a shibboleth attribute for LDAP group membership. Unfortunately I've been unable to figure out how to map these attributes into Wordpress with Zitadel.

My use case is to connect Zitadel users and roles to Wordpress but I've also discovered that a LOT of plugins have their own concept of users and roles, so this may be impossible to achieve in a generic tutorial.

Thanks again for your quick and super helpful docs, I will try to contribute back when I find anything useful!