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