Add oauth docs #847

bcbogdan · 2024-09-17T13:41:36Z

General TODO

Code Samples/Instructions @porcellus

Access token validation instructions
Override access token
Override id token
Override granted scopes
create client API Response shape
Generate access token request shape
Custom UI requirements
Exchange oauth2 access token for supertokens session token

netlify · 2024-09-17T13:41:54Z

✅ Deploy Preview for admiring-bhabha-7b1be9 ready!

Name	Link
🔨 Latest commit	`e507130`
🔍 Latest deploy log	https://app.netlify.com/sites/admiring-bhabha-7b1be9/deploys/66fba6852be96c0008a71d05
😎 Deploy Preview	https://deploy-preview-847--admiring-bhabha-7b1be9.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

v2/oauth/introduction.mdx

rishabhpoddar · 2024-09-21T06:40:23Z

v2/oauth/reuse-website-login.mdx

+import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs"
+
+
+# Reuse website login for desktop and mobile apps


Not sure how this page is helpful. The flow for mobile / desktop is very different compared to web apps from the point of view of which lib to use, how to use that lib etc. Once again, we will have to find example tutorial for mobile / desktop apps and link to those, and then add additional comments explaining to users how that tutorial would change in the context of supertokens.

I think we should expand this and provide more concrete guidance on how to achieve this, but the main point of this (i.e.: you are re-using web sign-in for mobile) is correct.

rishabhpoddar · 2024-09-21T06:41:54Z

v2/oauth/multiple-frontends-with-a-single-backend.mdx

