DOCSP-4883 Document OAuth2 login with React Native

contrib/docs-examples/.eslintrc

@@ -15,7 +15,10 @@
         "react/no-array-index-key": ["off"],
         "no-unused-vars": ["warn"],
         "no-console": ["off"],
-        "no-multi-spaces": ["off"]
+        "no-multi-spaces": ["off"],
+        "max-len": ["off"],
+        "react/jsx-filename-extension": ["off"],
+        "object-curly-newline": ["warn"]
     },
     "extends": ["airbnb"]
 }

contrib/docs-examples/checksum

@@ -1 +1 @@
-c83441369227c697b1e9b4c824c41b5a
+a4fa2fafc83bfa36b518faaac6ed9e6a

contrib/docs-examples/snippets/react-native/GoogleCredential.js

@@ -0,0 +1,100 @@
+function example() {} function untested({View, Text, Button, React, GoogleSignin, Stitch, GoogleCredential, GoogleSigninButton}) { // too much boilerplate to be able to test this
+  // Example component that uses the react-native-google-signin module to get
+  // the server auth code for Stitch to use.
+  //
+  // NOTE: The react-native-google-signin native module must be installed correctly
+  // and your Google project must be configured.
+  //
+  // For more detail, see https://stackoverflow.com/questions/55145071/#55173164
+  //
+  // Above:
+  // import {Stitch, GoogleCredential} from 'mongodb-stitch-react-native-sdk'
+  // import {GoogleSignin, GoogleSigninButton} from 'react-native-google-signin'
+  class GoogleLogin extends React.Component {
+    // ... other component methods ...
+
+    componentDidMount() {
+      // Configure react-native-google-signin
+      GoogleSignin.configure({
+        webClientId: '<id>', // client ID of type WEB that is found in the Google project configuration
+        offlineAccess: true, // Must be `true` to allow the Stitch service to use credential
+        iosClientId: '<id>', // [iOS] CLIENT_ID from GoogleService-Info.plist
+      })
+    }
+
+    _onPressLogin = async () => {
+      // It's recommended to call this before signIn()
+      await GoogleSignin.hasPlayServices()
+
+      // Sign in via react-native-google-signin
+      const userInfo = await GoogleSignin.signIn()
+
+      // Retrieve the server auth code
+      const {serverAuthCode} = userInfo
+
+      // serverAuthCode will be null if something went wrong
+      if (serverAuthCode === null) {
+        throw new Error('Failed to get serverAuthCode!')
+      }
+      try {
+        // Pass auth code to Stitch with a GoogleCredential
+        const {auth} = Stitch.defaultAppClient
+        const user = await auth.loginWithCredential(new GoogleCredential(serverAuthCode))
+
+        // Log in was successful
+        console.log(`Successfully logged in as user ${user.id}`)
+        this.setState({currentUserId: user.id})
+      } catch (err) {
+        // Login failed
+        console.error(`Failed to log in: ${err}`)
+        this.setState({currentUserId: undefined})
+      }
+    }
+
+    _onPressLogout = async () => {
+      // Logout react-native-google-signin
+      await GoogleSignin.revokeAccess()
+      await GoogleSignin.signOut()
+
+      // Then log Stitch out
+      const {auth} = Stitch.defaultAppClient
+      const user = await auth.logout()
+
+      console.log(`Successfully logged out user ${user.id}`)
+      this.setState({currentUserId: undefined})
+    }
+
+    render() {
+      let loginStatus = 'Currently logged out.'
+      const {currentUserId, isSigninInProgress} = this.state
+      if (currentUserId) {
+        loginStatus = `Currently logged in as ${currentUserId}.`
+      }
+
+      // Leverage react-native-google-signin's GoogleSigninButton
+      const loginButton = (
+        <GoogleSigninButton
+          style={{width: 192, height: 48}}
+          size={GoogleSigninButton.Size.Wide}
+          color={GoogleSigninButton.Color.Dark}
+          onPress={this._onPressLogin}
+          disabled={isSigninInProgress}
+        />
+      )
+
+      const logoutButton = (
+        <Button
+          onPress={this._onPressLogout}
+          title="Logout"
+        />
+      )
+
+      return (
+        <View>
+          <Text> {loginStatus} </Text>
+          {currentUserId === undefined ? loginButton : logoutButton}
+        </View>
+      )
+    }
+  }
+}

contrib/docs-examples/snippets/react-native/StitchAuth.js

