[SDK-4379] Readme / migration guide tweaks (#661)

Co-authored-by: Poovamraj T T <[email protected]>
auth0 · Jul 7, 2023 · 45a02ce · 45a02ce
1 parent 5d754a1
commit 45a02ce
Show file tree

Hide file tree

Showing 4 changed files with 92 additions and 74 deletions.
diff --git a/BREAKING-CHANGE.md b/BREAKING-CHANGE.md
diff --git a/EXAMPLES.md b/EXAMPLES.md
@@ -48,7 +48,7 @@ auth0.auth
 
 ```js
 auth0.auth
-  .userInfo({token: 'the user access_token'})
+  .userInfo({ token: 'the user access_token' })
   .then(console.log)
   .catch(console.error);
 ```
@@ -59,19 +59,17 @@ This endpoint requires an access token that was granted the `/userinfo` audience
 
 ```js
 auth0.auth
-  .refreshToken({refreshToken: 'the user refresh_token'})
+  .refreshToken({ refreshToken: 'the user refresh_token' })
   .then(console.log)
   .catch(console.error);
 ```
 
 ### Using custom scheme for web authentication redirection
 
-Custom Schemes can be used for redirecting to the React Native application after web authentication. Using this is <strong>mandatory</strong> for Expo applications.
+Custom Schemes can be used for redirecting to the React Native application after web authentication:
 
 ```js
-authorize({}, {customScheme: 'auth0'})
-  .then(console.log)
-  .catch(console.error);
+authorize({}, { customScheme: 'auth0' }).then(console.log).catch(console.error);
 ```
 
 ### Login using MFA with One Time Password code
@@ -162,7 +160,10 @@ auth0.auth
 ```js
 auth0
   .users('the user access_token')
-  .patchUser({id: 'user_id', metadata: {first_name: 'John', last_name: 'Doe'}})
+  .patchUser({
+    id: 'user_id',
+    metadata: { first_name: 'John', last_name: 'Doe' },
+  })
   .then(console.log)
   .catch(console.error);
 ```
@@ -171,8 +172,8 @@ auth0
 
 ```js
 auth0
-  .users('the user access_token')
-  .getUser({id: 'user_id'})
+  .users('{ACCESS_TOKEN}')
+  .getUser({ id: 'user_id' })
   .then(console.log)
   .catch(console.error);
 ```
@@ -190,9 +191,9 @@ Note that Organizations is currently only available to customers on our Enterpri
 
 ```js
 auth0.webAuth
-  .authorize({organization: 'organization-id'})
-  .then(credentials => console.log(credentials))
-  .catch(error => console.log(error));
+  .authorize({ organization: 'organization-id' })
+  .then((credentials) => console.log(credentials))
+  .catch((error) => console.log(error));
 ```
 
 ### Accept user invitations
@@ -209,8 +210,8 @@ auth0.webAuth
     invitationUrl:
       'https://myapp.com/login?invitation=inv123&organization=org123',
   })
