Configuring OpenID Connect

Available since 3.24.0

1. Configure OpenID Connect

We also provide specific examples for how to setup OpenID Connect in CleanSpeak

1.1. General OpenID Connect instructions

To setup OpenID Connect authentication in CleanSpeak you will need to do the following

  1. Navigate to Settings → System → Authentication

  2. Enable OpenID Connect Configuration

  3. Collect Client ID and Client Secret from the provider and insert them into the form.

  4. Enter the issuer or manually enter the endpoints

    1. If your provider has implemented a well-known URL you will likely just be able to use the providers domain (Ex: https://example.com) for the issuer. We will then navigate to https://example.com/.well-known/openid-configuration to automatically collect the required details for connecting.

    2. If your provider does not provide a well-known URL then you will need to manually provide their authorize, token, and userinfo URLs which should be documented with the provider.

  5. Enter the text you would like displayed on the login button

  6. Click save

Table 1. Form Fields

Client ID Required

The client id is how OpenID/OAuth identify who is asking for identification and in this case is how CleanSpeak tells the provider that it is the one asking for user logins. This is used on the authorization and token endpoints to authenticate CleanSpeak.

Client Secret optional

This is a way to prevent other applications from using the same ID as CleanSpeak and is up to the provider if they require it. This is used on the authorization and token endpoints to authenticate CleanSpeak.

Issuer Required

This field allows CleanSpeak to look up the endpoints via the well-known URL: /.well-known/openid-configuration. This is a common way for OpenID applications to retrieve all of the required information to operate. If the well-known endpoint is not present then you will need to fill out the next three fields instead.

Authorization endpoint Required

The URL in which authorization is done. This is where the user logs in. Required if the discover endpoints field is off/false.

Token endpoint Required

The URL which CleanSpeak trades the authorization code for a token and some security is done to prevent spoofing/hacking. Required if the discover endpoints field is off/false.

Userinfo endpoint Required

The URL which CleanSpeak uses the token to get information about the user (in this case their email and optionally roles) Required if the discover endpoints field is off/false.

Button text Required

The text to display on the login button

Button image optional

The image to display on the login button

Logout URL optional

A URL for CleanSpeak to redirect to after logout.

This is useful if you ever want to log out of your provider as well. You can set this to the providers logout URL and be logged out of everything that way.

Scope Required

The scope is a part of the request that specifies what permissions are required for this application to be successful. We allow you to customize this in case the provider does not provide the email when the email scope is provided. In that case you will need to figure out what scope is required to retrieve the users email as the email is how we figure out which user to log in. (The user must already exist in CleanSpeak!)

Override roles

The override roles allows CleanSpeak to overwrite the roles that were previously on the user with ones from the issuer on login. This requires that the userinfo responds with a roles field that is an array of strings. Any roles that are not explicitly on the list below will be ignored.

Allowed roles:

  • admin - Super User

  • approve_all - Permits the user to use approve all in moderation

  • audit_viewer - Permits the user to view the audit log

  • filter - Permits the user to view the filter

  • filter_manager - Permits the user to alter the filter

  • moderator - Permits the user to moderate

  • moderator_manager - Permits the user to moderate escalated content

  • user_admin - Permits the user to manage the users

  • webhook_manager - Permits the user to manage webhooks (Available since 3.27.0)