# Discourse OpenID Connect (OIDC) **URL:** https://meta.discourse.org/t/discourse-openid-connect-oidc/103632 **Category:** Plugin **Tags:** official, openid-connect, auth-plugins, included-in-core **Created:** [December 6, 2018, 4:08pm UTC](https://meta.discourse.org/t/discourse-openid-connect-oidc/103632 "2018-12-06T16:08:20Z") **Posts on this page:** 1 **Showing post:** 1
### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse) #### Post date: [December 6, 2018, 4:08pm UTC](https://meta.discourse.org/t/discourse-openid-connect-oidc/103632/1 "2018-12-06T16:08:21Z")
| | | | | --- | --- | --- | | :discourse2: | **Summary** | **Discourse OpenID Connect** allows an OpenID Connect provider to be used as an authentication provider for Discourse. | | 📖 | **Install Guide** | **This plugin is bundled with Discourse core**. There is no need to install the plugin separately. | > [@](#): > > :discourse2: As this is an #official plugin maintained by the Discourse team, #Contribute > Bug, #Contribute > UX, and #Contribute > Feature requests can be made in the respective categories here on Meta, and tagged with the appropriate plugin tag. Support is offered in #Support > SSO . Click on a link below to get one started. 👍 > > [❓ **Support**](https://meta.discourse.org/new-topic?category_id=24&tags=openid-connect "Ask for support on configuring and using Discourse OpenID Connect") [🐛 **Bug**](https://meta.discourse.org/new-topic?category_id=1&tags=openid-connect "A bug report means something is broken, preventing normal/typical use of the plugin") [👀 **UX**](https://meta.discourse.org/new-topic?category_id=9&tags=openid-connect "Discussion about the user interface of Discourse OpenID Connect, and how features are presented (including language and UI elements)") [💡 **Feature**](https://meta.discourse.org/new-topic?category_id=2&tags=openid-connect "Discussion about how existing Discourse OpenID Connect features can be improved or enhanced, and how proposed new features could work") ### Features The plugin aims to provide a minimal implementation of [the specification](https://openid.net/specs/openid-connect-basic-1_0.html). Specifically, it supports the “Authorization Code Flow”. To get started, follow [the plugin installation instructions](https://meta.discourse.org/t/install-plugins-in-discourse/19157), or contact your hosting provider. Our [oauth2-basic](https://meta.discourse.org/t/oauth2-basic-support/33879) plugin can be used for connecting to some openid-connect providers (OpenID Connect is based on OAuth2). However, this plugin should require far less manual configuration, and can make use of the JWT “ID Token” if a JSON API is not available. Configuration is automatically performed using an [OpenID Connect Discovery Document](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). According to the specification, this should be located at `/.well-known/openid-configuration`, but Discourse supports any path to allow for non-compliant implementations (e.g. Azure B2C). The discovery document is cached for 10 minutes, to improve performance on high-traffic sites. If the discovery document includes a `userinfo_endpoint` parameter, then the plugin will use that to collect user metadata. If not, the plugin will extract metadata from the `id_token` (A JWT) supplied by the token endpoint. The plugin DOES NOT verify the authenticity of the JWT signature, as this would significantly increase complexity. This decision is supported by [the specification](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation): > If the ID Token is received via direct communication between the Client and the Token Endpoint (which it is in this flow), the TLS server validation MAY be used to validate the issuer in place of checking the token signature. For identity providers which support secret-less authorization using the [“Authorization Code Flow with Proof Key for Code Exchange”](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce), PKCE should be enabled, and the `client_secret` configuration can be omitted. ### Configuration #### Basic Configuration Options - **`openid_connect_enabled:`** Enable OpenID Connect authentication - **`openid_connect_discovery_document`** : OpenID Connect discovery document URL. Normally located at `https://your.domain/.well-known/openid-configuration` - **`openid_connect_client_id`** : OpenID Connect client ID - **`openid_connect_client_secret`** : OpenID Connect client secret - **`openid connect rp initiated logout`** : Redirect the user to end\_session\_endpoint after logout. Must be supported by your identity provider and included in the discovery document. - **`openid connect rp initiated logout redirect`** : (optional) The post\_logout\_redirect\_uri which will be passed to the logout endpoint. If provided, it must be registered with the identity provider. - **`openid_connect_authorize_scope`** : The scopes sent to the authorize endpoint. This must include ‘openid’ - **`openid_connect_use_pkce`** : Enable Proof Key for Code Exchange (PKCE) for OpenID Connect authentication. - **`openid_connect_verbose_logging`** : Log detailed openid-connect authentication information to `/logs`. Keep this disabled during normal use. #### Advanced Configuration Options - **`openid_connect_token_scope`** : The scopes sent when requesting the token endpoint. The official specification does not require this. - **`openid_connect_error_redirects`** : If the callback error\_reason contains the first parameter, the user will be redirected to the URL in the second parameter. Used for unusual implementations that send errors in response to user input (e.g. Azure B2C) - **`openid_connect_allow_association_change`** : Allow users to disconnect and reconnect their Discourse accounts from the OpenID Connect provider - **`openid_connect_groups_claim`** : The name of the claim in the OIDC response\[1\] that contains the user’s groups as an array of strings. Leave blank to disable group syncing. See [Group sync](#group-sync) below. - **`openid_connect_user_field_mappings`** : mappings of OIDC claims\[2\] which will be stored in Discourse User Fields. User fields are identified by their numeric ID, which can be found in the URL when editing them via the admin panel. ### Group sync The plugin can automatically sync group memberships from your OpenID Connect provider to Discourse groups. On each login, the plugin will read the configured claim from the OIDC token and update the user’s group memberships accordingly. To enable group sync: 1. Configure your identity provider to return an array of groups in one of the claims. This must be an array of strings. 2. Set **`openid_connect_groups_claim`** to the name of the claim in the OIDC token that contains the user’s groups (e.g. `cognito:groups`). Once set, this will start to synchronise the information to Discourse’s “Associated Groups” system. 3. Find the Discourse Group you’d like to link up. Go to “Settings” → “Membership” → “Automatic”, and then choose the Associated Groups to link up. This dropdown list is populated by information from the identity provider, so at least one group member must have logged in for an option to appear. ![image](https://global.discourse-cdn.com/meta/original/4X/8/5/6/8563d51d15b37f23bd600cf4e735b7a3b09ed7e7.png) #### Example setup Here we will set up the openid-connect plugin to connect to Google’s OpenID Connect provider. This replicates functionality that already exists in the core of Discourse, but it serves as an accessible example. 1. Head to [OpenID Connect  |  Sign in with Google  |  Google for Developers](https://developers.google.com/identity/protocols/OpenIDConnect) and follow the instructions to obtain OAuth Credentials. 2. On the same page, follow the instructions to add a redirect URI. This should be `https:///auth/oidc/callback` ( **without** a trailing slash) 3. Go to your Discourse site settings and search for “openid\_connect” 4. You’re done. The “Login with OpenID Connect” button will now log in using Google 🎉. These same steps can be applied to other providers, with very minimal changes. #### Debugging In addition to the `verbose_logging` setting described above, you can access data about OIDC associations using the data-explorer plugin: ```sql SELECT user_id, provider_name, provider_uid FROM user_associated_accounts WHERE provider_name = 'oidc' ``` Or on the rails console: ```ruby User.find_by_username("david").user_associated_accounts.where(provider_name: 'oidc') ``` #### Provider Specific Notes Please feel free to update this if you find any provider-specific quirks relating to this integration: > **Entra ID (formerly Azure AD)** > > Add the `email` scope, and make sure you’re using the version 2 endpoint configuration document. For example > > ```plaintext > https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration > > ``` > > > [@andy.czerwonka](#): > > > > - Make sure you use v2.0 of the configuration endpoint as per the notes above. The default **v1.0 endpoint does not support email or profile scope**. > > - If there are issues with the client secret, try generating a new one. We had some issues, but after generating a couple it seemed just fine. > > - Make sure you turn on _“Sign in and read user profile”_ as a _“Delegated Permission”_ in Azure AD when creating the entry for your site. > > - Make sure you add the correct callback, which is ‘[https://your-site/auth/oidc/callback](https://your-site/auth/oidc/callback)’ > **Azure B2C** > > The discovery document URL details can be found here: [Web sign in with OpenID Connect - Azure AD B2C | Microsoft Learn](https://docs.microsoft.com/en-us/azure/active-directory-b2c/active-directory-b2c-reference-oidc) > > > [@](#): > > > > For example, the metadata document for the `b2c_1_sign_in` user flow in `fabrikamb2c.onmicrosoft.com` is located at: > > > > `https://fabrikamb2c.b2clogin.com/fabrikamb2c.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=b2c_1_sign_in` > > To make emails work: > > > [@Umer\_Nawab](#): > > > > To get email in claims, you will have to use custom policies. To achieve that, I used the policies starter pack mentioned here: > > > > [Tutorial - Create user flows and custom policies - Azure Active Directory B2C | Microsoft Learn](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#test-the-custom-policy) > > > > After implementing the steps mentioned in above article, email claim started appearing when user signed up but when an existing user signed in, the email claim was missing from token. Then I had to make some changes in the custom policy xml file by following the steps mentioned in this post: > > > > [https://stackoverflow.com/questions/59669666/email-claims-not-populated-with-custom-policies-in-azure-b2c](https://stackoverflow.com/questions/59669666/email-claims-not-populated-with-custom-policies-in-azure-b2c) > > > > After these changes, email claim is now appearing when the user signs up and also when user signs in. > **Yahoo** > > 1. Head to [https://developer.yahoo.com/apps](https://developer.yahoo.com/apps) and create a new app > > 2. Enter the Application Name, and set the callback domain to your forum domain (e.g. `meta.discourse.org`) > > 3. Under API Permissions, choose **Profiles: Read/Write Public and Private**. This is the only way I know of to obtain the user email address > > 4. Save the app > > 5. In the Discourse OIDC settings, set the discovery document to > > 6. Enter the client ID and secret from Yahoo > > 7. Enable the OIDC plugin > **AWS Cognito** > > 1. Go to Cognito and select or create a new user pool. > 2. Define an app in App clients. > 3. Leave everything to default, but change Auth Flows Configuration to only select ALLOW\_REFRESH\_TOKEN\_AUTH. > 4. Go to app client settings and select the new app. > 5. Change the callback URL to [https://yoursite.example.com/auth/oidc/callback](https://yoursite.example.com/auth/oidc/callback). > 6. Only check the Authorization code grant flow among “Allowed OAuth Flows”. > 7. Check all scopes needed (I have all checked). > **Okta** > > 1. Configure Discourse with your Okta app client ID and secret > > 2. Set the discovery document URL to > > 3. In Discourse, set the `openid connect authorize scope` to `openid email` > :discourse2: Hosted by us? This plugin is available on our Business and Enterprise plans. [OAuth 2.0 & OpenID Connect Support | Discourse - Civilized Discussion](https://www.discourse.org/plugins/oauth.html) > 🗒 Need to automate user sign-ups? See [Auto-provisioning user accounts when SSO is enabled](https://meta.discourse.org/t/auto-provisioning-user-accounts-when-sso-is-enabled/399917) * * * 1. token or userinfo payload 2. from token or userinfo payload > Last edited by @Moin 2026-05-25T19:17:47Z > > > **Check document** > > > > Perform check on document: --- _[View the full topic](https://meta.discourse.org/t/discourse-openid-connect-oidc/103632)._