Contact us

Adding OpenID to WordPress allows for existing users on a domain to connect without having to manage another account. In this setup, we will be using Keycloak to provide the existing accounts which the OpenID plugin will use.

There are a few plugins for WordPress that allow this functionality, but we will be using OpenID-Connect-Generic by Daggerhart.

Keycloak Client Setup

First step is to create a client in Keycloak. In the Keycloak web UI, create an openid-connect client by going to Clients and click Create.

There are a few settings to take note:

Endpoint Configuration or /auth/realms/{REALM}/.well-known/openid-configuration. These will be used in the next steps.

OpenID Connect - Generic Client Setup

Next, the actual plugin needs to be installed and activated in WordPress. The plugin can be installed like any other plugin by going to Plugins -> Add New. Once this has finished, there will be a new settings page located under Settings -> OpenID Connect Client.

The settings are straightforward and have a nice description under each field to describe the expected values. Most of the setting values needed are found on the Keycloak endpoint page mentioned above.

The main changes needed are as follows:

Congratulations! There should now be a button at the wp-admin login to redirect to a Keycloak login page. The plugin also has a debug log that can be enabled to help troubleshoot any problems.

When switching to root after the typical SSH with X11 forwarding enabled this error can appear:

$ X11 connection rejected because of wrong authentication.
$ Error: Can't open display: localhost:10.0

The workaround seems to include copying the MIT-MAGIC-COOKIE-1 from the user who ssh'd in to the root user using xauth. Here's how:

First verify the $DISPLAY being used and list the MIT-MAGIC-COOKIE-1 used for it :

$ echo $DISPLAY
localhost:10.0
$ xauth list
srv001/unix:10  MIT-MAGIC-COOKIE-1  b7ff39ed41f66cfe8fe439ed99e582ba

Next switch to root and copy the whole line that was listed and then add it to the root profile:

# xauth add srv001/unix:10  MIT-MAGIC-COOKIE-1  b7ff39ed41f66cfe8fe439ed99e582ba

Now assuming everything is correct in the standard ssh_config the error should go away and a window will before forwarded through the pipe.

Having a staging server for WordPress is quite useful for testing new features without the worry of breaking something in production. It is also helpful when you have a multi user environment and need to test something that could impact others. In this article it is assumed that your WordPress instance has SELinux enabled as is the case on RHEL/CentOS for example. On other distros like Ubuntu or Debian you can omit the steps specific to SELinux.

Assuming a fresh staging WordPress is ready with the SSL cert and hostname taken care of, you can import server files and the database.

Exporting Production Data

On the production server with the WordPress database, you will need to copy the database with mysqldump:

mysqldump wordpress | gzip > wordpress.sql.gz

Export the server files with the selinux context:

tar -czvf /tmp/wordpress.tar.gz /srv/wordpress --selinux

Importing Production Data

Extract WordPress server files to where the server files will be stored, e.g. /srv/wordpress:

tar -xzvf wordpress.tar.gz

To add system_u to the context:

chcon -R -u system_u -t httpd_sys_rw_content_t /srv/wordpress

You should verify that apache:apache is the user:group and system_u is mapped:

ls -lZ
-rw-r--r--. apache apache system_u:object_r:httpd_sys_rw_content_t:s0 index.php
-rw-r--r--. apache apache system_u:object_r:httpd_sys_rw_content_t:s0 license.txt
-rw-r--r--. apache apache system_u:object_r:httpd_sys_rw_content_t:s0 out.txt
-rw-r--r--. apache apache system_u:object_r:httpd_sys_rw_content_t:s0 readme.html
-rw-r--r--. apache apache system_u:object_r:httpd_sys_rw_content_t:s0 wp-activate.php
drwxr-xr-x. apache apache system_u:object_r:httpd_sys_rw_content_t:s0 wp-admin
---- snip ----

SQL dump import:

gunzip wordpress.sql.gz && mysql < wordpress.sql

Final Configuration

Use wp search-replace to find all references to the production server and replace it with staging server:

wp search-replace https://www.example.com https://www-staging.example.com

The last thing to do is to verify that everything needed for the WordPress plugins is done.

