Add section for Cognito Hosted UI on React Native

.spelling

@@ -285,6 +285,8 @@ withFederated
 Auth.federatedSignIn
 aws.cognito.signin.user.admin
 ChallengeName
+myapp
+LoginWithAmazon
 
 #js/cognito-hosted-ui-federated-identity.md
 oauth2

js/authentication.md

@@ -1055,9 +1055,9 @@ There is also `withGoogle`, `withFacebook`, `withAmazon` components, in case you
 
 ### Using Amazon Cognito Hosted UI
 
-Amazon Cognito provides a customizable user experience via the hosted UI. The hosted UI supports OAuth 2.0 and Federated Identities with Facebook, Amazon, Google, and SAML providers. To learn more about Amazon Cognito Hosted UI, please visit [Amazon Cognito Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html).
+Amazon Cognito provides a customizable user experience via the hosted UI. The hosted UI supports OAuth 2.0 and Federated Identities with Facebook, Amazon, Google, OIDC and SAML providers. To learn more about Amazon Cognito Hosted UI, please visit [Amazon Cognito Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html).
 
-> ***The Hosted UI support is only available for React / Web***
+> ***The Hosted UI support is only available for React / React Native / Web***
 
 #### Setup your Cognito App Client
 
@@ -1098,6 +1098,28 @@ To setup App Client:
 For example, in *Callback URL(s)*, you can put one url for local development, one for the production. If your app is running in `http://localhost:3000/` in local and `https://www.example.com/` in production, you can put `http://localhost:3000/,https://www.example.com/` under *Callback URL(s)*. Same as the *Signout URL(s)*.
 {: .callout .callout--info}
 
