From b3f3651857995e2122dc8e061b348bb1b0166fcb Mon Sep 17 00:00:00 2001 From: Selast Lambou Date: Tue, 28 Nov 2023 20:23:09 +0100 Subject: [PATCH] doc(auth): documented the oauth2 --- docs/pages/authentication.mdx | 1 + docs/pages/authentication/_meta.json | 3 +- docs/pages/authentication/oauth2.mdx | 130 ++++++++++++++++++++++++++ packages/medusa-plugin-auth/README.md | 6 +- 4 files changed, 138 insertions(+), 2 deletions(-) create mode 100644 docs/pages/authentication/oauth2.mdx diff --git a/docs/pages/authentication.mdx b/docs/pages/authentication.mdx index b11505bd..ae52e88a 100644 --- a/docs/pages/authentication.mdx +++ b/docs/pages/authentication.mdx @@ -33,6 +33,7 @@ This plugin provides you with the following authentication providers - [Auth0](/authentication/auth0) - [Firebase](/authentication/firebase) - [Azure AD](/authentication/azureoidc) +- [OAuth2](/authentication/oauth2) ### Contribute diff --git a/docs/pages/authentication/_meta.json b/docs/pages/authentication/_meta.json index ceb79302..724eaaa9 100644 --- a/docs/pages/authentication/_meta.json +++ b/docs/pages/authentication/_meta.json @@ -4,5 +4,6 @@ "linkedin": "Linkedin", "auth0": "Auth0", "firebase": "Firebase", - "azureoidc": "Azure AD" + "azureoidc": "Azure AD", + "oauth2": "OAuth2" } \ No newline at end of file diff --git a/docs/pages/authentication/oauth2.mdx b/docs/pages/authentication/oauth2.mdx new file mode 100644 index 00000000..22b7635b --- /dev/null +++ b/docs/pages/authentication/oauth2.mdx @@ -0,0 +1,130 @@ +
+ NPM Version + NPM Version +
+ +### Configuration + +In order to be able to use the **oauth2** authentication provider, you have to add the configuration to your +newly added plugins. To do so here are the steps + + + Configure your **oauth2 developer console** + + + + Go to your `medusa-config.js` + + + + Check that the variables are set with the appropriate values + + ```js + const BACKEND_URL = process.env.BACKEND_URL || "localhost:9000" + const ADMIN_URL = process.env.ADMIN_URL || "localhost:7000" + const STORE_URL = process.env.STORE_URL || "localhost:8000" + + const OAuth2AuthorizationURL = process.env.OAUTH2_CLIENT_ID || "" + const OAuth2TokenURL = process.env.tokenURL || "" + const OAuth2ClientId = process.env.OAUTH2_CLIENT_ID || "" + const OAuth2ClientSecret = process.env.OAUTH2_CLIENT_SECRET || "" + const OAuth2Scope = process.env.OAUTH2_SCOPE || "" + ``` + + Then in your `plugins` collections, if you did not already inserted the plugin, add the following otherwise, you can + just add the `oauth2` options to your auth plugin options + ```js + { + resolve: "medusa-plugin-auth", + /** @type {import('medusa-plugin-auth').AuthOptions} */ + options: { + strict: "all", // or "none" or "store" or "admin" + oauth2: { + authorizationURL: OAuth2AuthorizationURL, + tokenURL: OAuth2TokenURL, + clientID: OAuth2ClientId, + clientSecret: OAuth2ClientSecret, + scope: OAuth2Scope.split(","), + + admin: { + callbackUrl:`${BACKEND_URL}/admin/auth/oauth2/cb`, + failureRedirect: `${ADMIN_URL}/login`, + + // The success redirect can be overriden from the client by adding a query param `?redirectTo=your_url` to the auth url + // This query param will have the priority over this configuration + successRedirect: `${ADMIN_URL}/`, + + // authPath: '/admin/auth/oauth2', + // authCallbackPath: '/admin/auth/oauth2/cb', + // expiresIn: 24 * 60 * 60 * 1000, + // verifyCallback: (container, req, accessToken, refreshToken, profile, strict) => { + // // implement your custom verify callback here if you need it + // } + }, + + store: { + callbackUrl:`${BACKEND_URL}/store/auth/oauth2/cb`, + failureRedirect: `${STORE_URL}/login`, + + // The success redirect can be overriden from the client by adding a query param `?redirectTo=your_url` to the auth url + // This query param will have the priority over this configuration + successRedirect: `${STORE_URL}/`, + + // authPath: '/store/auth/oauth2', + // authCallbackPath: '/store/auth/oauth2/cb', + // expiresIn: 24 * 60 * 60 * 1000, + // verifyCallback: (container, req, accessToken, refreshToken, profile, strict) => { + // // implement your custom verify callback here if you need it + // } + } + } + } + } + ``` + The options that are commented are `optional` and the value that you see are the default values + + + + Update your client to add the authentication action + ```html + + + Sign in with OAuth2 + + ``` + - `medusa_url` correspond to your backend server url (e.g `http://localhost:9000`) + - `authPath` correspond to `authPath` configuration in your plugin (e.g `admin/auth/oauth2`) + + After authentication is successfull, the user will be redirected to the `successRedirect` url with a `?access_token=your_token` query param and a session cookie will be set. Session will automatically be authenticated. The access token is a JWT that can be used with Authorization: Bearer `` header to authenticate requests to the backend instead of using a session cookie. + + +### Default behaviour + +The default `verifyCallback` flow looks as follow (unless the `strict` option is changed to `none` or `store` or `admin` depending on the targeted domain) +- for the `admin` + - if the user trying to authenticate exists + - then we are looking in the metadata to find if the strategy identifier is present in `authProvider`. + - If it is not, the user authentication gets rejected. + - In the case it is present, then the user authentication gets authorized. + - if the user trying to authenticate does not exist, an unauthorized error will be returned +- for the `store` + - if the customer trying to authenticate exists + - then we are looking in the metadata to find if the strategy identifier is present in `authProvider`. + - If none are found, then the customer gets authenticated and can proceed and the metadata gets updated. + - In the case another external authentication method have been used in the past, then an unauthorized + will be returned. + - if the customer trying to authenticate does not exist, a new customer will be created with a randomly generated password and the authentication + flow follow the previous point + +### Request only access token in a JSON response + +If you are using your Medusa application with a SPA or mobile frontend, you can request opt to receive the access token in a JSON response instead of a redirect. + +To do this, you have to add ?returnAccessToken=true query parameter to your authentication call. Your authentication URL will then look like this: `${medusa_url}/${authPath}?returnAccessToken=true` + +The response will look like this: +```json +{ + access_token: "" +} +``` diff --git a/packages/medusa-plugin-auth/README.md b/packages/medusa-plugin-auth/README.md index 54fc30d2..e0d1f3f6 100644 --- a/packages/medusa-plugin-auth/README.md +++ b/packages/medusa-plugin-auth/README.md @@ -62,4 +62,8 @@ First of all, you need to install the plugin as follow `yarn add medusa-plugin-a ### Azure AD OIDC -[Documentation here](https://medusa-plugins.vercel.app/authentication/azureoidc) \ No newline at end of file +[Documentation here](https://medusa-plugins.vercel.app/authentication/azureoidc) + +### OAuth2 + +[Documentation here](https://medusa-plugins.vercel.app/authentication/oauth2) \ No newline at end of file