Add oauth docs #847

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

General TODO

OAuth2 flows diagrams
Diagrams for guides
Use the AppInfoForm and CoreInjector in every code snippets that show urls
Add a different code tabs abstraction (other than BackendSDKTabs) that allows more languages
Explain where SuperTokens Tokens are used compared to OAuth2 Tokens
Explain how to use libraries for external session handling
Add section about custom ui
Update create client examples to exclude apiKey

Code Samples/Instructions @porcellus

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

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

Name	Link
🔨 Latest commit	`febfb13`
🔍 Latest deploy log	https://app.netlify.com/sites/admiring-bhabha-7b1be9/deploys/66f43978222d7000084ceb81
😎 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.

rishabhpoddar · 2024-09-21T05:51:34Z

v2/oauth/introduction.mdx

+
+For these specific instances we expose recipes that allow you to complete your setup. 
+
+:::info


Suggested change

:::info

:::caution

rishabhpoddar · 2024-09-21T05:51:55Z

v2/oauth/introduction.mdx

+
+Also, the feature at the moment is supported just by the following **SDKs**:
+- `supertokens-node`
+- `supertokens-auth-react`


Suggested change

- `supertokens-auth-react`

- All of our frontend SDKs

rishabhpoddar · 2024-09-21T05:52:53Z

v2/oauth/introduction.mdx

+The **Resource Owner** is an entity capable of granting access to a protected resource.
+When the resource owner is a person, it is referred to as an **end-user**.


Its still not really clear what this means (at least for me). Maybe give more examples?

We could say that this is usually the end user who is using a browser or a mobile app. It's an important distinction that this is not the app/browser/SPA

rishabhpoddar · 2024-09-21T05:53:25Z

v2/oauth/introduction.mdx

+
+#### Resource Server
+
+The server hosting the protected resources, capable of accepting and responding to protected resource requests using **Access Tokens**.


What is a protected resource? Maybe give more examples?

We could give the example of downloading a file or a chat log.

rishabhpoddar · 2024-09-21T05:56:50Z

v2/oauth/introduction.mdx

+
+#### Access Token
+
+A token issued by the [**Authorization Server**](/#authorization-server), that then gets passed by the [**Client**](/#client) to the [**Resource Server**](/#resource-server) to gain access to protected resources.


Maybe here we should make it clear that with supertokens, there are two types of access tokens:

SuperTokens session access token

OAuth access token

And that in the docs, whenever we say just access token, we mean supertokens session access token, and whenever we say oauth access token its the other one. We should also state what these are here maybe

Same thing goes for refresh token below

Is the SuperTokens session access token actually used in the OAuth recipe flows? Or do users need to use the actual OAuth tokens?

Oauth recipe flows uses oauth access token only. A user's application API can use either supertokens session access token or oauth access token. Other recipes like email verificaiton, totp, user roles etc (all non oauth recipes) use supertokens session access token only.

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.

rishabhpoddar · 2024-09-21T06:42:07Z

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

+        // for each of your previously created clients 
+        OAuth2Client.init({
+          clientId: '<CLIENT_ID>',
+          oidcDiscoveryEndpoint: 'https://<AUTHENTICATION_SERVICE_DOMAIN>/.well-known/openid-configuration'


Suggested change

oidcDiscoveryEndpoint: 'https://<AUTHENTICATION_SERVICE_DOMAIN>/.well-known/openid-configuration'

oidcDiscoveryEndpoint: 'https://<YOUR_API_DOMAIN>/.well-known/openid-configuration'

also, is the path correct?

no, it is: {api_domain}/{base_path/.well-known/openid-configuration

rishabhpoddar · 2024-09-21T06:43:22Z

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

+
+</BackendSDKTabs>
+
+## 3. Initialize the recipe on the Frontend Applications


It needs to be very clear that this goes in the oauth provider frontend.

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add oauth docs #847

Add oauth docs #847

bcbogdan commented Sep 17, 2024 •

edited

Loading

netlify bot commented Sep 17, 2024 •

edited

Loading

rishabhpoddar Sep 21, 2024

bcbogdan Sep 24, 2024

rishabhpoddar Sep 21, 2024

bcbogdan Sep 24, 2024

rishabhpoddar Sep 21, 2024

porcellus Sep 22, 2024

bcbogdan Sep 24, 2024

rishabhpoddar Sep 21, 2024

porcellus Sep 22, 2024

bcbogdan Sep 24, 2024

rishabhpoddar Sep 21, 2024

rishabhpoddar Sep 21, 2024

bcbogdan Sep 23, 2024

rishabhpoddar Sep 23, 2024

bcbogdan Sep 24, 2024

rishabhpoddar Sep 21, 2024

porcellus Sep 22, 2024

rishabhpoddar Sep 21, 2024

porcellus Sep 22, 2024

bcbogdan Sep 25, 2024

rishabhpoddar Sep 21, 2024

rishabhpoddar Sep 21, 2024

porcellus Sep 22, 2024

rishabhpoddar Sep 21, 2024

bcbogdan Sep 25, 2024

rishabhpoddar Sep 21, 2024

rishabhpoddar Sep 21, 2024

rishabhpoddar Sep 21, 2024


		For these specific instances we expose recipes that allow you to complete your setup.

		:::info

		The Resource Owner is an entity capable of granting access to a protected resource.
		When the resource owner is a person, it is referred to as an end-user.


		#### Resource Server

		The server hosting the protected resources, capable of accepting and responding to protected resource requests using Access Tokens.


		#### Access Token

		A token issued by the [Authorization Server](/#authorization-server), that then gets passed by the [Client](/#client) to the [Resource Server](/#resource-server) to gain access to protected resources.

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


		# Reuse website login for desktop and mobile apps

	oidcDiscoveryEndpoint: 'https://<AUTHENTICATION_SERVICE_DOMAIN>/.well-known/openid-configuration'
	oidcDiscoveryEndpoint: 'https://<YOUR_API_DOMAIN>/.well-known/openid-configuration'


		</BackendSDKTabs>

		## 3. Initialize the recipe on the Frontend Applications

		</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

bcbogdan commented Sep 17, 2024 •

edited

Loading

netlify bot commented Sep 17, 2024 •

edited

Loading