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

docs: rename auth user to auth identity (#7400)

Browse Source 
* docs: rename auth user to auth identity

* updated protected routes guide

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

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

* store/me -> store/customers/me

* change scope to type

* remove soon notes

---------

Co-authored-by: Stevche Radevski <sradevski@live.com>
This commit is contained in:
Shahed Nasser
2024-05-29 13:47:11 +03:00
committed by GitHub
parent bbca54efa7
commit 72b57e2ae4
8 changed files with 60 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
www/apps/book/app/advanced-development/api-routes/protected-routes/page.mdx
View File

@@ -13,7 +13,7 @@ A protected route is a route that requires requests to be user-authenticated bef
Medusa applies an authentication guard on the following routes:
- Routes starting with `/admin` require an authenticated admin user.
- Routes starting with `/store/me` require an authenticated customer.
- Routes starting with `/store/customers/me` require an authenticated customer.
<Note>
@@ -25,11 +25,11 @@ Refer to the API Reference for [Admin](https://docs.medusajs.com/api/admin#authe
## Authentication Opt-Out
To disable the authentication guard on custom routes under the `/admin` or `/store/me` path prefixes, export an `AUTHENTICATE` variable in the route file with its value set to `false`.
To disable the authentication guard on custom routes under the `/admin` or `/store/customers/me` path prefixes, export an `AUTHENTICATE` variable in the route file with its value set to `false`.
For example:
```ts title="src/api/store/me/custom/route.ts" highlights={[["15"]]} apiTesting testApiUrl="http://localhost:9000/store/me/custom" testApiMethod="GET"
```ts title="src/api/store/customers/me/custom/route.ts" highlights={[["15"]]} apiTesting testApiUrl="http://localhost:9000/store/customers/me/custom" testApiMethod="GET"
import type {
MedusaRequest,
MedusaResponse,
@@ -47,7 +47,7 @@ export const GET = async (
export const AUTHENTICATE = false
```
Now, any request sent to the `/store/me/custom` API route is allowed, regardless if the customer is authenticated or not.
Now, any request sent to the `/store/customers/me/custom` API route is allowed, regardless if the customer is authenticated or not.
---
@@ -57,7 +57,7 @@ You can access the logged-in customer’s ID in all API routes starting with `/s
For example:
```ts title="src/api/store/me/custom/route.ts" highlights={[["16", "", "Access the logged-in customer's ID."]]}
```ts title="src/api/store/customers/me/custom/route.ts" highlights={[["16", "", "Access the logged-in customer's ID."]]}
import type {
AuthenticatedMedusaRequest,
MedusaResponse,
@@ -118,7 +118,7 @@ In the route handler, you resolve the `UserService`, and then use it to retrieve
## Protect Custom API Routes
To protect custom API Routes that don’t start with `/store/me` or `/admin`, use the `authenticate` middleware imported from `@medusajs/medusa`.
To protect custom API Routes that don’t start with `/store/customers/me` or `/admin`, use the `authenticate` middleware imported from `@medusajs/medusa`.
For example:
@@ -136,13 +136,13 @@ export const config: MiddlewaresConfig = {
{
matcher: "/custom/admin*",
middlewares: [
authenticate("admin", ["session", "bearer", "api-key"]),
authenticate("user", ["session", "bearer", "api-key"]),
],
},
{
matcher: "/custom/customer*",
middlewares: [
authenticate("store", ["session", "bearer"]),
authenticate("customer", ["session", "bearer"]),
],
},
],
@@ -151,8 +151,8 @@ export const config: MiddlewaresConfig = {
The `authenticate` middleware function accepts three parameters:
1. The scope of authentication. Use `admin` for authenticating admin users, and `store` for authenticating customers.
2. An array of the types of authentication methods allowed. Both `admin` and `store` scopes support `session` and `bearer`. The `admin` scope also supports the `api-key` authentication method.
1. The type of user authenticating. Use `user` for authenticating admin users, and `customer` for authenticating customers.
2. An array of the types of authentication methods allowed. Both `user` and `customer` scopes support `session` and `bearer`. The `admin` scope also supports the `api-key` authentication method.
3. An optional object of options having the following properties:
1. `allowUnauthenticated`: (default: `false`) A boolean indicating whether authentication is required. For example, you may have an API route where you want to access the logged-in customer if available, but guest customers can still access it too. In that case, enable the `allowUnauthenticated` option.
2. `allowUnregistered`: (default: `false`) A boolean indicating whether new users can be authenticated.

8
www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
View File

@@ -41,17 +41,17 @@ If the `authenticate` method returns the following object:
```ts
data = {
success: true,
authUser: {
authIdentity: {
// ...
},
}
```
Then, the user is authenticated successfully, and their authentication details are available within the `authUser` object.
Then, the user is authenticated successfully, and their authentication details are available within the `authIdentity` object.
<Note>
Learn more about the `authUser` in [this guide](../persisting-auth-user/page.mdx#what-is-an-authuser).
Learn more about the `authIdentity` in [this guide](../persisting-auth-user/page.mdx#what-is-an-authuser).
</Note>
@@ -101,7 +101,7 @@ If the authentication is successful, the auth provider’s `validateCallback` me
```ts
data = {
success: true,
authUser: {
authIdentity: {
// ...
},
}

4
www/apps/resources/app/commerce-modules/auth/events/_events-table/page.mdx
View File

@@ -17,14 +17,14 @@ import { Table } from "docs-ui"
</Table.Cell>
<Table.Cell>
Triggered when an auth user is deleted.
Triggered when an auth identity is deleted.
</Table.Cell>
<Table.Cell>
```ts noCopy noReport
{
// the ID of the deleted auth user
// the ID of the deleted auth identity
id,
}
```

36
www/apps/resources/app/commerce-modules/auth/examples/page.mdx
View File

@@ -36,7 +36,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const authModuleService: IAuthModuleService =
req.scope.resolve(ModuleRegistrationName.AUTH)
const { success, authUser, location, error } =
const { success, authIdentity, location, error } =
await authModuleService.authenticate("emailpass", {
url: req.url,
headers: req.headers,
@@ -57,7 +57,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const { jwtSecret } =
req.scope.resolve("configModule").projectConfig.http
const token = jwt.sign(authUser, jwtSecret)
const token = jwt.sign(authIdentity, jwtSecret)
res.status(200).json({ token })
}
@@ -77,7 +77,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const authModuleService = await initializeAuthModule()
const url = new URL(request.url)
const { success, authUser, location, error } =
const { success, authIdentity, location, error } =
await authModuleService.authenticate("emailpass", {
url: request.url,
headers: Object.fromEntries(request.headers),
@@ -96,7 +96,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
return
}
const token = jwt.sign(authUser, "supersecret")
const token = jwt.sign(authIdentity, "supersecret")
return NextResponse.json({
token,
@@ -139,7 +139,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const authModuleService: IAuthModuleService =
req.scope.resolve(ModuleRegistrationName.AUTH)
const { success, authUser, error, successRedirectUrl } =
const { success, authIdentity, error, successRedirectUrl } =
await authModuleService.validateCallback("google", {
url: req.url,
headers: req.headers,
@@ -155,7 +155,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const { jwtSecret } =
req.scope.resolve("configModule").projectConfig.http
const token = jwt.sign(authUser, jwtSecret)
const token = jwt.sign(authIdentity, jwtSecret)
if (successRedirectUrl) {
const url = new URL(successRedirectUrl!)
@@ -182,7 +182,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const authModuleService = await initializeAuthModule()
const url = new URL(request.url)
const { success, authUser, location, error } =
const { success, authIdentity, location, error } =
await authModuleService.authenticate("google", {
url: request.url,
headers: Object.fromEntries(request.headers),
@@ -196,7 +196,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
throw new Error(error)
}
const token = jwt.sign(authUser, "supersecret")
const token = jwt.sign(authIdentity, "supersecret")
if (successRedirectUrl) {
const url = new URL(successRedirectUrl!)
@@ -235,13 +235,13 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const authModuleService: IAuthModuleService =
req.scope.resolve(ModuleRegistrationName.AUTH)
const authUser = await authModuleService.create({
const authIdentity = await authModuleService.create({
provider: "emailpass",
entity_id: "user@example.com",
scope: "admin",
})
res.json({ auth_user: authUser })
res.json({ auth_identity: authIdentity })
}
```
@@ -258,14 +258,14 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
export async function POST(request: Request) {
const authModuleService = await initializeAuthModule()
const authUser = await authModuleService.create({
const authIdentity = await authModuleService.create({
provider: "emailpass",
entity_id: "user@example.com",
scope: "admin",
})
return NextResponse.json({
auth_user: authUser,
auth_identity: authIdentity,
})
}
```
@@ -293,7 +293,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
req.scope.resolve(ModuleRegistrationName.AUTH)
res.json({
auth_users: await authModuleService.list(),
auth_identitys: await authModuleService.list(),
})
}
```
@@ -312,7 +312,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const authModuleService = await initializeAuthModule()
return NextResponse.json({
auth_users: await authModuleService.list(),
auth_identities: await authModuleService.list(),
})
}
```
@@ -339,7 +339,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
const authModuleService: IAuthModuleService =
req.scope.resolve(ModuleRegistrationName.AUTH)
const authUser = await authModuleService.update({
const authIdentity = await authModuleService.update({
id: "authusr_123",
provider_metadata: {
test: true,
@@ -347,7 +347,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
})
res.json({
auth_user: authUser,
auth_identity: authIdentity,
})
}
```
@@ -374,7 +374,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
) {
const authModuleService = await initializeAuthModule()
const authUser = await authModuleService.update({
const authIdentity = await authModuleService.update({
id: "authusr_123",
provider_metadata: {
test: true,
@@ -382,7 +382,7 @@ This example uses the [jsonwebtoken NPM package](https://www.npmjs.com/package/j
})
return NextResponse.json({
auth_users: await authModuleService.list(),
auth_identitys: await authModuleService.list(),
})
}
```

2
www/apps/resources/app/commerce-modules/auth/module-options/page.mdx
View File

@@ -195,7 +195,7 @@ Follow [this Google documentation](https://developers.google.com/identity/protoc
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 user.
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>

14
www/apps/resources/app/commerce-modules/auth/page.mdx
View File

@@ -17,7 +17,7 @@ The Auth Module is the `@medusajs/auth` NPM package that provides authentication
With the Auth Module, authenticate users using their credentials.
```ts
const { success, authUser, error } =
const { success, authIdentity, error } =
await authModuleService.authenticate("emailpass", {
url: req.url,
headers: req.headers,
@@ -40,7 +40,7 @@ The Auth Module supports a variety of authentication methods, such as authentica
```ts
// in authentication API route
const { success, authUser, location } =
const { success, authIdentity, location } =
await authModuleService.authenticate("google", {
url: req.url,
headers: req.headers,
@@ -50,13 +50,13 @@ const { success, authUser, location } =
protocol: req.protocol,
} as AuthenticationInput)
if (!authUser && location) {
if (!authIdentity && location) {
res.redirect(location)
return
}
// in callback API route
const { success, authUser } =
const { success, authIdentity } =
await authModuleService.validateCallback("google", {
url: req.url,
headers: req.headers,
@@ -115,7 +115,7 @@ For example:
req.scope.resolve(ModuleRegistrationName.AUTH)
res.json({
authUsers: authModuleService.list(),
authIdentitys: authModuleService.list(),
})
}
```
@@ -134,7 +134,7 @@ For example:
const authModuleService: IAuthModuleService =
container.resolve(ModuleRegistrationName.AUTH)
const authUsers = await authModuleService.list()
const authIdentitys = await authModuleService.list()
}
```
@@ -151,7 +151,7 @@ For example:
context.container.resolve(
ModuleRegistrationName.AUTH
)
const authUsers = await authModuleService.list()
const authIdentitys = await authModuleService.list()
})
```

20
www/apps/resources/app/commerce-modules/auth/persisting-auth-user/page.mdx
View File

@@ -8,24 +8,24 @@ export const metadata = {
# {metadata.title}
In this document, you’ll learn what the `AuthUser` is and how to persist its authentication.
In this document, you’ll learn what the `AuthIdentity` is and how to persist its authentication.
## What is an AuthUser?
## What is an AuthIdentity?
As explained in the [Auth Provider](../auth-providers/page.mdx) guide, when a user or customer is authenticated, you receive an `authUser` object:
As explained in the [Auth Provider](../auth-providers/page.mdx) guide, when a user or customer is authenticated, you receive an `authIdentity` object:
```ts
const { success, authUser } =
const { success, authIdentity } =
await authModuleService.authenticate("emailpass", {
// ...
})
```
The `authUser` object is a record of the `AuthUser` data model. It has details about the authenticated user or customer, such as their ID, email, and other details.
The `authIdentity` object is a record of the `AuthIdentity` data model. It has details about the authenticated user or customer, such as their ID, email, and other details.
<Note>
Learn more about the `AuthUser`'s fields in [this reference](/references/auth/models/AuthUser).
Learn more about the `AuthIdentity`'s fields in [this reference](/references/auth/models/AuthIdentity).
</Note>
@@ -35,12 +35,12 @@ Learn more about the `AuthUser`'s fields in [this reference](/references/auth/mo
While the Auth Module provides the authentication functionality, it doesn’t provide the functionality to persist the authentication, as that depends on your application’s requirements.
For example, the Medusa application’s authentication route signs the `authUser` object into a JSON Web Token (JWT):
For example, the Medusa application’s authentication route signs the `authIdentity` object into a JSON Web Token (JWT):
```ts
const {
success,
authUser,
authIdentity,
} = await service.authenticate(auth_provider, authData)
// ...
@@ -48,11 +48,11 @@ const {
jwtSecret,
} = req.scope.resolve("configModule").projectConfig.http
const token = jwt.sign(authUser, jwtSecret)
const token = jwt.sign(authIdentity, jwtSecret)
```
Then, the token is passed in the header of subsequent requests in the Authorization Bearer header.
An authentication middleware verifies the token and attaches the associated `authUser`'s details to the `auth` property of the request object passed to the subsequent middlewares and route.
An authentication middleware verifies the token and attaches the associated `authIdentity`'s details to the `auth` property of the request object passed to the subsequent middlewares and route.
If the authentication middleware can’t verify the token, the user isn’t authenticated and they’re asked to login again.

16
www/apps/resources/app/commerce-modules/auth/user-creation/page.mdx
View File

@@ -12,11 +12,11 @@ In this document, you’ll learn about the user-creation flow and how to use it
## Auth User Creation in Authentication Flow
In the [Auth Provider](../auth-providers/page.mdx) documentation, you learned about the authentication flows supported by the Auth Module. These flows are used when an `AuthUser` is already available for the specified authentication data, such as email/password credentials.
In the [Auth Provider](../auth-providers/page.mdx) documentation, you learned about the authentication flows supported by the Auth Module. These flows are used when an `AuthIdentity` is already available for the specified authentication data, such as email/password credentials.
However, the `emailpass` and `google` providers support creating an `AuthUser` if none exists. If an email is provided that doesn’t have an `AuthUser` associated with it (checked via its `entity_id` field) for the specified provider (checked via its `provider` field), a new `AuthUser` is created for that email and provider.
However, the `emailpass` and `google` providers support creating an `AuthIdentity` if none exists. If an email is provided that doesn’t have an `AuthIdentity` associated with it (checked via its `entity_id` field) for the specified provider (checked via its `provider` field), a new `AuthIdentity` is created for that email and provider.
![Diagram showcasing the AuthUser creation part of the authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711441638/Medusa%20Resources/auth-user-creation_gmahvl.jpg)
![Diagram showcasing the AuthIdentity creation part of the authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711441638/Medusa%20Resources/auth-user-creation_gmahvl.jpg)
So, by default, your authentication flow supports both sign-in and sign-up flows.
@@ -34,22 +34,22 @@ The User Module provides user and invite management functionalities. However, it
By combining the User and Auth Modules, you can use the Auth Module for authenticating users, and the User Module to manage those users.
So, when a user is authenticated, and you receive the `AuthUser` object, you can use it to create a user if it doesn’t exist:
So, when a user is authenticated, and you receive the `AuthIdentity` object, you can use it to create a user if it doesn’t exist:
```ts
const { success, authUser } =
const { success, authIdentity } =
await authModuleService.authenticate("emailpass", {
// ...
})
// assuming authUser is defined
// assuming authIdentity is defined
const [, count] = await userModuleService.listAndCount({
email: authUser.entity_id,
email: authIdentity.entity_id,
})
if (!count) {
const user = await userModuleService.create({
email: authUser.entity_id,
email: authIdentity.entity_id,
})
}
```