Oxygen is one example that needs some extra configuration on migration such as css cache generation and shortcodes. The next items will be located within the wp-admin area in the browser.

Generate CSS Cache (in browser):

/wp-admin/admin.php?page=oxygen_vsb_settings&tab=security_manager OR
Oxygen -> Settings ->  Security -> Sign All Shortcodes

Generate shortcodes (in browser):

/wp-admin/admin.php?page=oxygen_vsb_settings&tab=cache OR
Oxygen -> Settings -> CSS Cache -> Regenerate

Notes

It is best to discourage your staging site from being indexed by search engines. You can disable that by:

/wp-admin/options-reading.php OR Settings -> Reading -> Discourage search engines

If only a white page loads then chances are there is a plugin needing changes. You can go through and disable the plugins one by one to find the culprit. If the website redirects you to the old server, there might be a reference in the database needing to be changed. You can use the wp search-replace tool to correct this.

Integrating Keycloak with Gitlab SAML makes it easier to manage users in an organization from a central point. You could manage separate accounts on Gitlab, but for us it makes sense to utilize Keycloak as we are already using it for other applications.


The first step is to create a Gitlab SAML client in the Keycloak dashboard. With the correct realm selected, navigate to the Clients configuration page and click the create button to add a new client.

Add client:

 Client ID:        gitlab
 Client Protocol:  saml

Note: Keep track of the client ID as that will need to match in the Gitlab configuration.

Next modify the newly created client and change whats needed:

 Client Signature Required:   OFF
 Force Name ID Format:        ON
 Name ID Format:              email
 Valid Redirect URIs:         https://gitlab.example.com/*
 Base URL:                    https://gitlab.example.com/users/auth/saml/callback

Note: According to the Gitlab Security, it is important to force the name ID format.

Next navigate to the Mappers tab and apply the Assertions described here:

 Name:                      email
 Mapper Type:               User Property
 Property:                  Email
 Friendly Name:             email
 Saml Attribute Name:       email

 Name:                      username
 Mapper Type:               User Property
 Property:                  Username
 Friendly Name:             username
 Saml Attribute Name:       username

 Name:                      first_name
 Mapper Type:               User Property
 Property:                  FirstName
 Friendly Name:             first_name
 Saml Attribute Name:       first_name

 Name:                      last_name
 Mapper Type:               User Property
 Property:                  LastName
 Friendly Name:             last_name
 Saml Attribute Name:       last_name

The next part can be a little tricky. You could add the full certificate to the idp_cert property, but I like to use the fingerprint as this looks nicer. We need the SHA1 hash of the certificate used for the Keycloak realm, but Keycloak's certificate is formatted in a way that makes it a little harder. Under Realm Settings -> Keys locate the Certificate button for the RSA certificate.

You can get the SHA1 hash by pasting this into the terminal:

read -p "Paste Certificate: " CERT;echo -e "-----BEGIN CERTIFICATE-----\n$CERT\n-----END CERTIFICATE-----" | openssl x509 -noout -fingerprint -sha1

Paste the cert displayed from Keycloak into the input of the above script. You should see something like:

SHA1 Fingerprint=8F:F3:20:F7:73:DE:42:85:9B:F9:1E:BF:35:79:46:53:4B:A1:E3:18

Now for the Gitlab part which can be explained in more detail here. There are a couple properties to take note:

On the Gitlab server edit /etc/gitlab/gitlab.rb and ensure the properties exist with the appropriate changes:

gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
{
  name: 'saml',
  args: {
           assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
           idp_cert_fingerprint: '8F:F3:20:F7:73:DE:42:85:9B:F9:1E:BF:35:79:46:53:4B:A1:E3:18',
           idp_sso_target_url: 'https://keycloak.example.com/auth/realms/REALM/protocol/saml',
           issuer: 'gitlab',
           name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
         },
  label: 'Provider name' # optional label for SAML login button, defaults to "Saml"
}]

Don't forget to reconfigure Gitlab:

gitlab-ctl reconfigure

You should now be able to login with Keycloak with the newly added SAML label created above!

menucross-circle