From 1ae72c1ca2d68543951c62f4bbadeb9901526fed Mon Sep 17 00:00:00 2001 From: Jarek Radosz Date: Sun, 13 Jul 2025 15:39:03 +0200 Subject: [PATCH 1/2] DEV: Deprecate the plugin --- README.md | 167 +----------------------------------------------------- 1 file changed, 1 insertion(+), 166 deletions(-) diff --git a/README.md b/README.md index ee477dd..a3ede04 100644 --- a/README.md +++ b/README.md @@ -1,168 +1,3 @@ ## discourse-oauth2-basic -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). - -## Usage - -## Part 1: Basic Configuration - -First, set up your Discourse application remotely on your OAuth2 provider. -It will require a **Redirect URI** which should 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. - -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. - -## Part 2: 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: - -``` -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. -Discourse will also add the `Authorization: Bearer` HTTP header with the -token in case your API uses that instead. - -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: - -``` - 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`. - -## Part 3: Test it with Google OAuth 2.0 Server - -To test this plugin in your local dev environment you can use Google OAuth 2.0 Server. Follow [this guide](https://support.google.com/cloud/answer/6158849?hl=en) to create new OAuth client id & secret. - -- While creating it choose "Web application" as "Application type". -- Add `http://localhost:3000` in "Authorized JavaScript origins" and `http://localhost:3000/auth/oauth2_basic/callback` in "Authorized redirect URIs" fields. -- Then add following site settings in your admin panel. - -```json -{ - "oauth2_enabled": true, - "oauth2_client_id": "YOUR_PROJECT_CLIENT_ID", - "oauth2_client_secret": "YOUR_PROJECT_CLIENT_SECRET", - "oauth2_authorize_url": "https://accounts.google.com/o/oauth2/auth", - "oauth2_token_url": "https://www.googleapis.com/oauth2/v3/token", - "oauth2_user_json_url": "https://www.googleapis.com/userinfo/v2/me", - "oauth2_json_user_id_path": "id", - "oauth2_json_user_name_path": "name", - "oauth2_json_user_email_path": "email", - "oauth2_json_user_avatar_path": "picture", - "oauth2_email_verified": true, - "oauth2_scope": "https://www.googleapis.com/auth/userinfo.email" -} -``` - -That's it! You can check it now in your browser. - -Good luck setting up custom OAuth2 on your Discourse! - -### Issues - -Please use [this topic on meta](https://meta.discourse.org/t/oauth2-basic-support/33879) to discuss -issues with the plugin, including bugs and feature requests. - -### How to run tests - -Make sure the plugin has been installed, then from the discourse directory run: - -``` -LOAD_PLUGINS=1 bundle exec rspec plugins/discourse-oauth2-basic/spec/plugin_spec.rb -``` - -### License - -MIT +This plugin has now been bundled into Discourse core. See: https://meta.discourse.org/t/bundling-more-popular-plugins-with-discourse-core/373574 From 5d384be454d805e74ed83b37eb51631794c2e682 Mon Sep 17 00:00:00 2001 From: Jarek Radosz Date: Mon, 14 Jul 2025 10:49:02 +0200 Subject: [PATCH 2/2] Update README.md --- README.md | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 169 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a3ede04..a1875ab 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,171 @@ ## discourse-oauth2-basic -This plugin has now been bundled into Discourse core. See: https://meta.discourse.org/t/bundling-more-popular-plugins-with-discourse-core/373574 +> [!IMPORTANT] +> This plugin has now been bundled into Discourse core. See: https://meta.discourse.org/t/bundling-more-popular-plugins-with-discourse-core/373574 + +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). + +## Usage + +## Part 1: Basic Configuration + +First, set up your Discourse application remotely on your OAuth2 provider. +It will require a **Redirect URI** which should 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. + +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. + +## Part 2: 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: + +``` +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. +Discourse will also add the `Authorization: Bearer` HTTP header with the +token in case your API uses that instead. + +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: + +``` + 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`. + +## Part 3: Test it with Google OAuth 2.0 Server + +To test this plugin in your local dev environment you can use Google OAuth 2.0 Server. Follow [this guide](https://support.google.com/cloud/answer/6158849?hl=en) to create new OAuth client id & secret. + +- While creating it choose "Web application" as "Application type". +- Add `http://localhost:3000` in "Authorized JavaScript origins" and `http://localhost:3000/auth/oauth2_basic/callback` in "Authorized redirect URIs" fields. +- Then add following site settings in your admin panel. + +```json +{ + "oauth2_enabled": true, + "oauth2_client_id": "YOUR_PROJECT_CLIENT_ID", + "oauth2_client_secret": "YOUR_PROJECT_CLIENT_SECRET", + "oauth2_authorize_url": "https://accounts.google.com/o/oauth2/auth", + "oauth2_token_url": "https://www.googleapis.com/oauth2/v3/token", + "oauth2_user_json_url": "https://www.googleapis.com/userinfo/v2/me", + "oauth2_json_user_id_path": "id", + "oauth2_json_user_name_path": "name", + "oauth2_json_user_email_path": "email", + "oauth2_json_user_avatar_path": "picture", + "oauth2_email_verified": true, + "oauth2_scope": "https://www.googleapis.com/auth/userinfo.email" +} +``` + +That's it! You can check it now in your browser. + +Good luck setting up custom OAuth2 on your Discourse! + +### Issues + +Please use [this topic on meta](https://meta.discourse.org/t/oauth2-basic-support/33879) to discuss +issues with the plugin, including bugs and feature requests. + +### How to run tests + +Make sure the plugin has been installed, then from the discourse directory run: + +``` +LOAD_PLUGINS=1 bundle exec rspec plugins/discourse-oauth2-basic/spec/plugin_spec.rb +``` + +### License + +MIT