From d1e652e95e5b6a878ea2389164760d0c3f103725 Mon Sep 17 00:00:00 2001 From: "Thomas E. Canter" Date: Fri, 27 Jun 2025 15:25:59 -0700 Subject: [PATCH] docs: Modernize authentication setup and enhance troubleshooting - Update README.md to use Microsoft Entra ID terminology (formerly Azure AD) - Modernize app registration instructions with current admin center UI - Add comprehensive troubleshooting section for common setup issues - Enhance developer experience with improved structure and clarity - Add Windows CMD/PowerShell command alternatives - Include detailed project structure and dependency information - Add cross-platform setup guidance and error resolution steps - Create CHANGELOG.md to document modernization improvements This modernization maintains backward compatibility while significantly improving the developer onboarding experience and resolving common authentication configuration issues. --- CHANGELOG.md | 74 +++++++++++ README.md | 351 ++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 390 insertions(+), 35 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e43de69 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,74 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Fixed - 2025-06-27 +#### Critical Authentication Configuration Issue + +- **Fixed "YOUR_APP_ID_HERE" error caused by TypeScript compilation conflicts** + - Added mandatory step to delete `AuthConfig.example.ts` after configuration + - Updated setup instructions to emphasize the importance of removing the example file + - Added comprehensive troubleshooting section explaining why both files cannot coexist + - This resolves the most common authentication error where the app uses placeholder values despite correct `AuthConfig.ts` configuration + +### Changed - 2025-06-27 +#### Documentation Modernization by Tom Canter + +- **Modernized README to use Microsoft Entra ID terminology** + - Updated all references from "Azure Active Directory" to "Microsoft Entra ID" + - Updated admin center links to use the new Entra admin center (entra.microsoft.com) + - Modernized app registration instructions with current UI navigation paths + +- **Enhanced documentation structure and developer experience** + - Added comprehensive Features section highlighting key capabilities + - Improved Prerequisites with specific version requirements and detailed setup guidance + - Added "Getting a Microsoft Account" section with clear options for personal and developer accounts + - Enhanced Registration steps with detailed, step-by-step instructions including API permissions setup + +- **Improved setup and installation instructions** + - Clarified directory navigation throughout the document + - Updated terminal commands to use consistent directory references (`cd ./GraphRNSample`) + - Added clear distinction between project root (`msgraph-sample-react-native`) and React Native app directory (`GraphRNSample`) + - Enhanced dependency installation instructions with better context + +- **Added comprehensive troubleshooting and project guidance** + - Added detailed Troubleshooting section with common issues and solutions + - Included complete Project Structure overview showing full directory hierarchy + - Enhanced run instructions with multiple options and better error handling + - Added Key Dependencies section explaining important packages + +- **Improved technical accuracy and usability** + - Updated product references from "Office 365" to "Microsoft 365" + - Added security and contributing sections following modern open source practices + - Enhanced code formatting and readability throughout + - Added helpful tips and context notes for better developer experience + - Maintained historical acknowledgment of tutorial origins while modernizing content + +- **API Permissions configuration improvements** + - Detailed step-by-step instructions for adding Microsoft Graph permissions + - Clarified that User.Read permission is pre-configured by default + - Added specific guidance for Calendars.ReadWrite and MailboxSettings.Read permissions + - Explained benefits of pre-configuring permissions for admin consent scenarios + +- **Added Windows command line examples to documentation** + - Added Windows CMD and PowerShell alternatives for all bash commands + - Updated file path navigation commands for Windows syntax + - Enhanced troubleshooting commands with platform-specific examples + - Improved cross-platform developer experience + +- **Enhanced error handling and debugging guidance** + - Added troubleshooting section for "Possible Unhandled Promise Rejection" errors + - Provided step-by-step debugging instructions for React Native errors + - Added guidance for using React Native debugger and Metro console + - Included common causes and solutions for authentication-related promise rejections + +### Technical Details +- All changes maintain backward compatibility with existing code +- Enhanced documentation follows current Microsoft documentation standards +- Improved clarity for developers across different experience levels +- Better integration with modern development workflows diff --git a/README.md b/README.md index 5467270..6252f1f 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,353 @@ --- page_type: sample -description: This sample demonstrates how to use the Microsoft Graph JavaScript SDK to access data in Office 365 from React Native apps. +description: This sample demonstrates how to use the Microsoft Graph JavaScript SDK to access data in Microsoft 365 from React Native apps using Microsoft Entra ID authentication. products: - ms-graph -- office-exchange-online +- microsoft-365 +- entra-id languages: - typescript +- javascript --- -# Microsoft Graph sample React Native app +# Microsoft Graph React Native Sample with Entra ID [![React Native CI](https://github.com/microsoftgraph/msgraph-training-react-native/actions/workflows/react-native.yml/badge.svg)](https://github.com/microsoftgraph/msgraph-training-react-native/actions/workflows/react-native.yml) ![License.](https://img.shields.io/badge/license-MIT-green.svg) -This sample demonstrates how to use the Microsoft Graph JavaScript SDK to access data in Office 365 from React Native mobile apps. +This sample demonstrates how to use the Microsoft Graph JavaScript SDK to access data in Microsoft 365 from React Native mobile apps using Microsoft Entra ID for authentication and authorization. -> **NOTE:** This sample was originally built from a tutorial published on the [Microsoft Graph tutorials](https://docs.microsoft.com/graph/tutorials) page. That tutorial has been removed. +> **NOTE:** This sample was originally built from a tutorial published on the Microsoft Graph tutorials page. That tutorial has been removed. + +## Features + +This sample app demonstrates the following capabilities: + +- **Microsoft Entra ID Authentication**: Secure user sign-in using OAuth 2.0 with PKCE +- **Microsoft Graph Integration**: Access Microsoft 365 data and services +- **Cross-Platform Support**: Runs on both iOS and Android devices +- **Modern React Native**: Built with latest React Native practices and TypeScript +- **Calendar Management**: View and create calendar events +- **User Profile**: Display user information from Microsoft Graph ## Prerequisites -To run the completed project in this folder, you need the following: +To run this sample, you need: + +- **Development Environment**: A configured React Native development environment using React Native CLI + - For setup instructions, see [React Native - Setting up the development environment](https://reactnative.dev/docs/environment-setup) + - Choose "React Native CLI Quickstart" (not Expo CLI) +- **Microsoft Account**: Either a personal Microsoft account with a mailbox on Outlook.com, or a Microsoft work or school account +- **Node.js**: Version 16 or higher +- **Mobile Development Tools**: + - For iOS: Xcode (macOS only) + - For Android: Android Studio with Android SDK + +## Getting a Microsoft Account + +If you don't have a Microsoft account, here are your options: + +- **Personal Account**: [Sign up for a new personal Microsoft account](https://signup.live.com/signup?wa=wsignin1.0&rpsnv=12&ct=1454618383&rver=6.4.6456.0&wp=MBI_SSL_SHARED&wreply=https://mail.live.com/default.aspx&id=64855&cbcxt=mai&bk=1454618383&uiflavor=web&uaid=b213a65b4fdc484382b6622b3ecaa547&mkt=E-US&lc=1033&lic=1) +- **Developer Account**: [Sign up for the Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program) to get a free Microsoft 365 subscription with sample data + +## Register an Application with Microsoft Entra ID + +1. **Navigate to the Microsoft Entra admin center** + - Open a browser and go to the [Microsoft Entra admin center](https://entra.microsoft.com) + - Sign in using a **personal account** (Microsoft Account) or **Work or School Account** + +2. **Access App Registrations** + - In the left navigation, select **Identity** > **Applications** > **App registrations** + - Alternatively, you can use the [Azure portal](https://portal.azure.com) and navigate to **Microsoft Entra ID** > **App registrations** + +3. **Create a New Registration** + - Select **New registration** + - Configure the application with these settings: + - **Name**: `React Native Graph Sample` + - **Supported account types**: `Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)` + - **Redirect URI**: + - Platform: `Public client (mobile & desktop)` + - URI: `graph-sample://react-native-auth/` + +4. **Complete Registration** + - Select **Register** + - On the app's overview page, copy the **Application (client) ID** and save it securely - you'll need this in the configuration step below + +5. **Configure API Permissions (Recommended)** + - Navigate to **API permissions** in the left menu + - You'll see that `User.Read` permission is already configured by default + - To add the additional permissions needed for this sample: + 1. Click **Add a permission** + 2. Select **Microsoft Graph** + 3. Choose **Delegated permissions** + 4. Search for and select the following permissions: + - `Calendars.ReadWrite` (to read and write calendar events) + - `MailboxSettings.Read` (to read mailbox settings) + 5. Click **Add permissions** + - **Note**: The app will request these permissions dynamically when needed, but pre-configuring them here provides better visibility and can help with admin consent scenarios + +## Configure the Sample + +1. **Set up Authentication Configuration** + - In your file explorer or IDE, navigate to the root project folder you downloaded/cloned (`msgraph-sample-react-native`) + - Go to the `GraphRNSample/auth/` directory within the project + - **Rename** the file `AuthConfig.example.ts` to `AuthConfig.ts` (this removes the example file and creates your config file): + ```bash + # Bash/macOS/Linux: + mv GraphRNSample/auth/AuthConfig.example.ts GraphRNSample/auth/AuthConfig.ts + # Windows CMD: + ren GraphRNSample\auth\AuthConfig.example.ts AuthConfig.ts + # Windows PowerShell: + Rename-Item GraphRNSample\auth\AuthConfig.example.ts AuthConfig.ts + ``` + - Open the newly renamed `AuthConfig.ts` in your code editor and replace `YOUR_APP_ID_HERE` with your **Application (client) ID** from the app registration step above + - **⚠️ CRITICAL**: Do NOT copy the example file and leave the original - if both `AuthConfig.ts` and `AuthConfig.example.ts` exist, the TypeScript compiler will include both files in the build, causing the app to use the placeholder "YOUR_APP_ID_HERE" instead of your actual App ID -- A configured development environment for React Native using the React Native CLI. For instructions on configuring your environment, see [Setting up the development environment](https://reactnative.dev/docs/environment-setup). -- Either a personal Microsoft account with a mailbox on Outlook.com, or a Microsoft work or school account. +2. **Install Dependencies** + - Open a terminal/command prompt + - Navigate to the `GraphRNSample` directory within your project root: + ```bash + # Bash/macOS/Linux: + cd ./GraphRNSample + + # Windows CMD: + cd .\GraphRNSample + + # Windows PowerShell: + cd .\GraphRNSample + ``` + > **Note**: This assumes you're starting from the root project directory (`msgraph-sample-react-native`) + - Install Node.js dependencies: + ```bash + npm install + ``` + - For iOS development, install iOS dependencies: + ```bash + npx pod-install ios + ``` -If you don't have a Microsoft account, there are a couple of options to get a free account: +## Run the Sample -- You can [sign up for a new personal Microsoft account](https://signup.live.com/signup?wa=wsignin1.0&rpsnv=12&ct=1454618383&rver=6.4.6456.0&wp=MBI_SSL_SHARED&wreply=https://mail.live.com/default.aspx&id=64855&cbcxt=mai&bk=1454618383&uiflavor=web&uaid=b213a65b4fdc484382b6622b3ecaa547&mkt=E-US&lc=1033&lic=1). -- You can [sign up for the Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program) to get a free Microsoft 365 subscription. +> **Important**: All commands below should be run from the `GraphRNSample` directory. If you followed the setup steps above, you should already be in this directory after running `cd ./GraphRNSample`. -## Register an application with the Azure Active Directory admin center +### Using Metro Bundler (Recommended) -1. Open a browser and navigate to the [Azure Active Directory admin center](https://aad.portal.azure.com) and login using a **personal account** (aka: Microsoft Account) or **Work or School Account**. +1. **Start the Metro bundler**: + ```bash + npm start + ``` -1. Select **Azure Active Directory** in the left-hand navigation, then select **App registrations** under **Manage**. +2. **Use the interactive menu** to launch your app: + + Once Metro starts, you'll see an interactive menu with these options: + + ``` + r - reload the app + d - open developer menu + i - run on iOS + a - run on Android + ``` + + - **Press `i`** - Run on iOS simulator (macOS only) + - **Press `a`** - Run on Android emulator + - **Press `r`** - Reload the app if it's already running + - **Press `d`** - Open the developer menu in the running app -1. Select **New registration**. On the **Register an application** page, set the values as follows. + > **Note**: The Metro CLI will automatically start the appropriate emulator/simulator if one isn't already running. The first build may take several minutes as React Native compiles the app and installs it on your device. - - Set **Name** to `React Native Graph Sample`. - - Set **Supported account types** to **Accounts in any organizational directory and personal Microsoft accounts**. - - Under **Redirect URI**, change the dropdown to **Public client (mobile & desktop)**, and set the value to `graph-sample://react-native-auth/`. +### Alternative: Direct Commands -1. Select **Register**. On the **React Native Graph Tutorial** page, copy the value of the **Application (client) ID** and save it, you will need it in the next step. +If you prefer using direct commands instead of the interactive menu: -## Configure the sample +- **iOS Simulator**: + ```bash + npm run ios + ``` +- **Android Emulator**: + ```bash + npm run android + ``` +- **Specific iOS Simulator**: + ```bash + npx react-native run-ios --simulator="iPhone 15" + ``` -1. Rename the **GraphRNSample/auth/AuthConfig.example.ts** file to **AuthConfig.ts**. -1. Edit the **AuthConfig.ts** file and make the following changes. - 1. Replace `YOUR_APP_ID_HERE` with the **Application (client) ID** you got from the App Registration Portal. +## Troubleshooting -1. In your command-line interface (CLI), navigate to the **GraphRNSample** directory and run the following commands to install requirements. +### Common Issues - ```bash - npm install - npx pod-install ios - ``` +1. **"YOUR_APP_ID_HERE" not found error** + - This error occurs when the app is still using cached or placeholder values + - **First, verify your configuration**: + - Ensure you've renamed `AuthConfig.example.ts` to `AuthConfig.ts` + - Confirm you've replaced `YOUR_APP_ID_HERE` with your actual App ID in `AuthConfig.ts` + + - **⚠️ CRITICAL**: **Ensure only `AuthConfig.ts` exists (not both files)**: + ```bash + # Check that only AuthConfig.ts exists in the auth directory + # If you see both AuthConfig.ts AND AuthConfig.example.ts, delete the example: + # Bash/macOS/Linux: + rm GraphRNSample/auth/AuthConfig.example.ts + # Windows CMD: + del GraphRNSample\auth\AuthConfig.example.ts + # Windows PowerShell: + Remove-Item GraphRNSample\auth\AuthConfig.example.ts + ``` + **Why this matters**: If you copied `AuthConfig.example.ts` to create `AuthConfig.ts` instead of renaming it, both files will exist. The TypeScript compiler will include both files in the build, causing the app to use the placeholder "YOUR_APP_ID_HERE" from the example file instead of your actual App ID from `AuthConfig.ts`. This is the most common cause of persistent authentication errors even when `AuthConfig.ts` is correctly configured. + + - **Try these troubleshooting steps**: + ```bash + # 1. Clear Metro cache: + npx react-native start --reset-cache + + # 2. If that doesn't work, stop Metro (Ctrl+C) and try a complete clean: + npx react-native clean + + # 3. Remove node_modules and reinstall: + # Bash/macOS/Linux: + rm -rf node_modules + # Windows CMD: + rmdir /s node_modules + # Windows PowerShell: + Remove-Item -Recurse -Force node_modules + + npm install + + # 4. For iOS, reinstall pods: + npx pod-install ios + + # 5. For Android, clean gradle: + # Bash/macOS/Linux: + cd android && ./gradlew clean && cd .. + # Windows CMD: + cd android && gradlew.bat clean && cd .. + # Windows PowerShell: + cd android; .\gradlew.bat clean; cd .. + + # 6. Start Metro fresh: + npm start + ``` + - **Alternative approach**: Try deleting the Metro cache directory manually: + ```bash + # Windows CMD: + rmdir /s "%LOCALAPPDATA%\Temp\metro-*" + + # Windows PowerShell: + Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Temp\metro-*" + + # macOS/Linux/Bash: + rm -rf $TMPDIR/metro-* + ``` + + - **Still getting the error?** Double-check these details: + - Open `auth/AuthConfig.ts` and verify your App ID is correctly formatted + - Ensure no extra characters, spaces, or quotes around your App ID + - Check that the file doesn't have any import errors or syntax issues + - Try restarting your code editor/IDE to refresh its cache -## Run the sample +2. **Metro bundler port conflict** + - If port 8081 is in use, start Metro on a different port: + ```bash + npm start -- --port 8082 + ``` -1. Run the following command to start the sample. +3. **iOS build errors** + - Clean build folder: `npx react-native clean` + - Reinstall pods: + ```bash + # Bash/macOS/Linux: + cd ios && pod install && cd .. + # Windows CMD: + cd ios && pod install && cd .. + # Windows PowerShell: + cd ios; pod install; cd .. + ``` + - Make sure you're running these commands from the `GraphRNSample` directory -```bash -npm start +4. **Android build errors** + - Clean gradle cache: + ```bash + # Bash/macOS/Linux: + cd android && ./gradlew clean && cd .. + # Windows CMD: + cd android && gradlew.bat clean && cd .. + # Windows PowerShell: + cd android; .\gradlew.bat clean; cd .. + ``` + - Ensure Android SDK and build tools are installed + - Make sure you're running these commands from the `GraphRNSample` directory + + > **Note**: Build warnings about deprecated APIs or CMake versions are normal and don't prevent the app from running. Look for "BUILD SUCCESSFUL" in the output - that indicates a successful build. + +5. **Authentication issues** + - Verify your App ID is correctly configured in `AuthConfig.ts` + - Ensure the redirect URI matches exactly: `graph-sample://react-native-auth/` + +6. **"Possible Unhandled Promise Rejection" errors** + - This usually indicates an async operation failed without proper error handling + - **To get more details**: + - Check the Metro console (terminal where you ran `npm start`) for full error details + - In the emulator, press `Ctrl+M` (Android) or `Cmd+D` (iOS) and select "Debug" + - Look at the browser console for detailed stack traces + - **Common causes**: + - Authentication failures due to incorrect App ID configuration + - Network connectivity issues preventing Microsoft Graph API calls + - Invalid redirect URI configuration + - Missing internet connection in emulator + - **Solutions**: + - Verify your App ID is correct in `auth/AuthConfig.ts` + - Check that your emulator has internet access + - Ensure the redirect URI in Entra ID matches `graph-sample://react-native-auth/` + - Try authentication on a different network to rule out network issues + +## Project Structure + +``` +msgraph-sample-react-native/ # Root project directory +├── README.md # This file +├── GraphRNSample/ # React Native app directory +│ ├── auth/ # Authentication configuration and management +│ │ ├── AuthConfig.ts # App registration settings (you create this) +│ │ └── AuthManager.ts # Authentication logic +│ ├── graph/ # Microsoft Graph integration +│ │ ├── GraphAuthProvider.ts +│ │ └── GraphManager.ts +│ ├── screens/ # App screens +│ │ ├── SignInScreen.tsx +│ │ ├── HomeScreen.tsx +│ │ ├── CalendarScreen.tsx +│ │ └── NewEventScreen.tsx +│ ├── menus/ # Navigation components +│ ├── images/ # Static assets +│ ├── package.json # Node.js dependencies +│ └── ios/, android/ # Platform-specific code +└── README.md, LICENSE, etc. # Project documentation ``` -1. In another instance of your CLI also in the **GraphRNSample** directory, run one of the following commands: +## Key Dependencies + +- **@microsoft/microsoft-graph-client**: Microsoft Graph SDK for JavaScript +- **react-native-app-auth**: OAuth 2.0 and OpenID Connect client for React Native +- **@react-navigation/**: Navigation library for React Native +- **date-fns**: Modern JavaScript date utility library + +## Learn More + +- [Microsoft Graph documentation](https://docs.microsoft.com/graph/) +- [Microsoft Entra ID documentation](https://docs.microsoft.com/entra/) +- [React Native documentation](https://reactnative.dev/) +- [Microsoft Graph JavaScript SDK](https://github.com/microsoftgraph/msgraph-sdk-javascript) + +## Contributing + +We welcome contributions! Please see our [Contributing Guidelines](CODE_OF_CONDUCT.md) for details. + +## Security + +If you discover a security vulnerability, please follow our [Security Policy](SECURITY.md) for reporting it. + +## License - - To run on an iOS Simulator: `npm run ios` - - To run on an Android virtual device: `npm run android` (start an Android virtual device from Android Studio first) +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Code of conduct