### Author:  [@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. |
| :open_book: | **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. :+1:
>
> [:question: **Support**](https://meta.discourse.org/new-topic?category_id=24&tags=oauth2 "Ask for support on configuring and using Discourse OAuth2 Basic") [:bug: **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") [:eyes: **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)") [:bulb: **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`
> :information_source: 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.
> :information_source: 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.
> :warning: 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)
> :spiral_notepad: 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:
---
### Author:  [@qlands](https://meta.discourse.org/u/qlands)
#### Post date: [September 1, 2022, 10:03pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/290 "2022-09-01T22:03:00Z")
Hello,
We are trying to integrate Discourse with our application using OAuth2 Basic but we are getting the following error in the logs:
Note: We are using NGROK as we are debugging the connection.
```plaintext
OAuth2 Debugging: request POST https://formshare.ngrok.io/oauth2/token
Headers: {"User-Agent"=>"Faraday v1.9.3", "Content-Type"=>"application/x-www-form-urlencoded", "Authorization"=>"Basic S2k2SFZtTVpuSTFHUExiRXVlWVJDNENiOkNvb1k0anlQemt3dWNRV21Sa2FWOVNnbHZLbjJFT3cxc3BIMmtMck9yY21vNDM4Tg=="}
Body: {"client_id"=>"Ki6HVmMZnI1GPLbEueYRC4Cb", "client_secret"=>"...some_secret_...", "grant_type"=>"authorization_code", "code"=>"5pPCrsp0pZ84373MNaHh2cuskfc8AlbfmdwMBFIVW4n4z9aX", :redirect_uri=>"https://community.formshare.org/auth/oauth2_basic/callback"}
------------------
OAuth2 Debugging: response status 200
From POST https://formshare.ngrok.io/oauth2/token
Headers: {"content-length"=>"108", "content-type"=>"text/html; charset=UTF-8", "date"=>"Thu, 01 Sep 2022 21:42:08 GMT", "ngrok-trace-id"=>"79cdc3f1c3eae5e37a30796aebbf9bd6", "server"=>"gunicorn"}
Body: {"token_type": "Bearer", "access_token": "p0FVuwjSXL1ZINEklMAVqUlpZxSll1SgnbpE8YWP4C", "expires_in": 864000}
-----------------------------------
(oauth2_basic) Authentication failure! invalid_credentials: OAuth2::Error, {"token_type": "Bearer", "access_token": "p0FVuwjSXL1ZINEklMAVqUlpZxSll1SgnbpE8YWP4C", "expires_in": 864000}
```
We left the params “oauth2 callback user id path” and " oauth2 callback user info paths" empty.
Any idea is appreciated.
---
### Author:  [@Sikamikanico](https://meta.discourse.org/u/Sikamikanico)
#### Post date: [September 30, 2022, 3:19pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/291 "2022-09-30T15:19:37Z")
Can I use this to authenticate with Microsofts XBL service?
I presume the logic would be similar to this?
>
---
### Author:  [@MendelYev](https://meta.discourse.org/u/MendelYev)
#### Post date: [January 1, 2023, 9:47pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/297 "2023-01-01T21:47:53Z")
Hi everyone. I try to configure this plugin with our internal Oauth2 server with authorization code flow.
When a user click “Connect with Oauth”, the /authorize endpoint works and a code is return to the callback. But then Discourse shows a generic 500 error " Oops. The software powering this discussion forum encountered an unexpected problem" and the /token endpoint is not accessed.
**The error log says so** :
OAuth2::ConnectionError (FinalDestination: all resolved IPs were disallowed) lib/final\_destination/ssrf\_detector.rb:74:in `lookup_and_filter_ips' lib/final_destination/http.rb:13:in `connect’ lib/midd
| hostname | discourse-app |
| --- | --- |
| process\_id | 653 |
| application\_version | 702f27e6ee10ac257f5fee3f331d05f5fa5d7a45 |
| HTTP\_HOST | \*\*\*\*\* |
| REQUEST\_METHOD | GET |
| HTTP\_USER\_AGENT | Mozilla/5.0 (X11; Linux x86\_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36 |
| HTTP\_ACCEPT | text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,_/_;q=0.8,application/signed-exchange;v=b3;q=0.9 |
| HTTP\_REFERER | \*\*\*\*\* |
| HTTP\_X\_FORWARDED\_FOR | \*\*\*\*\* |
| HTTP\_X\_REAL\_IP | \*\*\*\*\* |
| time | 10:25 pm |
| params | |
| code | def50200babf84f7376f99fefa34369d876566b6bc0a341d8fba431999a72549ac06f6aad01df6fa43061707c525ba5d725ad |
| state | 20139e0a134a5972566d4ddb6f7f9092a2cddb9e5216973a |
As I understand there is an issue with some IP address? Currently the Oauth2 server is hosted on my dev environment (localhost) and the authorize and token endpoints are configured accordingly. Is it a problem?
---
### Author:  [@MendelYev](https://meta.discourse.org/u/MendelYev)
#### Post date: [January 3, 2023, 12:00am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/298 "2023-01-03T00:00:15Z")
Found the problem:
1. For some reason the /token endpoint was never called. After filling a maximum of options in admin parameters related to oauth the endpoint was called without answer
2. I forgot that it was the Discourse server that would call the /token endpoint and not the webclient. Therefore, the server could not reach my localhost Oauth2 server. Putting our Oauth2 server behinf a domain solved the problem
Now, I can connect existing users but don’t undersand how to sign in new users through this plugin.
If the user sign in with oauth, it gets an error saying he has no active account on Discours server. Which is normal since it’s a new user.
Is there a dedicated callback to sign in user instead of login? Or a specific parameter to set to allow account creation?
---
### Author:  [@MendelYev](https://meta.discourse.org/u/MendelYev)
#### Post date: [January 10, 2023, 5:42pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/299 "2023-01-10T17:42:23Z")
My company oauth server was generating a /profile JSON response with a little typo in one field. Everything was okay after fixing the typo.
But I have to say that Discourse logs can be very misleading! Nothing was wrong with the callback.
---
### Author:  [@mjr4684](https://meta.discourse.org/u/mjr4684)
#### Post date: [February 1, 2023, 6:27pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/300 "2023-02-01T18:27:44Z")
Hi team,
I’m having an issue with pulling the ID I need for my user JSON request from the authorization response. In reading the documentation it appears that the account ID is sent in a nested array:
```plaintext
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":1800,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"permissions":[
{
"accountId":123,
"availableScopes":["contacts_view", "contacts_me",
"contacts_edit", "finances_view", "events_view"]
}
]
}
```
I’ve tried setting the oauth2 callback user id path to `permissions[0].accountId` but my uid value is always blank. Unfortunately, calls to pull the user json require this accountId in the JSON url.
---
### Author:  [@mjr4684](https://meta.discourse.org/u/mjr4684)
#### Post date: [February 2, 2023, 11:41pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/301 "2023-02-02T23:41:18Z")
I was able to get this working by passing permissions.first.accountId, I found that when I passed permissions into a test property the array was already parsed as a Ruby array. Unfortunately, the fields seem to reject the Ruby syntax to call array elements and any attempt to use Javascript syntax would result in a TypeError String to Integer. Luckily Ruby had the syntax above, is this the intended method?
---
### Author:  [@Pietro\_Saccardi\_Spak](https://meta.discourse.org/u/Pietro_Saccardi_Spak)
#### Post date: [March 17, 2023, 6:37pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/302 "2023-03-17T18:37:58Z")
I just got this to work with Authentik OAuth2, however there were some hiccups with the `oauth2 user json url` setting. I used the `user_info` endpoint of Authentik for that (`/application/o/userinfo/`), however I did not know how to map the fields. For anyone looking how to set up Discourse with Authentik’s OAuth2, here’s the summary:
- User id path: `preferred_username`
- Username path: `preferred_username`
- Name path: `name`
- Email path: `email`
- Email verified path: `email_verified`
- Avatar: empty.
I had the following issues:
1. At the beginning, I forgot the trailing slash in the json url `https://DOMAIN/application/o/userinfo/`. This lead to the user info request ([permalink to the source](https://github.com/discourse/discourse-oauth2-basic/blob/1448f05319a0ceb09388946caaac74abb9df12e7/plugin.rb#L231)) to return a 301 HTTP code, which caused the login to fail. I do not know whether the trailing slash should be there by spec, but perhaps it would be good to handle 301 correctly.
2. Debugging this turned out tricky. The `oauth2 debug auth` settings was a lifesaver but… Logster truncates the debug log before actually dumping the meaningful response data. I had to modify manually in the container the log line to
```plaintext
log("user_json_response: #{user_json_response.status} #{user_json_response.headers} #{user_json_response.body}")
```
Perhaps that log line could be updated? I guess it could help other people figure out the json attributes path.
---
### Author:  [@nodomain](https://meta.discourse.org/u/nodomain)
#### Post date: [April 27, 2023, 7:21pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/304 "2023-04-27T19:21:02Z")
I just set up Auth0 with the plugin and found that avatars are not picked up.
These are the relevant settings:
```bash
DISCOURSE_OAUTH2_ENABLED: true
DISCOURSE_OAUTH2_CLIENT_ID: '${DISCOURSE_OAUTH2_CLIENT_ID}'
DISCOURSE_OAUTH2_CLIENT_SECRET: '${DISCOURSE_OAUTH2_CLIENT_SECRET}'
DISCOURSE_OAUTH2_AUTHORIZE_URL: '${DISCOURSE_OAUTH2_ISSUER}/authorize?connection=xxx&login_options=yyy'
DISCOURSE_OAUTH2_TOKEN_URL: '${DISCOURSE_OAUTH2_ISSUER}/oauth/token'
DISCOURSE_OAUTH2_USER_JSON_URL: '${DISCOURSE_OAUTH2_ISSUER}/userinfo'
DISCOURSE_OAUTH2_SCOPE: 'email openid profile'
DISCOURSE_OAUTH2_JSON_USER_ID_PATH: 'sub'
DISCOURSE_OAUTH2_JSON_USERNAME_PATH: 'nickname'
DISCOURSE_OAUTH2_JSON_NAME_PATH: 'name'
DISCOURSE_OAUTH2_JSON_EMAIL_PATH: 'email'
DISCOURSE_OAUTH2_JSON_EMAIL_VERIFIED_PATH: 'email_verified'
DISCOURSE_OAUTH2_JSON_AVATAR_PATH: 'picture'
DISCOURSE_OAUTH2_EMAIL_VERIFIED: true
DISCOURSE_OAUTH2_OVERRIDES_EMAIL: true
DISCOURSE_OAUTH2_ALLOW_ASSOCIATION_CHANGE: false
```
In the debug log I can see that the `picture` element is set in the JSON response, but the user’s avatar does not change, neither for new nor for existing users.
What did I miss?
---
### Author:  [@supermathie](https://meta.discourse.org/u/supermathie)
#### Post date: [May 31, 2023, 7:43pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/305 "2023-05-31T19:43:34Z")
What is the best way to replace the icon on the login button with either another icon or an image?
```css
.btn-social.oauth2_basic:before {
content: url('https://www.contoso.com/path/to/image');
}
.btn-social.oauth2_basic > svg {
display: none;
}
```
feels sufficient but a bit hacky
---
### Author:  [@Headless](https://meta.discourse.org/u/Headless)
#### Post date: [June 13, 2023, 12:42am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/306 "2023-06-13T00:42:08Z")
It seems like the plugin only updates the avatar/username on initial creation of the user, not on everytime they log in.
Is there anyway to fix this and have the plugin update the avatar as well on login/reconnection?
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [June 13, 2023, 8:47am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/307 "2023-06-13T08:47:35Z")
You can use the `auth overrides email`, `auth overrides username` and `auth overrides name` settings to make those things apply on future logins. I’m afraid we don’t currently have a similar setting for avatars, but it would be #pr-welcome
---
### Author:  [@Headless](https://meta.discourse.org/u/Headless)
#### Post date: [June 13, 2023, 9:00am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/308 "2023-06-13T09:00:48Z")
Thank you! I actually found these later on. I forked the repo and added my own versions to get this functioning with Roblox, which included the override for avatars. Which I believe just uses [DiscourseConnect](https://meta.discourse.org/t/13045?silent=true) avatar override so people can’t change it.
One thing I wish though is that roblox does not provide a email on OAuth so I sadly need to have them signup with a email. but thats a non issue for yall haha.
---
### Author:  [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [October 29, 2023, 10:23am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/309 "2023-10-29T10:23:33Z")
A post was split to a new topic: [Twitter login doesn’t work on meta](https://meta.discourse.org/t/twitter-login-doesnt-work-on-meta/283801)
---
### Author:  [@Marshably](https://meta.discourse.org/u/Marshably)
#### Post date: [October 29, 2023, 10:17am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/310 "2023-10-29T10:17:23Z")
Does anyone know if this still works?
---
### Author:  [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [October 29, 2023, 10:21am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/311 "2023-10-29T10:21:46Z")
Yes. I’m confident this plugin works. :+1:
---
### Author:  [@Shivam\_Bhalla1](https://meta.discourse.org/u/Shivam_Bhalla1)
#### Post date: [November 21, 2023, 3:52pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/312 "2023-11-21T15:52:54Z")
Hi, I was able to intergrate this plugin in my discourse [discuss.frontendlead.com](http://discuss.frontendlead.com), I am using teachable oauth [OAuth Quickstart Guide](https://docs.teachable.com/docs/oauth-quickstart-guide)
However, I only want to allow people to be able to successfully register if and only if they have a current paid account on teachable. I would imagine, I need to add custom functionality in the plugin to handle this? I am wondering, can you guys or even I can, introduce another field on the settings called custom code after oauth, which allows developers to perform specific actions after signing up? Or if there are better suggestions, please let me know.
Edit: I forked the repo and got it working here:
>
If someone else using teachable is trying to do the same, my repo would work out of the box, the only thing is if you didn’t buy a course, it will say you need to go to my domain to purchase it. you may want to update that for your own usecase.
---
### Author:  [@simon](https://meta.discourse.org/u/simon)
#### Post date: [November 22, 2023, 2:49am UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/313 "2023-11-22T02:49:01Z")
> [@Shivam\_Bhalla1](#):
>
> I only want to allow people to be able to successfully register if and only if they have a current paid account on teachable.
> [@Shivam\_Bhalla1](#):
>
> Edit: I forked the repo and got it working here:
That’s great!
There’s a similar situation with OAuth2 registration with the Discourse Patreon plugin. When “Login with Patreon” is enabled, it allows anyone with a Patreon account to register on the Discourse site. What site owners generally want is to only allow _their_ supporters to be able to register Discourse accounts. I wonder if details are returned from Patreon that would allow similar logic to be added to Patreon authentication?
---
### Author:  [@jmlord](https://meta.discourse.org/u/jmlord)
#### Post date: [December 8, 2023, 2:53pm UTC](https://meta.discourse.org/t/discourse-oauth2-basic/33879/314 "2023-12-08T14:53:39Z")
I have the exact same error as @qlands above.
My initial plan was to send the profile info in the token. Seeing it did not work, I stripped it down indenting to try the json approach. But it doesn’t even get to the point of calling the JSON file.
The error message is:
```plaintext
(oauth2_basic) Authentication failure! invalid_credentials: OAuth2::Error, {
"access_token":"fa79b6fe0763862f5a8fd8",
"token_type":"Bearer",
"expires_in":3600,
"scope":"profile"
}
```
Do you see anything wrong with the above reply?
Why would the plugin generate an invalid\_credentials error while the OAuth2 server replied a 200 with a token?
[Next page](https://meta.discourse.org/t/discourse-oauth2-basic/33879.md?page=2)