|
1 | 1 | ## discourse-oauth2-basic |
2 | 2 |
|
3 | | -This plugin allows you to use a basic OAuth2 provider as authentication for |
4 | | -Discourse. It should work with many providers, with the caveat that they |
5 | | -must provide a JSON endpoint for retrieving information about the user |
6 | | -you are logging in. |
7 | | - |
8 | | -This is mainly useful for people who are using login providers that aren't |
9 | | -very popular. If you want to use Google, Facebook or Twitter, those are |
10 | | -included out of the box and you don't need this plugin. You can also |
11 | | -look for other login providers in our [Github Repo](https://github.com/discourse). |
12 | | - |
13 | | -## Usage |
14 | | - |
15 | | -## Part 1: Basic Configuration |
16 | | - |
17 | | -First, set up your Discourse application remotely on your OAuth2 provider. |
18 | | -It will require a **Redirect URI** which should be: |
19 | | - |
20 | | -`http://DISCOURSE_HOST/auth/oauth2_basic/callback` |
21 | | - |
22 | | -Replace `DISCOURSE_HOST` with the appropriate value, and make sure you are |
23 | | -using `https` if enabled. The OAuth2 provider should supply you with a |
24 | | -client ID and secret, as well as a couple of URLs. |
25 | | - |
26 | | -Visit your **Admin** > **Settings** > **OAuth2 Login** and fill in the basic |
27 | | -configuration for the OAuth2 provider: |
28 | | - |
29 | | -- `oauth2_enabled` - check this off to enable the feature |
30 | | - |
31 | | -- `oauth2_client_id` - the client ID from your provider |
32 | | - |
33 | | -- `oauth2_client_secret` - the client secret from your provider |
34 | | - |
35 | | -- `oauth2_authorize_url` - your provider's authorization URL |
36 | | - |
37 | | -- `oauth2_token_url` - your provider's token URL. |
38 | | - |
39 | | -If you can't figure out the values for the above settings, check the |
40 | | -developer documentation from your provider or contact their customer |
41 | | -support. |
42 | | - |
43 | | -## Part 2: Configuring the JSON User Endpoint |
44 | | - |
45 | | -Discourse is now capable of receiving an authorization token from your |
46 | | -OAuth2 provider. Unfortunately, Discourse requires more information to |
47 | | -be able to complete the authentication. |
48 | | - |
49 | | -We require an API endpoint that can be contacted to retrieve information |
50 | | -about the user based on the token. |
51 | | - |
52 | | -For example, the OAuth2 provider [SoundCloud provides such a URL](https://developers.soundcloud.com/docs/api/reference#me). |
53 | | -If you have an OAuth2 token for SoundCloud, you can make a GET request |
54 | | -to `https://api.soundcloud.com/me?oauth_token=A_VALID_TOKEN` and |
55 | | -will get back a JSON object containing information on the user. |
56 | | - |
57 | | -To configure this on Discourse, we need to set the value of the |
58 | | -`oauth2_user_json_url` setting. In this case, we'll input the value of: |
59 | | - |
60 | | -``` |
61 | | -https://api.soundcloud.com/me?oauth_token=:token |
62 | | -``` |
63 | | - |
64 | | -The part with `:token` tells Discourse that it needs to replace that value |
65 | | -with the authorization token it received when the authentication completed. |
66 | | -Discourse will also add the `Authorization: Bearer` HTTP header with the |
67 | | -token in case your API uses that instead. |
68 | | - |
69 | | -There is one last step to complete. We need to tell Discourse what |
70 | | -attributes are available in the JSON it received. Here's a sample |
71 | | -response from SoundCloud: |
72 | | - |
73 | | -```json |
74 | | -{ |
75 | | - "id": 3207, |
76 | | - "permalink": "jwagener", |
77 | | - "username": "Johannes Wagener", |
78 | | - "uri": "https://api.soundcloud.com/users/3207", |
79 | | - "permalink_url": "http://soundcloud.com/jwagener", |
80 | | - "avatar_url": "http://i1.sndcdn.com/avatars-000001552142-pbw8yd-large.jpg?142a848", |
81 | | - "country": "Germany", |
82 | | - "full_name": "Johannes Wagener", |
83 | | - "city": "Berlin" |
84 | | -} |
85 | | -``` |
86 | | - |
87 | | -The `oauth2_json_user_id_path`, `oauth2_json_username_path`, `oauth2_json_name_path` and |
88 | | -`oauth2_json_email_path` variables should be set to point to the appropriate attributes |
89 | | -in the JSON. |
90 | | - |
91 | | -The only mandatory attribute is _id_ - we need that so when the user logs on in the future |
92 | | -that we can pull up the correct account. The others are great if available -- they will |
93 | | -make the signup process faster for the user as they will be pre-populated in the form. |
94 | | - |
95 | | -Here's how I configured the JSON path settings: |
96 | | - |
97 | | -``` |
98 | | - oauth2_json_user_id_path: 'id' |
99 | | - oauth2_json_username_path: 'permalink' |
100 | | - oauth2_json_name_path: 'full_name' |
101 | | -``` |
102 | | - |
103 | | -I used `permalink` because it seems more similar to what Discourse expects for a username |
104 | | -than the username in their JSON. Notice I omitted the email path: SoundCloud do not |
105 | | -provide an email so the user will have to provide and verify this when they sign up |
106 | | -the first time on Discourse. |
107 | | - |
108 | | -If the properties you want from your JSON object are nested, you can use periods. |
109 | | -So for example if the API returned a different structure like this: |
110 | | - |
111 | | -```json |
112 | | -{ |
113 | | - "user": { |
114 | | - "id": 1234, |
115 | | - "email": { |
116 | | - |
117 | | - } |
118 | | - } |
119 | | -} |
120 | | -``` |
121 | | - |
122 | | -You could use `user.id` for the `oauth2_json_user_id_path` and `user.email.address` for `oauth2_json_email_path`. |
123 | | - |
124 | | -## Part 3: Test it with Google OAuth 2.0 Server |
125 | | - |
126 | | -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. |
127 | | - |
128 | | -- While creating it choose "Web application" as "Application type". |
129 | | -- Add `http://localhost:3000` in "Authorized JavaScript origins" and `http://localhost:3000/auth/oauth2_basic/callback` in "Authorized redirect URIs" fields. |
130 | | -- Then add following site settings in your admin panel. |
131 | | - |
132 | | -```json |
133 | | -{ |
134 | | - "oauth2_enabled": true, |
135 | | - "oauth2_client_id": "YOUR_PROJECT_CLIENT_ID", |
136 | | - "oauth2_client_secret": "YOUR_PROJECT_CLIENT_SECRET", |
137 | | - "oauth2_authorize_url": "https://accounts.google.com/o/oauth2/auth", |
138 | | - "oauth2_token_url": "https://www.googleapis.com/oauth2/v3/token", |
139 | | - "oauth2_user_json_url": "https://www.googleapis.com/userinfo/v2/me", |
140 | | - "oauth2_json_user_id_path": "id", |
141 | | - "oauth2_json_user_name_path": "name", |
142 | | - "oauth2_json_user_email_path": "email", |
143 | | - "oauth2_json_user_avatar_path": "picture", |
144 | | - "oauth2_email_verified": true, |
145 | | - "oauth2_scope": "https://www.googleapis.com/auth/userinfo.email" |
146 | | -} |
147 | | -``` |
148 | | - |
149 | | -That's it! You can check it now in your browser. |
150 | | - |
151 | | -Good luck setting up custom OAuth2 on your Discourse! |
152 | | - |
153 | | -### Issues |
154 | | - |
155 | | -Please use [this topic on meta](https://meta.discourse.org/t/oauth2-basic-support/33879) to discuss |
156 | | -issues with the plugin, including bugs and feature requests. |
157 | | - |
158 | | -### How to run tests |
159 | | - |
160 | | -Make sure the plugin has been installed, then from the discourse directory run: |
161 | | - |
162 | | -``` |
163 | | -LOAD_PLUGINS=1 bundle exec rspec plugins/discourse-oauth2-basic/spec/plugin_spec.rb |
164 | | -``` |
165 | | - |
166 | | -### License |
167 | | - |
168 | | -MIT |
| 3 | +This plugin has now been bundled into Discourse core. See: https://meta.discourse.org/t/bundling-more-popular-plugins-with-discourse-core/373574 |
0 commit comments