+<div>
+For React Native applications, you can put one url for local development, one for production.
+
+You need to define a custom URL scheme for your application before testing locally or publishing to the app store. This is different for Expo or vanilla React Native. Follow the steps at the [React Native Linking docs](https://facebook.github.io/react-native/docs/linking) or [Expo Linking docs](https://docs.expo.io/versions/latest/workflow/linking/) for more information.
+
+After completing those steps, assuming you are using "myapp" as the name of your URL Scheme (or whatever friendly name you have chosen), you will use this URL in the Cognito Hosted UI domain URL.
+
+Your URLs could look like any of these:
+
+- `myapp://`
+- `exp://127.0.0.1:19000/--/` (Local development if your app is running [in the Expo client](https://docs.expo.io/versions/latest/workflow/linking/#linking-to-your-app)).
+One way to get your app URL when using Expo, is doing this:
+
+```js
+import { Linking } from 'expo';
+
+console.log('url', Linking.makeUrl('/'));
+```
+
+</div>
+{: .callout .callout--info}
+
 - Under the *OAuth 2.0* section, Choose OAuth Flow and OAuth scopes. [To learn more about flows and scopes.](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-app-idp-settings.html)
 - Select an OAuth Flow. 
 
@@ -1124,7 +1146,7 @@ Note: `openid` is required for `phone`, `email` or `profile`. Also `openid` is r
 
 To configure your application for hosted UI, you need to use *oauth* options:
 
-> ***The Hosted UI support is only available for React / Web***
+> ***The Hosted UI support is only available for React / React Native / Web***
 
 ```javascript
 import Amplify from 'aws-amplify';
@@ -1137,10 +1159,10 @@ const oauth = {
     scope : ['phone', 'email', 'profile', 'openid','aws.cognito.signin.user.admin'], 
 
     // Callback URL
-    redirectSignIn : 'http://www.example.com/signin/', 
+    redirectSignIn : 'http://www.example.com/signin/', // or 'exp://127.0.0.1:19000/--/', 'myapp://main/'
 
     // Sign out URL
-    redirectSignOut : 'http://www.example.com/signout/',
+    redirectSignOut : 'http://www.example.com/signout/', // or 'exp://127.0.0.1:19000/--/', 'myapp://main/'
 
     // 'code' for Authorization code grant, 
     // 'token' for Implicit grant
@@ -1170,7 +1192,7 @@ Note: An ID token is only returned if openid scope is requested. The access toke
 
 To invoke the browser to display the hosted UI, you need to construct the URL in your app;
 
-> ***The Hosted UI support is only available for React / Web***
+> ***The Hosted UI support is only available for React / React Native / Web***
 
 ```javascript
 const config = Auth.configure();
@@ -1201,7 +1223,7 @@ window.location.assign(url_to_facebook);
 
 With React, you can use `withOAuth` HOC to launch the hosted UI experience. Just wrap your app's main component with our HOC:
 
-> ***The Hosted UI support is only available for React / Web***
+> ***The Hosted UI support is only available for React/ React Native / Web***
 
 ```javascript
 import { withOAuth } from 'aws-amplify-react';
@@ -1222,7 +1244,7 @@ export default withOAuth(MyApp);
 
 #### Make it work in your App
 
-Here is a code sample of how to integrate it in the React App:
+Here is a code sample of how to integrate it in the React App: (Web)
 ```js
 // App.js
 import React, { Component } from 'react';
@@ -1366,6 +1388,154 @@ class CustomButton extends React.Component {
 export default CustomButton;
 ```
 
+#### Launching the Hosted UI in React Native 
+
+> ***The Hosted UI support is only available for React/ React Native / Web***
+
+With React Native, you can use `withOAuth` HOC to launch the hosted UI experience. Just wrap your app's main component with our HOC. Doing so, will pass the following `props` available to your component:
+
+- `oAuthUser`: If the sign was successful, this object will have the user from the user pool.
+- `oAuthError`: In case of an error, the string with the error as given by the Cognito Hosted UI.
+
+- `hostedUISignIn`: A callback function to trigger the hosted UI sign in flow, this will show the Cognito Hosted UI.
+
+- `signOut`: A callback function to trigger the hosted UI sign out flow.
+
+The following `props` are used for building a custom UI with buttons if you do not want to show the Cognito UI, however it will still create a User Pool entry once the OAuth flow has completed.
+{: .callout .callout--info}
+
+- `facebookSignIn`: A callback function to trigger the hosted UI sign in flow for Facebook, this will show the Facebook login page.
+- `googleSignIn`: A callback function to trigger the hosted UI sign in flow for Google, this will show the Google login page.
+- `amazonSignIn`: A callback function to trigger the hosted UI sign in flow for LoginWithAmazon, this will show the LoginWithAmazon login page.
+- `customProviderSignIn`: A callback function to trigger the hosted UI sign in flow for an OIDC provider, this will show the OIDC provider login page. This function expects a string with the **provider name** specified when [adding the OIDC  IdP to your User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-oidc-idp.html#cognito-user-pools-oidc-idp-step-2).
+
+The following code snippet shows an example of its possible usage:
+
+```javascript
+import { StyleSheet, Text, ScrollView, SafeAreaView, StatusBar, Button } from 'react-native';
+import { default as Amplify } from "aws-amplify";
+import { withOAuth } from "aws-amplify-react-native";
+import { default as awsConfig } from "./aws-exports";
+
+Amplify.configure(awsConfig);
+
+Amplify.configure({
+    Auth: {
+        oauth: {
+            // OAuth config...
+        }
+    },
+});
+
+
+class App extends React.Component {
+  render() {
+    const {
+      oAuthUser: user,
+      oAuthError: error,
+      hostedUISignIn,
+      facebookSignIn,
+      googleSignIn,
+      amazonSignIn,
+      customProviderSignIn,
+      signOut,
+    } = this.props;
+
+    return (
+      <SafeAreaView style={styles.safeArea}>
+        {user && <Button title="Sign Out" onPress={signOut} icon='logout' />}
+        <ScrollView contentContainerStyle={styles.scrollViewContainer}>
+          <Text>{JSON.stringify({ user, error, }, null, 2)}</Text>
+          {!user && <React.Fragment>
+            {/* Go to the Cognito Hosted UI */}
+            <Button title="Cognito" onPress={hostedUISignIn} />
+
+            {/* Go directly to a configured identity provider */}
+            <Button title="Facebook" onPress={facebookSignIn} />
+            <Button title="Google" onPress={googleSignIn}  />
+            <Button title="Amazon" onPress={amazonSignIn} />
+
+            {/* e.g. for OIDC providers */}
+            <Button title="Yahoo" onPress={() => customProviderSignIn('Yahoo')} />
+          </React.Fragment>}
+        </ScrollView>
+      </SafeAreaView>
+    );
+  }
+}
+
+const styles = StyleSheet.create({
+  safeArea: {
+    flexGrow: 1,
+    paddingTop: StatusBar.currentHeight,
+    backgroundColor: '#FFFFFF',
+  },
+  scrollViewContainer: {
+    flexGrow: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  }
+});
+
+export default withOAuth(App);
+``` 
+
+#### A note for Expo users
+
+It is possible to use Expo's `WebBrowser.openAuthSessionAsync` function to launch the hosted UI pages. To do this, you can provide a `urlOpener` function as below when configuring OAuth in Amplify:
+
+```javascript
+import Amplify from 'aws-amplify';
+
+const urlOpener = async (url, redirectUrl) => {
+    // On Expo, use WebBrowser.openAuthSessionAsync to open the Hosted UI pages.
+    const { type, url: newUrl } = await WebBrowser.openAuthSessionAsync(url, redirectUrl);
+
+    if (type === 'success') {
+        await WebBrowser.dismissBrowser();
+
+        if (Platform.OS === 'ios') {
+        return Linking.openURL(newUrl);
+        }
+    }
+};
+
+const oauth = {
+    // Domain name
+    domain : 'your-domain-prefix.auth.us-east-1.amazoncognito.com', 
+
+    // Authorized scopes
+    scope : ['phone', 'email', 'profile', 'openid','aws.cognito.signin.user.admin'], 
+
+    // Callback URL
+    redirectSignIn : 'http://www.example.com/signin/', // or 'exp://127.0.0.1:19000/--/', 'myapp://main/'
+
+    // Sign out URL
+    redirectSignOut : 'http://www.example.com/signout/', // or 'exp://127.0.0.1:19000/--/', 'myapp://main/'
+
+    // 'code' for Authorization code grant, 
+    // 'token' for Implicit grant
+    responseType: 'code',
+
+    // optional, for Cognito hosted ui specified options
+    options: {
+        // Indicates if the data collection is enabled to support Cognito advanced security features. By default, this flag is set to true.
+        AdvancedSecurityDataCollectionFlag : true
+    },
+
+    urlOpener: urlOpener
+}
+
+Amplify.configure({
+    Auth: {
+        // other configurations...
+        // ....
+        oauth: oauth
+    },
+    // ...
+});
+```
+
 #### Handling Authentication Events
 
 When using the hosted UI, you can handle authentication events by creating event listeners with the [Hub module]({%if jekyll.environment == 'production'%}{{site.amplify.docs_baseurl}}{%endif%}/js/hub#listening-authentication-events).