From 1ee0d8228ea6597281f385e4585961fa3c9ac9ab Mon Sep 17 00:00:00 2001 From: Seltyk Date: Thu, 20 Jul 2023 11:46:33 -0400 Subject: [PATCH 1/3] Clarify OAuth flow documentation - add note about AUGUR_DEV envvar and localhost - remove Augur View and docs terminology disparity - fix "acquired" typo Signed-off-by: Seltyk --- docs/source/login.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/source/login.rst b/docs/source/login.rst index 92ab6914a8..bfe25b18ac 100644 --- a/docs/source/login.rst +++ b/docs/source/login.rst @@ -20,8 +20,9 @@ Once you have registered an account, follow the below steps to create a new Clie 4. In the create application form, fill out the application name and redirect URL - The redirect URL is relative to the user-agent (IE: the user's browser), and **must** be accessible to the user-agent. - If you are testing an application locally, you may use ``http://127.0.0.1/`` as the host for the redirect URL. The authorization server will *not* prevent redirection if the redirect url is unreachable. + - In this case, it would be beneficial to run Augur with the ``AUGUR_DEV`` environment variable set. This will disable SSL requirements for authorization, allowing ``localhost`` clients to use the OAuth flow. Execute Augur with ``(nohup env AUGUR_DEV=1 augur backend start &)`` for this. -Once the application has been created, note the Client ID and API Key, as you will need them for application authentication requests. +Once the application has been created, note the Application ID and Client Secret, as you will need them for application authentication requests. Authorization Flow -------------------- @@ -34,7 +35,7 @@ Initial Request The authorization flow is initiated when a user clicks a link or button which redirects the user-agent (browser) to the authorization server. This request URL must be of the following format:: https://augur.example.com/user/authorize? - client_id=[your app client ID] + client_id=[your application ID] &response_type="code" &state=[optional value that you define] @@ -65,7 +66,7 @@ The Client Application must make the following request in order to facilitate th code: [the temporary authorization code] grand_type: "code" headers: - Authorization: Client [your app API Key] + Authorization: Client [your client secret] The authorization server will respond with the following on success: @@ -99,7 +100,7 @@ The application may also attempt automatic reauthorization using the previously refresh_token: [the previously provided refresh token] grand_type: "refresh_token" headers: - Authorization: Client [your app API Key] + Authorization: Client [your client secret] The authorization server will respond with the following on success: @@ -120,8 +121,8 @@ See the rest API documentation for more specific details about these login endpo Making Authenticated Requests ------------------------------ -Once the User Session Token has been aqcuired, authenticated requests must be made using both the Client Application API Key and the Bearer Token. Authentication credentials must be provided in the ``Authorization`` header as such:: +Once the User Session Token has been acquired, authenticated requests must be made using both the Client Secret and the Bearer Token. Authentication credentials must be provided in the ``Authorization`` header as such:: - Authorization: Client [API Key], Bearer [User Session Token] + Authorization: Client [Client Secret], Bearer [User Session Token] -**Please note that both the Client API Key and the User Sesson Token must be included in the Authorization header for authenticated requests** \ No newline at end of file +**Please note that both the Client Secret and the User Sesson Token must be included in the Authorization header for authenticated requests** From 506f501b4345fe1312f552acd7337776150c529f Mon Sep 17 00:00:00 2001 From: Seltyk Date: Tue, 25 Jul 2023 10:40:41 -0400 Subject: [PATCH 2/3] Remove AUGUR_DEV comment, add Nginx/Apache Signed-off-by: Seltyk --- docs/source/login.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/source/login.rst b/docs/source/login.rst index bfe25b18ac..b0f0a84504 100644 --- a/docs/source/login.rst +++ b/docs/source/login.rst @@ -6,6 +6,10 @@ Augur implements the Oauth 2.0 specification, and each Augur instance is capable Prerequisites -------------- +If your Augur instance is running behind Nginx or Apache, make sure this parameter (or its Apache equivalent) is set in your ``sites-enabled`` configuration:: + + proxy_set_header X-Forwarded-Proto $scheme; + Registering a user account on the desired Augur instance is a requirement for creating a Client Application. The developer of the application must follow the below steps: 1. Navigate to the home page of the desired Augur instance. @@ -18,9 +22,8 @@ Once you have registered an account, follow the below steps to create a new Clie 2. Click "Profile". 3. Click "Applications" 4. In the create application form, fill out the application name and redirect URL - - The redirect URL is relative to the user-agent (IE: the user's browser), and **must** be accessible to the user-agent. - - If you are testing an application locally, you may use ``http://127.0.0.1/`` as the host for the redirect URL. The authorization server will *not* prevent redirection if the redirect url is unreachable. - - In this case, it would be beneficial to run Augur with the ``AUGUR_DEV`` environment variable set. This will disable SSL requirements for authorization, allowing ``localhost`` clients to use the OAuth flow. Execute Augur with ``(nohup env AUGUR_DEV=1 augur backend start &)`` for this. + - The redirect URL is relative to the user-agent (i.e. the user's browser), and **must** be accessible to the user-agent. + - If you are testing an application locally, you may use ``http://127.0.0.1/`` or ``http://localho.st`` as the host for the redirect URL. The authorization server will *not* prevent redirection if the redirect url is unreachable. Once the application has been created, note the Application ID and Client Secret, as you will need them for application authentication requests. From 5035c4b645d61452300e7323d6e41fdf6d2fcf64 Mon Sep 17 00:00:00 2001 From: Seltyk Date: Mon, 31 Jul 2023 11:34:54 -0400 Subject: [PATCH 3/3] Fix lethal typo in OAuth flow: "grant" has no D. Signed-off-by: Seltyk --- docs/source/login.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/login.rst b/docs/source/login.rst index b0f0a84504..f549751186 100644 --- a/docs/source/login.rst +++ b/docs/source/login.rst @@ -67,7 +67,7 @@ The Client Application must make the following request in order to facilitate th URL: https://augur.example.com/api/unstable/user/session/generate arguments: code: [the temporary authorization code] - grand_type: "code" + grant_type: "code" headers: Authorization: Client [your client secret] @@ -101,7 +101,7 @@ The application may also attempt automatic reauthorization using the previously URL: https://augur.example.com/api/unstable/user/session/refresh arguments: refresh_token: [the previously provided refresh token] - grand_type: "refresh_token" + grant_type: "refresh_token" headers: Authorization: Client [your client secret]