# Discourse OAuth2 Basic **URL:** https://meta.discourse.org/t/discourse-oauth2-basic/33879 **Category:** Plugin **Tags:** official, oauth2, auth-plugins, included-in-core **Created:** [September 29, 2015, 4:27pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879 "2015-09-29T16:27:19Z") **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: [September 29, 2015, 4:27pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/1 "2015-09-29T16:27:19Z")
| | | | | --- | --- | --- | | :discourse2: | **Summary** | **Discourse OAuth2 Basic** supports basic OAuth2 providers, assuming they have a JSON API endpoint where user details can be retrieved by token. | | 📖 | **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=oauth2 "Ask for support on configuring and using Discourse OAuth2 Basic") [🐛  **Bug**](https://meta.discourse.org/new-topic?category_id=1&tags=oauth2 "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=oauth2 "Discussion about the user interface of Discourse AOAuth2 Basic, and how features are presented (including language and UI elements)") [💡  **Feature**](https://meta.discourse.org/new-topic?category_id=2&tags=oauth2 "Discussion about how existing Discourse OAuth2 Basic features can be improved or enhanced, and how proposed new features could work") ### Features This plugin allows you to use a basic OAuth2 provider as authentication for Discourse. It should work with many providers, with the caveat that they must provide a JSON endpoint for retrieving information about the user you are logging in. This is mainly useful for people who are using login providers that aren’t very popular. If you want to use Google, Facebook or Twitter, those are included out of the box and you don’t need this plugin. You can also look for other login providers in our [Github Repo](https://github.com/discourse). ### Configuration #### Basic Configuration 1. First, register your Discourse application with your OAuth2 provider. It will require a **Redirect URI** which will be:     `http://DISCOURSE_HOST/auth/oauth2_basic/callback` > ℹ Replace `DISCOURSE_HOST` with the appropriate value, and make sure you are using `https` if enabled. The OAuth2 provider should supply you with a `client ID` and `secret`, as well as a couple of URLs. 1. Visit your **Admin** → **Settings** → **OAuth2 Login** and fill in the basic configuration for the OAuth2 provider: - `oauth2_enabled` - check this off to enable the feature - `oauth2_client_id` - the client ID from your provider - `oauth2_client_secret` - the client secret from your provider - `oauth2_authorize_url` - your provider’s authorization URL - `oauth2_token_url` - your provider’s token URL. > ℹ If you can’t figure out the values for the above settings, check the developer documentation from your provider or contact their customer support. #### Configuring the JSON User Endpoint Discourse is now capable of receiving an authorization token from your OAuth2 provider. Unfortunately, Discourse requires more information to be able to complete the authentication. We require an API endpoint that can be contacted to retrieve information about the user based on the token. For example, the OAuth2 provider [SoundCloud provides such a URL](https://developers.soundcloud.com/docs/api/reference#me). If you have an OAuth2 token for SoundCloud, you can make a GET request to `https://api.soundcloud.com/me?oauth_token=A_VALID_TOKEN` and will get back a JSON object containing information on the user. To configure this on Discourse, we need to set the value of the `oauth2_user_json_url` setting. In this case, we’ll input the value of: ```plaintext https://api.soundcloud.com/me?oauth_token=:token ``` The part with `:token` tells Discourse that it needs to replace that value with the authorization token it received when the authentication completed. There is one last step to complete. We need to tell Discourse what attributes are available in the JSON it received. Here’s a sample response from SoundCloud: ```json { "id": 3207, "permalink": "jwagener", "username": "Johannes Wagener", "uri": "https://api.soundcloud.com/users/3207", "permalink_url": "http://soundcloud.com/jwagener", "avatar_url": "http://i1.sndcdn.com/avatars-000001552142-pbw8yd-large.jpg?142a848", "country": "Germany", "full_name": "Johannes Wagener", "city": "Berlin" } ``` The `oauth2_json_user_id_path`, `oauth2_json_username_path`, `oauth2_json_name_path` and `oauth2_json_email_path` variables should be set to point to the appropriate attributes in the JSON. The only mandatory attribute is _id_ - we need that so when the user logs on in the future that we can pull up the correct account. The others are great if available – they will make the signup process faster for the user as they will be pre-populated in the form. Here’s how I configured the JSON path settings: ```plaintext oauth2_json_user_id_path: 'id' oauth2_json_username_path: 'permalink' oauth2_json_name_path: 'full_name' ``` I used `permalink` because it seems more similar to what Discourse expects for a username than the username in their JSON. Notice I omitted the email path: SoundCloud do not provide an email so the user will have to provide and verify this when they sign up the first time on Discourse. If the properties you want from your JSON object are nested, you can use periods. So for example if the API returned a different structure like this: ```json { "user": { "id": 1234, "email": { "address": "test@example.com" } } } ``` You could use `user.id` for the `oauth2_json_user_id_path` and `user.email.address` for `oauth2_json_email_path`. If the key itself includes periods, you will need to put double quotes around it, or escape the periods with a backslash. For example, given this JSON: ```json { "example.com/uid": "myuid" } ``` You would specify the path as `example\.com/uid` or `"example.com/uid"` ### Group & User Field Sync - **`oauth2_json_groups_path`** : JSON path which contains the user’s groups as an array of strings. After the first member has logged in, these groups will be available for selection in the ‘associated groups’ section of the Discourse group settings. Leave blank to disable group syncing. - **`oauth2_user_field_mappings`** : mappings of JSON paths 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. > ⚠ If you set `oauth2_json_email_path`, the OAuth2 provider _must_ confirm the user owns that email address. Failure to do this can result in account takeover in Discourse! > :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) > Last edited by @david 2026-05-28T11:12:59Z > > > **Check document** > > > > Perform check on document: --- _[View the full topic](https://meta.discourse.org/t/discourse-oauth2-basic/33879)._