-  .then(credentials => console.log(credentials))
-  .catch(error => console.log(error));
+  .then((credentials) => console.log(credentials))
+  .catch((error) => console.log(error));
 ```
 
 If the URL doesn't contain the expected values, an error will be raised through the provided callback.
@@ -231,18 +232,18 @@ auth0.auth
     realm: realm,
     scope: scope,
   })
-  .then(credentials => {
+  .then((credentials) => {
     // Logged in!
   })
-  .catch(error => {
+  .catch((error) => {
     if (error.name === 'requires_verification') {
       auth0.webAuth
         .authorize({
           connection: realm,
           scope: scope,
           login_hint: email, // So the user doesn't have to type it again
         })
-        .then(credentials => {
+        .then((credentials) => {
           // Logged in!
         })
         .catch(console.error);

diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md
@@ -0,0 +1,50 @@
+# Migration Guide
+
+## Upgrading from v2 -> v3
+
+### Improvements and changes
+
+- Web Auth will now have default scope of 'openid profile email', so these scopes can be removed if you're explicitly specifying them
+- Minimum supported version for iOS is bumped to 13
+- Revoke Token and Change Password now return `void` instead of an empty object
+
+### Breaking changes
+
+- The properties inside the `user` object will now be camelCase instead of snake_case
+- Removed the `type` property returned in the `Credentials` object in Android. Use `tokenType` instead.
+- `Credentials` object in Android will return `expiresIn` instead of `expiresAt`
+- `max_age` parameter is changed to `maxAge` in `WebAuth.authorize()`
+- `skipLegacyListener` has been removed in `authorize` and `clearSession`
+- `customScheme` is now part of `ClearSessionOptions` instead of `ClearSessionParameters` in `clearSession`
+
+### Callback URL migration
+
+We are migrating the callback URL we use for the SDK to below.
+
+**Old**
+
+```
+iOS: {PRODUCT_BUNDLE_IDENTIFIER}://{DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback
+Android: {YOUR_APP_PACKAGE_NAME}://{DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
+```
+
+**New**
+
+Notice the new `.auth0` suffix after the bundle identifier / package name:
+
+```
+iOS: {PRODUCT_BUNDLE_IDENTIFIER}.auth0://{DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback
+Android: {YOUR_APP_PACKAGE_NAME}.auth0://{DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
+```
+
+Choose one of the following migration paths depending on your application:
+
+- **If your project is built with Expo:**
+  - To keep things as it is, no changes are required
+  - To migrate to new non-custom scheme flow:
+    - Remove custom scheme in app.json and `authorize()`.
+    - Run `npx expo prebuild --clean` (any manual changes to Android or iOS folders will be lost)
+    - Add the new callback URL to Auth0 dashboard
+- **If your project is built with Non Expo:**
+  - To keep things as it is, set `useLegacyCallbackUrl` to true in `authorize` and `clearSession`
+  - To migrate to new non-custom scheme flow, add the new callback URL to Auth0 dashboard
diff --git a/README.md b/README.md
@@ -11,36 +11,28 @@
 
 ## Documentation
 
-- [Quickstart](https://auth0.com/docs/quickstart/native/react-native/interactive)
-- [Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo/interactive)
+- [Quickstart](https://auth0.com/docs/quickstart/native/react-native-beta/interactive)
+- [Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo-beta/interactive)
 - [Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Hooks)
 - [Expo Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Expo)
 - [FAQs](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md)
 - [Examples](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md)
 - [Docs Site](https://auth0.github.io/react-native-auth0/)
 
-## Important Notices
-
-Version **2.9.0** introduced a **breaking change** to the Android configuration. Previously it was required to add an intent filter in the definition of the Activity that receives the authentication result, and to use the `singleTask` **launchMode** in that activity. Now both the intent filter and the launch mode **must be removed** and instead you need to add a couple of manifest placeholders. Check out the [Android](#android) section for more details.
-
 ## Getting Started
 
 ### Requirements
 
 This SDK targets apps that are using React Native SDK version `0.60.5` and up. If you're using an older React Native version, see the compatibility matrix below.
 
-### Compatibility Matrix
-
-This SDK attempts to follow [semver](https://semver.org/) in a best-effort basis, but React Native is still making releases that eventually include breaking changes on it making this approach difficult for any React Native library module. Use the table below to find the version that best suites your application.
+### Platform compatibility
 
-| React Native SDK | Auth0 SDK |
-| :--------------: | :-------: |
-|     v0.65.0      |  v2.11.0  |
-|     v0.62.2      |  v2.5.0   |
-|     v0.60.5      |  v2.0.0   |
-| v0.59.0 or lower |  v1.6.0   |
+The following shows platform minimums for running projects with this SDK:
 
-The contents of previous release can be found on the [branch v1](https://github.com/auth0/react-native-auth0/tree/v1).
+| Platform | Minimum version |
+| -------- | :-------------: |
+| iOS      |      13.0       |
+| Android  |       28        |
 
 ### Installation
 
@@ -73,18 +65,18 @@ Open your app's `build.gradle` file (typically at `android/app/build.gradle`) an
 android {
     defaultConfig {
         // Add the next line
-        manifestPlaceholders = [auth0Domain: "YOUR_AUTH0_DOMAIN", auth0Scheme: "${applicationId}"]
+        manifestPlaceholders = [auth0Domain: "YOUR_AUTH0_DOMAIN", auth0Scheme: "${applicationId}.auth0"]
     }
     ...
 }
 ```
 
-The `auth0Domain` value must be replaced with your Auth0 domain value. So if you have `samples.auth0.com` as your Auth0 domain you would have a configuration like the following:
+The `auth0Domain` value must be replaced with your Auth0 domain value. So if you have `samples.us.auth0.com` as your Auth0 domain you would have a configuration like the following:
 
 ```groovy
 android {
     defaultConfig {
-        manifestPlaceholders = [auth0Domain: "samples.auth0.com", auth0Scheme: "${applicationId}"]
+        manifestPlaceholders = [auth0Domain: "samples.us.auth0.com", auth0Scheme: "${applicationId}.auth0"]
     }
     ...
 }
@@ -149,7 +141,7 @@ and then below it register a URL type entry using the value of `CFBundleIdentifi
         <string>auth0</string>
         <key>CFBundleURLSchemes</key>
         <array>
-            <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+            <string>$(PRODUCT_BUNDLE_IDENTIFIER).auth0</string>
         </array>
     </dict>
 </array>
