From 4564a6ab6eaba08c16ef2409abb26de6f04d4eba Mon Sep 17 00:00:00 2001 From: Gunnar Oledal Date: Mon, 9 Nov 2020 13:05:20 +0100 Subject: [PATCH 1/3] Clarifying documentation of custom authentication. Documentation on custom authentication was extremely unclear. Tried to clarify a few aspects. That id is required in the authData object. Also what is client-side vs backend code. Very open to feedback and improvements! --- _includes/js/users.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/_includes/js/users.md b/_includes/js/users.md index 8c64f55bd..dcd385854 100644 --- a/_includes/js/users.md +++ b/_includes/js/users.md @@ -389,7 +389,7 @@ Our library manages the `FB` object for you. The `FB` singleton is synchronized Parse allows you to link your users with [3rd party authentication]({{ site.baseUrl }}/parse-server/guide/#oauth-and-3rd-party-authentication), enabling your users to sign up or log into your application using their existing identities. This is accomplished through [`linkWith`](https://parseplatform.org/Parse-SDK-JS/api/2.9.0/Parse.User.html#linkWith) method by providing authentication data for the service you wish to link to a user in the `authData` field. Once your user is associated with a service, the `authData` for the service will be stored with the user and is retrievable by logging in. -`authData` is a JSON object with keys for each linked service containing the data below. +`authData` is a JSON object with keys for each linked service containing the data below. The `authData` object is required to at least have a key named `id`, which is used to identify the user on subsequent login attempts with linked account data. > `_linkWith` has been deprecated since version 2.9.0, see [_linkWith](https://parseplatform.org/Parse-SDK-JS/api/master/Parse.User.html#_linkWith) @@ -399,7 +399,7 @@ Signing a user up with a linked service and logging them in with that service us ```javascript const myAuthData = { - id: '12345678' + id: '12345678' // required field. Used to uniquely identify the linked account. }; const user = new Parse.User(); await user.linkWith('providerName', { authData: myAuthData }); @@ -450,7 +450,7 @@ To create a link to an un-authenticated user (for example in cloud code), option ```javascript const myAuthData = { - id: xzx5tt123, + id: xzx5tt123, // The id key is required in the authData-object. Otherwise Parse server will throw the Error 252 'This authentication method is unsupported.' access: token } @@ -473,14 +473,15 @@ const loggedIn = await Parse.User.logInWith('CustomAdapter', { authData: myAuthD ### Custom Authentication Module Parse Server supports many [3rd Party Authenications]({{ site.baseUrl }}/parse-server/guide/#oauth-and-3rd-party-authentication). -It is possible to `linkWith` any 3rd Party Authentication by creating a custom authentication module. +It is possible to `linkWith` any 3rd Party Authentication by creating a custom authentication module. A custom authetication module normally consists of a client-side provider object and a back-end authAdapter. The client-side object should implement the [AuthProvider interface](https://github.com/parse-community/Parse-SDK-JS/blob/master/src/interfaces/AuthProvider.js). The backend authAdapter should implement the the functions `validateAuthData` and `validateAppId`, check out this [AuthAdapter example](https://github.com/parse-community/parse-server/blob/master/src/Adapters/Auth/AuthAdapter.js). +When calling the `linkWith` function **without** an `authData` object the client side authenticate-method from the provider object will be called. In the other case the `authData` object will be sent directly to parse server for authentication using the backend module. -[Read more about Auth Provider Documentation](https://github.com/parse-community/Parse-SDK-JS/blob/master/src/interfaces/AuthProvider.js) +Note: The following is a minimal example implementing auth provider client-side and authadapter on the backend. -Note: This is an example, you can handle your own authentication (if you don't have authData), restoreAuthentication and deauthenticate methods. - -A minimal `CustomAuth.js` module: +A minimal `CustomAuth.js` module in the backend: ```javascript +// Don't require or import parse-server in this module. +// See this issue: https://github.com/parse-community/parse-server/issues/6467 function validateAuthData(authData, options) { return Promise.resolve({}) } @@ -517,7 +518,13 @@ app.use('/parse', api); Use the `CustomAuth`: ```javascript const provider = { - authenticate: () => Promise.resolve(), + authenticate: (options) => { + // Some code to get retrieve authData + // If retrieved valid authData, call success function with the data + options.success(this, { + id: 1234 + }); + }, restoreAuthentication() { return true; }, From dc67e0c248103611d335bd58ec6b95610554d768 Mon Sep 17 00:00:00 2001 From: Diamond Lewis Date: Tue, 10 Nov 2020 10:42:55 -0600 Subject: [PATCH 2/3] Update users.md --- _includes/js/users.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/_includes/js/users.md b/_includes/js/users.md index dcd385854..77ea8f61c 100644 --- a/_includes/js/users.md +++ b/_includes/js/users.md @@ -473,10 +473,10 @@ const loggedIn = await Parse.User.logInWith('CustomAdapter', { authData: myAuthD ### Custom Authentication Module Parse Server supports many [3rd Party Authenications]({{ site.baseUrl }}/parse-server/guide/#oauth-and-3rd-party-authentication). -It is possible to `linkWith` any 3rd Party Authentication by creating a custom authentication module. A custom authetication module normally consists of a client-side provider object and a back-end authAdapter. The client-side object should implement the [AuthProvider interface](https://github.com/parse-community/Parse-SDK-JS/blob/master/src/interfaces/AuthProvider.js). The backend authAdapter should implement the the functions `validateAuthData` and `validateAppId`, check out this [AuthAdapter example](https://github.com/parse-community/parse-server/blob/master/src/Adapters/Auth/AuthAdapter.js). +It is possible to `linkWith` any 3rd Party Authentication by creating a custom authentication module. A custom authentication module normally consists of a client-side AuthProvider object and a back-end AuthAdapter. The client-side object should implement the [AuthProvider interface](https://github.com/parse-community/Parse-SDK-JS/blob/master/src/interfaces/AuthProvider.js). The backend AuthAdapter should implement the the functions `validateAuthData` and `validateAppId`, check out this [AuthAdapter example](https://github.com/parse-community/parse-server/blob/master/src/Adapters/Auth/AuthAdapter.js). When calling the `linkWith` function **without** an `authData` object the client side authenticate-method from the provider object will be called. In the other case the `authData` object will be sent directly to parse server for authentication using the backend module. -Note: The following is a minimal example implementing auth provider client-side and authadapter on the backend. +Note: The following is a minimal example implementing AuthProvider client-side and AuthAdapter on the backend. A minimal `CustomAuth.js` module in the backend: ```javascript @@ -524,6 +524,8 @@ const provider = { options.success(this, { id: 1234 }); + // You can also handle error + // options.error(this, {}); }, restoreAuthentication() { return true; From 1efc5ee0c5b8ac67dcec808e6638d51350e9942a Mon Sep 17 00:00:00 2001 From: Tom Fox <13188249+TomWFox@users.noreply.github.com> Date: Thu, 12 Nov 2020 21:20:38 +0000 Subject: [PATCH 3/3] Apply suggestions from code review --- _includes/js/users.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_includes/js/users.md b/_includes/js/users.md index 77ea8f61c..a306ac1af 100644 --- a/_includes/js/users.md +++ b/_includes/js/users.md @@ -399,7 +399,7 @@ Signing a user up with a linked service and logging them in with that service us ```javascript const myAuthData = { - id: '12345678' // required field. Used to uniquely identify the linked account. + id: '12345678' // Required field. Used to uniquely identify the linked account. }; const user = new Parse.User(); await user.linkWith('providerName', { authData: myAuthData }); @@ -450,7 +450,7 @@ To create a link to an un-authenticated user (for example in cloud code), option ```javascript const myAuthData = { - id: xzx5tt123, // The id key is required in the authData-object. Otherwise Parse server will throw the Error 252 'This authentication method is unsupported.' + id: xzx5tt123, // The id key is required in the authData-object. Otherwise Parse Server will throw the Error 252 'This authentication method is unsupported'. access: token } @@ -474,7 +474,7 @@ const loggedIn = await Parse.User.logInWith('CustomAdapter', { authData: myAuthD Parse Server supports many [3rd Party Authenications]({{ site.baseUrl }}/parse-server/guide/#oauth-and-3rd-party-authentication). It is possible to `linkWith` any 3rd Party Authentication by creating a custom authentication module. A custom authentication module normally consists of a client-side AuthProvider object and a back-end AuthAdapter. The client-side object should implement the [AuthProvider interface](https://github.com/parse-community/Parse-SDK-JS/blob/master/src/interfaces/AuthProvider.js). The backend AuthAdapter should implement the the functions `validateAuthData` and `validateAppId`, check out this [AuthAdapter example](https://github.com/parse-community/parse-server/blob/master/src/Adapters/Auth/AuthAdapter.js). -When calling the `linkWith` function **without** an `authData` object the client side authenticate-method from the provider object will be called. In the other case the `authData` object will be sent directly to parse server for authentication using the backend module. +When calling the `linkWith` function **without** an `authData` object the client side authenticate-method from the provider object will be called. In the other case the `authData` object will be sent directly to Parse Server for authentication using the backend module. Note: The following is a minimal example implementing AuthProvider client-side and AuthAdapter on the backend.