asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: update auth docs + add new storefront guides (#9020)

Browse Source 
* docs: update auth docs + add new storefront guides

* lint content

* fix vale error

* add callback response schema

* Update www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx

Co-authored-by: Stevche Radevski <sradevski@live.com>

* Update www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx

Co-authored-by: Stevche Radevski <sradevski@live.com>

* Update www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx

Co-authored-by: Stevche Radevski <sradevski@live.com>

* address PR comments

* replace google -> github

* better explanation for refresh token

---------

Co-authored-by: Stevche Radevski <sradevski@live.com>
This commit is contained in:
Shahed Nasser
2024-09-06 15:26:10 +03:00
committed by GitHub
co-authored by Stevche Radevski
parent cf3c25addf
commit a28c911c24
29 changed files with 1476 additions and 315 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/auth/auth-providers/_google/page.mdx
-186
View File
@@ -1,186 +0,0 @@
import { Table } from "docs-ui"
export const metadata = {
title: `Google Auth Module Provider`,
}
# {metadata.title}
In this document, you’ll learn about the Google auth module provider and how to install and use it in the Auth Module.
## Features
The Google auth module provider handles authenticating users with their Google accounts.
By integrating the Google auth provider, you provide your users and customers with the ability to login with their Google account.
---
## Install the Google Auth Module Provider
<Note type="check">
- [Create a project in Google Cloud.](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
- [Create authorization credentials](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred).
- Set the Redirect Uri of your Oauth Client ID to `{medusa_url}/auth/{actor_type}/google/callback`, where:
- `{medusa_url}` is the URL of your Medusa backend.
- `{actor_type}` is the actor type that the Google auth provider can authenticate. For example, `customer`.
</Note>
To install the Google auth module provider, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/auth-google
```
Next, add the module to the array of providers passed to the Auth Module:
```js title="medusa-config.js"
import { Modules } from "@medusajs/utils"
// ...
const modules = {
// ...
[Modules.AUTH]: {
resolve: "@medusajs/auth",
options: {
providers: [
{
resolve: "@medusajs/auth-google",
id: "google",
options: {
clientID: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
callbackURL: process.env.GOOGLE_CALLBACK_URL,
successRedirectUrl:
process.env.GOOGLE_SUCCESS_REDIRECT_URL,
},
},
],
},
},
}
```
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
GOOGLE_CLIENT_ID=<YOUR_GOOGLE_CLIENT_ID>
GOOGLE_CLIENT_SECRET=<YOUR_GOOGLE_CLIENT_SECRET>
GOOGLE_CALLBACK_URL=<YOUR_GOOGLE_CALLBACK_URL>
GOOGLE_SUCCESS_REDIRECT_URL=<YOUR_GOOGLE_SUCCESS_REDIRECT_URL>
```
### Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Configuration</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`clientID`
</Table.Cell>
<Table.Cell>
A string indicating the [Google API Client ID](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`clientSecret`
</Table.Cell>
<Table.Cell>
A string indicating the [Google Client Secret](https://support.google.com/cloud/answer/6158849?hl=en#zippy=%2Cstep-create-a-new-client-secret).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`callbackURL`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your app after the user completes their authentication in Google.
The Medusa application provides the API route `/auth/[scope]/google/callback` that you can use, where `[scope]` is the scope this config belongs to.
For example, `/auth/store/google/callback`.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`successRedirectUrl`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your app after the authentication has been successful.
If not provided, the Medusa application's callback route just returns a JSON with the JWT token of the auth identity.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
{/* TODO add how to implement authentication flow with google */}
www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx
+1 -2
View File
@@ -8,8 +8,6 @@ export const metadata = {
In this document, you’ll learn about the Emailpass auth module provider and how to install and use it in the Auth Module.
## Features
Using the Emailpass auth module provider, you allow users to register and login with an email and password.
---
@@ -31,6 +29,7 @@ const modules = {
resolve: "@medusajs/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/auth-emailpass",
id: "emailpass",
www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx
+152
View File
@@ -0,0 +1,152 @@
import { Table, Prerequisites } from "docs-ui"
export const metadata = {
title: `GitHub Auth Module Provider`,
}
# {metadata.title}
In this document, you’ll learn about the GitHub Auth Module Provider and how to install and use it in the Auth Module.
The Github Auth Module Provider handles authenticating users with their GitHub account.
<Note title="Tip">
Learn about the authentication flow in [this guide](../../authentication-route/page.mdx).
</Note>
---
## Install the Github Auth Module Provider
<Prerequisites
items={[
{
text: "Register GitHub App. When setting the Callback URL, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.",
link: "https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app"
},
{
text: "Retrieve the client ID and client secret of your GitHub App",
link: "https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api?apiVersion=2022-11-28#using-basic-authentication"
}
]}
/>
To install the GitHub auth module provider, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/auth-github@preview
```
Next, add the module to the array of providers passed to the Auth Module:
```js title="medusa-config.js"
import { Modules } from "@medusajs/utils"
// ...
const modules = {
// ...
[Modules.AUTH]: {
resolve: "@medusajs/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/auth-github",
id: "github",
options: {
clientId: process.env.GITHUB_CLIENT_ID,
clientSecret: process.env.GITHUB_CLIENT_SECRET,
callbackUrl: process.env.GITHUB_CALLBACK_URL,
},
},
],
},
},
}
```
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```plain
GITHUB_CLIENT_ID=<YOUR_GITHUB_CLIENT_ID>
GITHUB_CLIENT_SECRET=<YOUR_GITHUB_CLIENT_SECRET>
GITHUB_CALLBACK_URL=<YOUR_GITHUB_CALLBACK_URL>
```
### Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Configuration</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell className="w-1/5">Required</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`clientId`
</Table.Cell>
<Table.Cell>
A string indicating the client ID of your GitHub app.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`clientSecret`
</Table.Cell>
<Table.Cell>
A string indicating the client secret of your GitHub app.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`callbackUrl`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your frontend after the user completes their authentication in GitHub.
At this URL, the frontend will receive a `code` query parameter. It then sends that `code` query parameter to the Medusa application's `/auth/{actor_type}/github/callback` route.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Examples
- [How to implement third-party / social login in the storefront.](../../../../storefront-development/customers/third-party-login/page.mdx).
www/apps/resources/app/commerce-modules/auth/auth-providers/google/page.mdx
+152
View File
@@ -0,0 +1,152 @@
import { Table, Prerequisites } from "docs-ui"
export const metadata = {
title: `Google Auth Module Provider`,
}
# {metadata.title}
In this document, you’ll learn about the Google Auth Module Provider and how to install and use it in the Auth Module.
The Google Auth Module Provider handles authenticating users with their Google account.
<Note title="Tip">
Learn about the authentication flow in [this guide](../../authentication-route/page.mdx).
</Note>
---
## Install the Google Auth Module Provider
<Prerequisites
items={[
{
text: "Create a project in Google Cloud.",
link: "https://cloud.google.com/resource-manager/docs/creating-managing-projects"
},
{
text: "Create authorization credentials. When setting the Redirect Uri, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.",
link: "https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred"
}
]}
/>
To install the Google auth module provider, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/auth-google@preview
```
Next, add the module to the array of providers passed to the Auth Module:
```js title="medusa-config.js"
import { Modules } from "@medusajs/utils"
// ...
const modules = {
// ...
[Modules.AUTH]: {
resolve: "@medusajs/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/auth-google",
id: "google",
options: {
clientId: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
callbackUrl: process.env.GOOGLE_CALLBACK_URL,
},
},
],
},
},
}
```
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```plain
GOOGLE_CLIENT_ID=<YOUR_GOOGLE_CLIENT_ID>
GOOGLE_CLIENT_SECRET=<YOUR_GOOGLE_CLIENT_SECRET>
GOOGLE_CALLBACK_URL=<YOUR_GOOGLE_CALLBACK_URL>
```
### Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Configuration</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell className="w-1/5">Required</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`clientId`
</Table.Cell>
<Table.Cell>
A string indicating the [Google API Client ID](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`clientSecret`
</Table.Cell>
<Table.Cell>
A string indicating the [Google Client Secret](https://support.google.com/cloud/answer/6158849?hl=en#zippy=%2Cstep-create-a-new-client-secret).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`callbackUrl`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your frontend after the user completes their authentication in Google.
At this URL, the frontend will receive a `code` query parameter. It then sends that `code` query parameter to the Medusa application's `/auth/{actor_type}/google/callback` route.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Examples
- [How to implement Google social login in the storefront.](../../../../storefront-development/customers/third-party-login/page.mdx).
www/apps/resources/app/commerce-modules/auth/auth-providers/page.mdx
+19 -4
View File
@@ -1,3 +1,5 @@
import { CardList } from "docs-ui"
export const metadata = {
title: `Auth Providers`,
}
@@ -12,11 +14,24 @@ An auth module provider handles authenticating customers and users, either using
For example, the EmailPass Auth Module Provider authenticates a user using their email and password, whereas the Google Auth Module Provider authenticates users using their Google account.
<Note type="soon">
### Auth Providers List
Support for the Google Auth Module Provider is coming soon.
</Note>
<CardList
items={[
{
title: "Emailpass",
href: "/commerce-modules/auth/auth-providers/emailpass"
},
{
title: "Google",
href: "/commerce-modules/auth/auth-providers/google"
},
{
title: "GitHub",
href: "/commerce-modules/auth/auth-providers/github"
},
]}
/>
---