@@ -189,10 +181,10 @@ To use the SDK with Expo, configure the app at build time by providing the `doma
 }
 ```
 
-| API          | Description                                                                                                                                                                                                                                                                                                                                   |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| domain       | Mandatory: Provide the Auth0 domain that can be found at the [Application Settings](https://manage.auth0.com/#/applications)                                                                                                                                                                                                                  |
-| customScheme | Mandatory: Custom scheme to build the callback URL with. The value provided here should be passed to the `customScheme` option parameter of the `authorize` and `clearSession` methods. The custom scheme should be a unique, all lowercase value with no special characters (For example: auth0.YOUR_APP_PACKAGE_NAME_OR_BUNDLE_IDENTIFIER). |
+| API          | Description                                                                                                                                                                                                                                                                                                                                  |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| domain       | Mandatory: Provide the Auth0 domain that can be found at the [Application Settings](https://manage.auth0.com/#/applications)                                                                                                                                                                                                                 |
+| customScheme | Optional: Custom scheme to build the callback URL with. The value provided here should be passed to the `customScheme` option parameter of the `authorize` and `clearSession` methods. The custom scheme should be a unique, all lowercase value with no special characters. |
 
 Now you can run the application using `expo run:android` or `expo run:ios`.
 
@@ -209,18 +201,18 @@ If in addition you plan to use the log out method, you must also add these URLs
 #### Android
 
 ```text
-{APP_PACKAGE_NAME_OR_CUSTOM_SCHEME}://{AUTH0_DOMAIN}/android/{APP_PACKAGE_NAME}/callback
+{YOUR_APP_PACKAGE_NAME}.auth0://{AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
 ```
 
-> Make sure to replace {APP_PACKAGE_NAME_OR_CUSTOM_SCHEME} and {AUTH0_DOMAIN} with the actual values for your application. The {APP_PACKAGE_NAME_OR_CUSTOM_SCHEME} value provided should be all lower case.
+> Make sure to replace {YOUR_APP_PACKAGE_NAME} and {AUTH0_DOMAIN} with the actual values for your application. The {YOUR_APP_PACKAGE_NAME} value provided should be all lower case.
 
 #### iOS
 
 ```text
-{BUNDLE_IDENTIFIER_OR_CUSTOM_SCHEME}://{AUTH0_DOMAIN}/ios/{BUNDLE_IDENTIFIER}/callback
+{PRODUCT_BUNDLE_IDENTIFIER}.auth0://{AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback
 ```
 
-> Make sure to replace {BUNDLE_IDENTIFIER_OR_CUSTOM_SCHEME} and {AUTH0_DOMAIN} with the actual values for your application. The {BUNDLE_IDENTIFIER_OR_CUSTOM_SCHEME} value provided should be all lower case.
+> Make sure to replace {PRODUCT_BUNDLE_IDENTIFIER} and {AUTH0_DOMAIN} with the actual values for your application. The {PRODUCT_BUNDLE_IDENTIFIER} value provided should be all lower case.
 
 ## Next Steps
 
@@ -274,7 +266,7 @@ import { useAuth0 } from 'react-native-auth0';
 
 #### Login
 
-Use the `authorize` method to redirect the user to the Auth0 [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) page for authentication.
+Use the `authorize` method to redirect the user to the Auth0 [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) page for authentication. If `scope` is not specified, `openid profile email` is used by default.
 
 - The `isLoading` property is set to true once the authentication state of the user is known to the SDK.
 - The `user` property is populated with details about the authenticated user. If `user` is `null`, no user is currently authenticated.
@@ -285,7 +277,7 @@ const Component = () => {
   const { authorize, user, isLoading, error } = useAuth0();
 
   const login = async () => {
-    await authorize({ scope: 'openid profile email' }); // authorize({scope: 'openid profile email'}, {customScheme: 'CUSTOM_SCHEME'}) when using Expo or a custom scheme
+    await authorize(); // authorize({}, {customScheme: 'CUSTOM_SCHEME'}) when using Expo or a custom scheme
   };
 
   if (isLoading) {
@@ -311,7 +303,7 @@ const Component = () => {
 
   ```js
   auth0.webAuth
-    .authorize({scope: 'openid email profile'})
+    .authorize()
     .then(credentials => console.log(credentials))
     .catch(error => console.log(error));
   ```
@@ -336,7 +328,7 @@ const Component = () => {
   const { clearSession, user } = useAuth0();
 
   const logout = async () => {
-    await clearSession(); // clearSession({customScheme: 'CUSTOM_SCHEME'}) when using Expo or a custom scheme
+    await clearSession(); // clearSession({}, { customScheme: 'CUSTOM_SCHEME' }) when using Expo or a custom scheme
   };
 
   return <View>{user && <Button onPress={logout} title="Log out" />}</View>;