@@ -0,0 +1,20 @@
+function example({AnonymousCredential, UserPasswordCredential, stitchAppClient}) {
+  // Previously:
+  // const stitchAppClient = await Stitch.initializeDefaultAppClient('your-stitch-app-id')
+
+  // Log in with anonymous credential
+  stitchAppClient.auth
+    .loginWithCredential(new AnonymousCredential())
+    .then((user) => {
+      console.log(`Logged in as anonymous user with id: ${user.id}`)
+    })
+    .catch(console.error)
+
+  // Log in with user/password credential
+  stitchAppClient.auth
+    .loginWithCredential(new UserPasswordCredential('user', 'password'))
+    .then((user) => {
+      console.log(`Logged in as user with id: ${user.id}`)
+    })
+    .catch(console.error)
+}

contrib/docs-examples/snippets/react-native/StitchAuth.loginWithCredential.js

@@ -0,0 +1,98 @@
+function example() {} function untested({View, Text, Button, React, GoogleSignin, Stitch, GoogleCredential, GoogleSigninButton}) { // too much boilerplate to be able to test this
+  // Example component that uses the react-native-google-signin module to get
+  // the server auth code for Stitch to use.
+  //
+  // NOTE: The react-native-google-signin native module must be installed correctly
+  // and your Google project must be configured.
+  //
+  // For more detail, see https://stackoverflow.com/questions/55145071/#55173164
+  //
+  // Above:
+  // import {Stitch, GoogleCredential} from 'mongodb-stitch-react-native-sdk'
+  // import {GoogleSignin, GoogleSigninButton} from 'react-native-google-signin'
+  class GoogleLogin extends React.Component {
+    // ...
+
+    componentDidMount() {
+      // Configure react-native-google-signin
+      GoogleSignin.configure({
+        webClientId: '<id>', // client ID of type WEB from Stitch
+        offlineAccess: true, // allows Stitch service to use credential
+        iosClientId: '<id>', // [iOS] CLIENT_ID from GoogleService-Info.plist
+      })
+    }
+
+    _onPressLogin = async () => {
+      // It's recommended to call this before signIn()
+      await GoogleSignin.hasPlayServices()
+
+      // Sign in via react-native-google-signin
+      const userInfo = await GoogleSignin.signIn()
+
+      // Retrieve the server auth code
+      const {serverAuthCode} = userInfo
+      if (serverAuthCode === null) {
+        throw new Error('Failed to get serverAuthCode!')
+      }
+      try {
+        // Pass auth code to Stitch with a GoogleCredential
+        const {auth} = Stitch.defaultAppClient
+        const user = await auth.loginWithCredential(new GoogleCredential(serverAuthCode))
+
+        // Log in was successful
+        console.log(`Successfully logged in as user ${user.id}`)
+        this.setState({currentUserId: user.id})
+      } catch (err) {
+        // Login failed
+        console.error(`Failed to log in: ${err}`)
+        this.setState({currentUserId: undefined})
+      }
+    }
+
+    _onPressLogout = async () => {
+      // Logout react-native-google-signin
+      await GoogleSignin.revokeAccess()
+      await GoogleSignin.signOut()
+
+      // Then log Stitch out
+      const {auth} = Stitch.defaultAppClient
+      const user = await auth.logout()
+
+      console.log(`Successfully logged out user ${user.id}`)
+      this.setState({currentUserId: undefined})
+    }
+
+    render() {
+      let loginStatus = 'Currently logged out.'
+      const {currentUserId, isSigninInProgress} = this.state
+      if (currentUserId) {
+        loginStatus = `Currently logged in as ${currentUserId}.`
+      }
+
+      // Leverage react-native-google-signin's GoogleSigninButton
+      const loginButton = (
+        <GoogleSigninButton
+          style={{width: 192, height: 48}}
+          size={GoogleSigninButton.Size.Wide}
+          color={GoogleSigninButton.Color.Dark}
+          onPress={this._onPressLogin}
+          disabled={isSigninInProgress}
+        />
+      )
+
+      const logoutButton = (
+        <Button
+          onPress={this._onPressLogout}
+          title="Logout"
+        />
+      )
+
+      return (
+        <View>
+          <Text> {loginStatus} </Text>
+          {currentUserId === undefined ? loginButton : logoutButton}
+        </View>
+      )
+    }
+  }
+}

packages/core/sdk/src/auth/providers/facebook/FacebookCredential.ts

@@ -22,7 +22,17 @@ enum Fields {
   ACCESS_TOKEN = "accessToken"
 }
 