+        // You will have to initialize the OAuth2Client recipe
+        // for each of your previously created clients 
+        OAuth2Client.init({
+          clientId: '<CLIENT_ID>',


users will have multiple clients, so they need to be added here in an array?

This will have to be updated for the current version types, I think we still had a single clientId/secret pair when @bcbogdan was writing it.

I dont think this is resolved. It still has just one client id and secret.

maybe you were on a previous version. It's an array with a providerConfigs option

v2/oauth/multiple-frontends-with-a-single-backend.mdx

rishabhpoddar · 2024-09-21T06:44:09Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+</TabItem>
+
+</BackendSDKTabs>
+


missing step of initing the oauthprovider recipe in the oauth provider frontend application.

I think you can extract the part of setting up the OAuth provider as its own page. So after the Introduction section, you can have a page (before the use cases section) that says "Setting up OAuth provider" which talks about initing oauthprovider on the backend and frontend of the auth server, and talking about that there. So that the use cases only focus on the clients and dont have to talk about oauth provider setup again and again.

One more missing part here is that there is no custom UI docs for how to setup an oauth provider with a custom UI instead of using our pre built ui

rishabhpoddar · 2024-09-26T06:32:00Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+    "authorize_url": "^{form_apiDomain}/^{form_apiBasePath}/oauth/auth",
+    "token_fetch_url": "^{form_apiDomain}/^{form_apiBasePath}/oauth/token"


^{form_apiBasePath} already adds a /, so you need to do "^{form_apiDomain}/^{form_apiBasePath}oauth/auth

rishabhpoddar · 2024-09-26T06:32:40Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+</BackendSDKTabs>
+
+
+###  Configure the Authorization Service Frontend 


for pre built UI, you also have to tell users to add the prebuiltui component in case of react being used.

rishabhpoddar · 2024-09-26T06:38:12Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+
+In your `frontend` applications you will have to add a login action that will direct the user to the authentication page.
+
+The user should first be redirected to the `backend` authentication endpoint that was defined during the previous step.


Its a bit unclear, which url exactly?

rishabhpoddar · 2024-09-26T06:38:48Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+You can use the [AuthLib](https://docs.authlib.org/) library.
+Just follow these [instructions](https://docs.authlib.org/en/latest/client/oauth2.html) and implement it in your `backend`.
+
+</TabItem>


need to add content for other languages as well

rishabhpoddar · 2024-09-26T06:39:50Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+</OAuthBackendTabs>
+
+
+## 5. Update the login flow in your frontend applications


Does this step correctly apply to all the languages mentioned for the previous step?

rishabhpoddar · 2024-09-26T06:44:11Z

v2/oauth/reuse-website-login.mdx

+Just follow [the instructions](https://commerce.nearform.com/open-source/react-native-app-auth/docs/usage/config) setup your application. 
+The configuration parameters can be determined based on the response that we received on **step 2**, when we created the **OAuth2 Client**.
+
+- `issuer` corresponds to the endpoint of the **Authorization Service** `^{form_apiDomain}`


i think the issuer that we use is apidomain + apibasepath. Please confirm with @porcellus

rishabhpoddar · 2024-09-26T06:46:18Z

v2/oauth/reuse-website-login.mdx

+In each of your individual `applications` you will have to setup up logic for handling the **OAuth 2.0** authentication flow.
+We recommend using a generic **OICD** or **OAuth** library in order to do this.
+
+<OAuthMobileTabs>


for mobile flows, we also need to mention to have a prompt=login query param added to the authorization url during redirection. You will have to see how to do this for each of the mobile app docs.

rishabhpoddar · 2024-09-26T06:47:16Z

v2/src/components/tabs/OAuthMobileTabs.tsx

+import React from "react";
+let Tabs = require("@theme/Tabs").default;
+
+export default function OAuthMobileTabs(props: any) {


We already have a component to render the mobile code tabs. Please reuse that.

I don't think I can use that. It's a subtabs component. I've updated the oauth tabs to match the options that we expose in those subtabs

rishabhpoddar · 2024-09-26T06:49:29Z

v2/oauth/multiple-frontends-with-a-single-backend.mdx

+OAuth2Provider.init()
+```
+
+3. Update the **Session** recipe initialization to use `header` authentication.


this is not needed to do in the authorization server frontend. This step is needed in the application frontend

rishabhpoddar · 2024-09-26T06:55:26Z

v2/oauth/multiple-frontends-with-a-single-backend.mdx

+In your `frontend` applications you will have to add a login action that will direct the user to the authentication page.
+
+The user should first be redirected to the `backend` login endpoint.
+There the `backend` will redirect the user to the actual [**Authorization Service**](/docs/oauth/introduction#authorization-service) login UI.
+After the user has logged in they will be redirected to the `backend` callback URL.
+Then the authentication session will be created and the `backend` will send it to the user agent as a cookie.


You should first mention that you need to setup supertokens session in the frontend application here, and you can do that by following https://supertokens.com/docs/session/quick-setup/frontend.

Then talk about setting it to header based auth, and say why we need to do it - cause each of these frontends will be third party domains to the backend, and third party cookies are not allowed by browsers like safari.

Then we need to talk about using an oauth lib for the framework and setting the various values in that.

Then finally, when the oauth login is done, we can tell users to call some API (which one - need to have the curl command) which will exchange the oauth tokens for a supertokens session?

rishabhpoddar · 2024-09-26T06:58:14Z

v2/oauth/introduction.mdx

+The **OAuth2 recipes** are available only when using the **SuperTokens Managed Service**. This feature is not included in the **Self-Hosted** version.
+
+Also, the feature at the moment is supported, on the backend, just by the following **SDKs**:
+- `supertokens-node`
+- All our frontend SDKs
+
+Additionally, our **OAuth2** implementation does not support magic links based login flows right now.


Suggested change

The **OAuth2 recipes** are available only when using the **SuperTokens Managed Service**. This feature is not included in the **Self-Hosted** version.

Also, the feature at the moment is supported, on the backend, just by the following **SDKs**:

- `supertokens-node`

- All our frontend SDKs

Additionally, our **OAuth2** implementation does not support magic links based login flows right now.

There are a few limitations to the OAuth recipe:

- It's only available for the **SuperTokens Managed Service**. This feature is not included in the **Self-Hosted** version.

- Only `supertokens-node` backend SDK supports it as of yet. So if you are using our golang or python SDK, you will have to wait, or else you could switch to using our node SDK.

- We do not support magic link based login, however, you can switch to email / SMS OTP instead which offers the same level of security.

rishabhpoddar · 2024-09-26T06:59:42Z

v2/oauth/introduction.mdx

+:::info
+
+This token is different from the **SuperTokens Session Access Token**.
+The latter is used in the **OAuth 2.0** authentication flows when you set the `authMode: 'header'` option in the `Session` recipe.


Suggested change

The latter is used in the **OAuth 2.0** authentication flows when you set the `authMode: 'header'` option in the `Session` recipe.

The latter is used in the **OAuth 2.0** authentication flows to maintain a session between the authorization frontend and the authorization backend server.

rishabhpoddar · 2024-09-26T06:59:56Z

v2/oauth/introduction.mdx

+:::info
+
+This token is different from the **SuperTokens Session Refresh Token**.
+The latter is used in the **OAuth 2.0** authentication flows when you set the `authMode: 'header'` option in the `Session` recipe.


Suggested change

The latter is used in the **OAuth 2.0** authentication flows when you set the `authMode: 'header'` option in the `Session` recipe.

The latter is used in the **OAuth 2.0** authentication flows to maintain a session between the authorization frontend and the authorization backend server.

rishabhpoddar · 2024-09-26T07:01:18Z

v2/oauth/introduction.mdx

+
+<img src="/img/oauth/authorization-code-flow.png" alt="Authorization Code Grant"/>
+
+This flow is best suited for **web applications** where the [**Client**](/#client) can securely store a client secret (for example in the application's backend).


But if we use with PKCE, then there is no need for a client secret. So this can be a bit misleading.

All security guidance on PKCE explicitly state that it is not intended to replace the client-secret, so that's something we should take care to not suggest.

rishabhpoddar · 2024-09-26T07:04:56Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+# You will have to run this for each one of your applications
+# Adjust the client_name and redirect_uri based on that
+curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
+  -H "Content-Type: application/json" \


missing API key. Please see how other snippets to curl have the API key. Our component auto adds the api key if the user is logged into their dashboard

rishabhpoddar · 2024-09-26T07:10:56Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+</TabItem>
+
+</BackendSDKTabs>
+


So this would apply mainly to the use case of multiple frontends with common backend, right?

rishabhpoddar · 2024-09-26T07:15:26Z

v2/oauth/multiple-frontends-with-separate-backends.mdx

+1. Add the import statement for the recipe.
+
+```typescript 
+import OAuth2Provider from "supertokens-node/recipe/oauth2provider";
+```
+
+2. Update the list of recipes with the new initialization step.
+
+```tsx
+OAuth2Provider.init()
+```


normally we show the full supertokens.init here and highlight the important parts. FOr some people it can get confusing where to do OAuth2Provider.init() if they do not really understand the recipe thing we have and just copy / paste docs blindly

If we show the entire init page it might get confusing for them since we can't really know what recipes they already have initialized. Also if they don't understand where recipe init happens then we can't expect them to follow the OAuth2 session guides.

rishabhpoddar · 2024-09-26T07:16:07Z

v2/oauth/machine-to-machine-authentication.mdx

+Just keep in mind to generate a new one when it expires.
+
+The service that will receive the request which includes the **OAuth2 Access Token** will have to verify it.
+To see a detailed example of how to do this please check our [separate guide](/docs/oauth/customizations/verfiy-tokens).


rishabhpoddar · 2024-09-26T07:17:22Z

v2/oauth/multiple-frontends-with-a-single-backend.mdx

+import AppInfoForm from "/src/components/appInfoForm"
+import TabItem from '@theme/TabItem';
+
+# Multiple Frontend Domains Using a Single Backend


The title here and the title in the sidebar are not consistent. Please make sure consistency for all pages

rishabhpoddar · 2024-09-26T07:18:13Z

v2/oauth/multiple-frontends-with-a-single-backend.mdx

+        // You will have to initialize the OAuth2Client recipe
+        // for each of your previously created clients 
+        OAuth2Client.init({
+          clientId: '<CLIENT_ID>',


I dont think this is resolved. It still has just one client id and secret.

rishabhpoddar · 2024-09-26T07:19:47Z

v2/oauth/create-an-authentication-provider.mdx

+title: Create an authentication provider
+hide_title: true
+---
+


is this page relevant? Cause its not in the sidebar

Add oauth docs

9308ff6

bcbogdan force-pushed the feat/oauth branch from 9cb4848 to 9308ff6 Compare September 17, 2024 15:30

Update the scopes section

c9127b5

rishabhpoddar requested changes Sep 21, 2024

View reviewed changes

bcbogdan added 2 commits September 24, 2024 13:38

Code review changes

625df2f

Add improvements and new pages

febfb13

rishabhpoddar requested changes Sep 26, 2024

View reviewed changes

rishabhpoddar reviewed Sep 26, 2024

View reviewed changes

rishabhpoddar requested changes Sep 26, 2024

View reviewed changes

bcbogdan force-pushed the feat/oauth branch 8 times, most recently from 0ddede6 to 36b67a3 Compare September 30, 2024 12:41

Add more corrections

6aa257b

bcbogdan force-pushed the feat/oauth branch from 36b67a3 to 6aa257b Compare September 30, 2024 14:49

bcbogdan added 2 commits October 1, 2024 10:14

Change the old microservices auth to private access token authentication

f9dbf43

Merge branch 'master' into feat/oauth

e507130

		import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs"


		# Reuse website login for desktop and mobile apps

		"authorize_url": "^{form_apiDomain}/^{form_apiBasePath}/oauth/auth",
		"token_fetch_url": "^{form_apiDomain}/^{form_apiBasePath}/oauth/token"

		</BackendSDKTabs>


		### Configure the Authorization Service Frontend


		In your `frontend` applications you will have to add a login action that will direct the user to the authentication page.

		The user should first be redirected to the `backend` authentication endpoint that was defined during the previous step.

		</OAuthBackendTabs>


		## 5. Update the login flow in your frontend applications

	The latter is used in the OAuth 2.0 authentication flows when you set the `authMode: 'header'` option in the `Session` recipe.
	The latter is used in the OAuth 2.0 authentication flows to maintain a session between the authorization frontend and the authorization backend server.


		<img src="/img/oauth/authorization-code-flow.png" alt="Authorization Code Grant"/>

		This flow is best suited for web applications where the [Client](/#client) can securely store a client secret (for example in the application's backend).

		</TabItem>

		</BackendSDKTabs>

		</TabItem>

		</BackendSDKTabs>

Add oauth docs #847

Are you sure you want to change the base?

Add oauth docs #847

Conversation

bcbogdan commented Sep 17, 2024 • edited Loading

General TODO

Code Samples/Instructions @porcellus

netlify bot commented Sep 17, 2024 • edited Loading

✅ Deploy Preview for admiring-bhabha-7b1be9 ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bcbogdan commented Sep 17, 2024 •

edited

Loading

netlify bot commented Sep 17, 2024 •

edited

Loading