-/** @hidden */
+/** 
+ * A credential which can be used to log in as a Stitch user
+ * using the Facebook authentication provider.
+ *
+ * Browser SDK users can use the 
+ * [FacebookRedirectCredential](https://docs.mongodb.com/stitch-sdks/js/4/classes/facebookredirectcredential.html)
+ * with [StitchAuth.loginWithRedirect](https://docs.mongodb.com/stitch-sdks/js/4/interfaces/stitchauth.html#loginwithredirect).
+ * Server and React Native SDK users must obtain their own access token.
+ * Use a third-party module to get this token and pass it to the FacebookCredential
+ * constructor.
+ */
 export default class FacebookCredential implements StitchCredential {
 
   public get providerCapabilities(): ProviderCapabilities {

packages/core/sdk/src/auth/providers/google/GoogleCredential.ts

@@ -23,9 +23,15 @@ enum Fields {
 }
 
 /** 
- * @hidden
  * A credential which can be used to log in as a Stitch user
  * using the Google authentication provider.
+ *
+ * Browser SDK users can use the 
+ * [GoogleRedirectCredential](https://docs.mongodb.com/stitch-sdks/js/4/classes/googleredirectcredential.html)
+ * with [StitchAuth.loginWithRedirect](https://docs.mongodb.com/stitch-sdks/js/4/interfaces/stitchauth.html#loginwithredirect).
+ * Server and React Native SDK users must obtain their own server auth code.
+ * Use a third-party module to get this code and pass it to the GoogleCredential
+ * constructor.
  */
 export default class GoogleCredential implements StitchCredential {
   /**

packages/react-native/core/src/core/Stitch.ts

@@ -30,10 +30,14 @@ let appClients: { [key: string]: StitchAppClientImpl } = {};
  * Singleton class with static utility functions for initializing a [[StitchAppClient]].
  *
  * Typically, the [[Stitch.initializeDefaultAppClient]] method is all you need 
- * to instantiate the client:
+ * to instantiate the client (note that, unlike in the browser and server JS SDKs, this
+ * method returns a Promise in the React Native SDK):
  * 
  * ```
- * const client = Stitch.initializeDefaultAppClient('your-stitch-app-id')
+ * Stitch.initializeDefaultAppClient('your-stitch-app-id')
+ *   .then((client) => {
+ *     // use client
+ *   })
  * ```
  *
  * For custom configurations, see [[Stitch.initializeAppClient]] and [[StitchAppClientConfiguration]].

packages/react-native/core/src/core/StitchAppClient.ts

@@ -33,9 +33,12 @@ import StitchAuth from "./auth/StitchAuth";
  *
  * @example
  * ```
- * import { Stitch } from "mongodb-stitch-browser-sdk"
+ * import { Stitch } from 'mongodb-stitch-react-native-sdk'
  * 
- * const client = Stitch.initializeDefaultAppClient('example-stitch-app-id')
+ * Stitch.initializeDefaultAppClient('example-stitch-app-id')
+ *   .then((client) => {
+ *     // use client
+ *   })
  * ```
  * 
  * @see

packages/react-native/core/src/core/auth/StitchAuth.ts

@@ -27,11 +27,14 @@ import StitchUser from "./StitchUser";
  * [Authentication Provider](https://docs.mongodb.com/stitch/authentication/)
  * you are using and use [[loginWithCredential]] to log in.
  *
+ * For OAuth2 login (e.g. Google, Facebook), you must obtain a server auth code
+ * yourself and pass it to the relevant [[StitchCredential]]. One approach is 
+ * to use a third party module, e.g. install
+ * [react-native-google-signin](https://github.com/react-native-community/react-native-google-signin)
+ * and use it to get the auth code to pass to [[GoogleCredential]].
+ *
  * Once logged in, [[StitchAuth.user]] is a [[StitchUser]] object that can be examined for 
  * user profile and other information.
- * 
- * Login state can persist across browser sessions. Therefore, a StitchAppClient's
- * StitchAuth instance may already contain login information upon initialization.
  *
  * To log out, use [[logout]].
  *

packages/server/core/src/core/auth/StitchAuth.ts

@@ -27,6 +27,12 @@ import StitchUser from "./StitchUser";
  * [Authentication Provider](https://docs.mongodb.com/stitch/authentication/)
  * you are using and use [[loginWithCredential]] to log in.
  *
+ * For OAuth2 login (e.g. Google, Facebook), you must obtain a server auth code
+ * yourself and pass it to the relevant [[StitchCredential]]. One approach is 
+ * to use a third party module, e.g. install
+ * [google-auth-library](https://www.npmjs.com/package/google-auth-library)
+ * and use it to get the auth code to pass to [[GoogleCredential]].
+ *
  * Once logged in, [[StitchAuth.user]] is a [[StitchUser]] object that can be examined for 
  * user profile and other information.
  *