Cline rules

1# Agent Instructions: Create iOS/macOS Sample Application with Microsoft Entra ID - External configuration
2 
3## Overview
4 
5These instructions guide agents through creating a sample iOS or macOS application that implements user sign-in using Microsoft Entra External ID for external tenants (customer-facing applications) and calls the Microsoft Graph API.
6 
7## Prerequisites
8 
9Before starting, ensure the following requirements are met:
10 
11### Azure Requirements
12 
13- Active Azure subscription with an active account
14- Permissions to manage applications (requires one of these roles):
15  - Application Administrator
16  - Application Developer
17- An external tenant. To create one, choose from:
18  - Use the [Microsoft Entra External ID extension](https://aka.ms/ciamvscode/samples/marketplace) to set up an external tenant directly in Visual Studio Code _(Recommended)_
19  - [Create a new external tenant](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-create-external-tenant-portal) in the Microsoft Entra admin center
20 
21### Development Environment
22 
23- **iOS**: Version 16 or higher (for iOS apps)
24- **macOS**: Version 11 or higher (for macOS apps)
25- **CocoaPods**: For dependency management
26 
27### Pre-Configuration
28 
29- Register a new application in the Microsoft Entra admin center
30- Configure for "Accounts in this organizational directory only"
31- Record the following values from the application Overview page:
32  - **Application (client) ID**
33  - **Directory (tenant) ID**
34  - **Tenant Subdomain** (e.g., if your tenant primary domain is `contoso.onmicrosoft.com`, the subdomain is `contoso`)
35 
36### Additional Requirements
37 
38- A user flow configured for self-service sign-up
39- The application must be added to the user flow
40 
41## Step 1: Register Application in Microsoft Entra Admin Center
42 
43### 1.1 Create App Registration
44 
451. Navigate to the [Microsoft Entra admin center](https://entra.microsoft.com)
462. Select **Applications** > **App registrations** > **New registration**
473. Enter a name for your application
484. Select "Accounts in this organizational directory only" as the supported account types
495. Click **Register**
506. Save the **Application (client) ID** and **Directory (tenant) ID** from the Overview page
51 
52### 1.2 Get Tenant Details
53 
541. Note your tenant's primary domain (e.g., `contoso.onmicrosoft.com`)
552. Extract the subdomain portion (e.g., `contoso`)
563. Save this subdomain for later configuration
57 
58### 1.3 Configure Platform (iOS/macOS)
59 
601. Under **Manage**, select **Authentication** > **Add Platform** > **iOS / macOS**
612. Enter your **Bundle Identifier**
62   - For the sample code: `com.microsoft.identitysample.ciam.MSALiOS`
63   - For custom apps: Use your unique identifier (e.g., `com.yourcompany.appname`)
643. Click **Configure** and save the **MSAL Configuration** details
654. Click **Done**
66 
67### 1.4 Enable Public Client Flow
68 
691. Under **Manage**, select **Authentication**
702. Scroll to **Advanced settings**
713. For **Allow public client flows**, select **Yes**
724. Click **Save**
73 
74## Step 2: Configure User Flow
75 
76### 2.1 Create User Flow
77 
781. In the Microsoft Entra admin center, navigate to **External Identities** > **User flows**
792. Click **New user flow**
803. Select **Sign up and sign in** as the user flow type
814. Configure the user flow:
82   - Name the user flow
83   - Select identity providers (e.g., Email and password)
84   - Choose user attributes to collect during sign-up
85   - Configure optional claims
865. Click **Create**
87 
88### 2.2 Add Application to User Flow
89 
901. Open your created user flow
912. Select **Applications**
923. Click **Add application**
934. Select your registered application
945. Click **Add**
95 
96For detailed instructions, see:
97 
98- [Create self-service sign-up user flows](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-user-flow-sign-up-sign-in-customers)
99- [Add application to user flow](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-user-flow-add-application)
100 
101## Step 3: Download Sample Code
102 
103### 3.1 Clone the Repository
104 
105Open Terminal and run the following command:
106 
107```bash
108git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-ios-sample.git
109cd ms-identity-ciam-browser-delegated-ios-sample
110```
111 
112Alternatively, download as a ZIP file:
113 
114```bash
115curl -L https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-ios-sample/archive/refs/heads/main.zip -o ios-ciam-sample.zip
116unzip ios-ciam-sample.zip
117cd ms-identity-ciam-browser-delegated-ios-sample-main
118```
119 
120## Step 4: Install Dependencies
121 
122### 4.1 Install MSAL Library
123 
1241. Navigate to the project directory in Terminal
1252. Run CocoaPods to install the Microsoft Authentication Library (MSAL):
126```bash
127pod install
128```
1293. Wait for the installation to complete
130 
131### 4.2 Open Workspace
132 
133After pod installation, open the `.xcworkspace` file:
134 
135```bash
136open *.xcworkspace
137```
138 
139**Important**: Always use the `.xcworkspace` file, not the `.xcodeproj` file when working with CocoaPods.
140 
141## Step 5: Configure the Application
142 
143### 5.1 Update Configuration.swift
144 
1451. In Xcode, locate and open **/MSALiOS/Configuration.swift**
1462. Replace the placeholders with your values:
147 
148```swift
149// Replace Enter_the_Application_Id_Here with your Application (client) ID
150let kClientID = "YOUR_APPLICATION_CLIENT_ID_HERE"
151 
152// Replace Enter_the_Redirect_URI_Here with your redirect URI
153// This should match the MSAL configuration from the portal
154let kRedirectUri = "msauth.com.microsoft.identitysample.ciam.MSALiOS://auth"
155 
156// Replace Enter_the_Tenant_Subdomain_Here with your tenant subdomain
157// For example, if your domain is contoso.onmicrosoft.com, use "contoso"
158let kTenantSubdomain = "YOUR_TENANT_SUBDOMAIN"
159 
160// Replace Enter_the_Protected_API_Scopes_Here with your API scopes
161// If you haven't configured any scopes yet, you can leave this empty
162let kScopes = ["YOUR_API_SCOPES_HERE"]
163// Example: let kScopes = ["api://YOUR_CLIENT_ID/ToDoList.Read", "api://YOUR_CLIENT_ID/ToDoList.ReadWrite"]
164```
165 
166### 5.2 Configure Bundle Identifier
167 
1681. In Xcode, select the project in the navigator
1692. Select your target
1703. Go to the **General** tab
1714. In the **Identity** section, verify the **Bundle Identifier** matches what you registered in the Azure portal
172   - Default sample: `com.microsoft.identitysample.ciam.MSALiOS`
173 
174### 5.3 Update Info.plist (if needed)
175 
176The Info.plist should already be configured correctly for the sample. If you're using a custom Bundle Identifier:
177 
1781. Right-click **Info.plist** in the project navigator
1792. Select **Open As** > **Source Code**
1803. Find the `CFBundleURLTypes` section
1814. Ensure the URL scheme matches your configuration:
182 
183```xml
184<key>CFBundleURLTypes</key>
185<array>
186   <dict>
187      <key>CFBundleURLSchemes</key>
188      <array>
189         <string>msauth.YOUR_BUNDLE_IDENTIFIER</string>
190      </array>
191   </dict>
192</array>
193```
194 
195## Step 6: Grant Admin Consent (if required)
196 
197If your application requires API permissions:
198 
1991. In the Microsoft Entra admin center, go to your app registration
2002. Under **Manage**, select **API permissions**
2013. Review the configured permissions
2024. Click **Grant admin consent for [your tenant]**
2035. Confirm the consent
204 
205For more details, see [Grant admin consent](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#grant-admin-consent-external-tenants-only).
206 
207## Step 7: Build and Run the Application
208 
209### 7.1 Build the Project
210 
2111. Select your target device or simulator from the scheme selector
2122. Click the **Build** button (⌘+B) or select **Product** > **Build**
2133. Verify there are no build errors
214 
215### 7.2 Run the Application
216 
2171. Select **Product** > **Run** from the menu (or press ⌘+R)
2182. The app will launch in the simulator or on your connected device
219 
220### 7.3 Test Authentication
221 
2221. When the app launches, you'll see the main interface
2232. Click **Acquire Token Interactively**
2243. A browser or web view will open with your configured sign-in experience
2254. Complete the sign-up or sign-in process:
226   - For new users: Fill in required attributes during sign-up
227   - For existing users: Enter credentials
2285. After successful authentication, you'll be redirected back to the app
2296. The app will display user information and the access token
230 
231### 7.4 Test API Calls
232 
2331. Click **API - Perform GET** to test calling a protected API
2342. Note: If you haven't configured a protected API yet, you may receive an error
2353. For testing purposes, you can use Microsoft Graph API or deploy a custom API
236 
237## Step 8: Understanding the External Tenant Flow
238 
239### Authentication Flow for External Tenants
240 
241```
242User opens app
243        ↓
244User clicks "Acquire Token Interactively"
245        ↓
246App initiates MSAL authentication with external tenant
247        ↓
248Browser/Web view opens with custom sign-up/sign-in UI
249        ↓
250New user: Sign-up flow with attribute collection
251Existing user: Sign-in with credentials
252        ↓
253External tenant validates credentials
254        ↓
255User grants consent (if needed)
256        ↓
257Redirect back to app with authorization code
258        ↓
259MSAL exchanges code for access token
260        ↓
261App receives access token and ID token
262        ↓
263App can call protected APIs
264```
265 
266### Key Differences from Workforce Tenants
267 
268- **User Flows**: External tenants use customizable user flows for sign-up/sign-in
269- **Self-Service Registration**: Users can sign up without admin pre-creation
270- **Branding**: Fully customizable sign-up/sign-in experience
271- **Identity Providers**: Can configure social identity providers (Google, Facebook, etc.)
272- **Attribute Collection**: Configure which user attributes to collect during sign-up
273 
274## Step 9: Testing the Application
275 
276### 9.1 Test New User Sign-Up
277 
2781. Launch the app
2792. Click **Acquire Token Interactively**
2803. On the sign-in page, click **Sign up now** or similar link
2814. Fill in required attributes (email, password, etc.)
2825. Complete email verification if configured
2836. Verify successful account creation and sign-in
2847. Check that user information is displayed in the app
285 
286### 9.2 Test Existing User Sign-In
287 
2881. Launch the app (or sign out if already signed in)
2892. Click **Acquire Token Interactively**
2903. Enter credentials for an existing user
2914. Verify successful sign-in
2925. Check that user information is displayed
293 
294### 9.3 Test Silent Token Acquisition
295 
2961. After initial sign-in, restart the app
2972. Click **Acquire Token Silently**
2983. Verify token is obtained without user interaction
2994. This validates token caching and refresh token functionality
300 
301### 9.4 Test API Access
302 
303If you've configured a protected API:
304 
3051. Click **API - Perform GET**
3062. Verify successful API call with the acquired token
3073. Check the response data
308 
309## Step 10: Customize Branding and User Experience
310 
311### 10.1 Customize Branding
312 
3131. In the Microsoft Entra admin center, go to **Company branding**
3142. Configure:
315   - Logo and background images
316   - Colors and themes
317   - Custom text and messages
3183. Save changes
3194. Test the updated branding in your app
320 
321For details, see [Customize the default branding](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-customize-branding-customers).
322 
323### 10.2 Configure Social Identity Providers
324 
325Add social sign-in options (Google, Facebook, etc.):
326 
3271. In the Microsoft Entra admin center, go to **External Identities** > **All identity providers**
3282. Click **New identity provider**
3293. Select the provider (e.g., Google)
3304. Configure the provider settings
3315. Add the provider to your user flow
332 
333For details, see [Configure sign-in with Google](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-google-federation-customers).
334 
335## Step 11: Common Configuration Issues
336 
337### Issue: "Invalid tenant subdomain"
338 
339- **Solution**: Verify the tenant subdomain in Configuration.swift
340- Ensure no extra spaces or characters
341- Check that it matches your tenant's primary domain
342 
343### Issue: "Application not found in user flow"
344 
345- **Solution**: Verify the app is added to the user flow
346- Check that the user flow is active
347- Ensure the correct user flow is configured
348 
349### Issue: "Redirect URI mismatch"
350 
351- **Solution**: Verify Bundle Identifier matches Azure portal configuration
352- Ensure the redirect URI in Configuration.swift matches the portal
353- Check that URL scheme in Info.plist is correct
354 
355### Issue: "Invalid client"
356 
357- **Solution**: Double-check Application (client) ID in Configuration.swift
358- Ensure the app registration exists in the correct tenant
359- Verify no extra spaces or characters
360 
361### Issue: "Scopes not granted"
362 
363- **Solution**: Verify API permissions are configured
364- Grant admin consent if required
365- Check that scopes in Configuration.swift match configured permissions
366 
367### Issue: "Pod install fails"
368 
369- **Solution**: Update CocoaPods: `sudo gem install cocoapods`
370- Clear pod cache: `pod cache clean --all`
371- Try again: `pod install`
372 
373### Issue: "Sign-up attributes not appearing"
374 
375- **Solution**: Check user flow configuration
376- Verify required attributes are selected
377- Ensure custom attributes are defined if needed
378 
379## Step 12: Next Steps
380 
381After successfully building and running the sample:
382 
383### Implement Protected API Calls
384 
385- Follow the tutorial: [Sign in users and call a protected web API in sample iOS (Swift) app](https://learn.microsoft.com/en-us/entra/external-id/customers/sample-mobile-app-ios-swift-sign-in-call-api)
386- Deploy an ASP.NET Core web API
387- Configure API permissions and scopes
388- Implement authenticated API calls from the mobile app
389 
390### Enhance User Experience
391 
392- Customize the in-app UI after authentication
393- Implement user profile management
394- Add password reset functionality
395- Configure multi-factor authentication
396 
397### Add Advanced Features
398 
399- Implement token refresh strategies
400- Add offline support with cached tokens
401- Integrate biometric authentication (Face ID, Touch ID)
402- Add logging and analytics
403 
404### Production Readiness
405 
406- Implement comprehensive error handling
407- Add retry logic for network failures
408- Configure app transport security
409- Implement certificate pinning
410- Add crash reporting and monitoring
411 
412## Step 13: Additional Resources
413 
414### Documentation
415 
416- **External ID Overview**: [Microsoft Entra External ID documentation](https://learn.microsoft.com/en-us/entra/external-id/)
417- **MSAL for iOS/macOS**: [Microsoft Authentication Library for iOS and macOS](https://github.com/AzureAD/microsoft-authentication-library-for-objc)
418- **User Flows**: [User flows for external tenants](https://learn.microsoft.com/en-us/entra/external-id/customers/concept-user-flows)
419- **API Protection**: [Protect an API in external tenants](https://learn.microsoft.com/en-us/entra/external-id/customers/tutorial-protect-web-api-dotnet-core-build-app)
420 
421### Sample Applications
422 
423- **iOS Sample**: [ms-identity-ciam-browser-delegated-ios-sample](https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-ios-sample)
424- **macOS Sample**: Available in the same repository with platform-specific configurations
425 
426### Best Practices
427 
428- **Security**: [Security best practices for external tenants](https://learn.microsoft.com/en-us/entra/external-id/customers/concept-security-customers)
429- **User Experience**: [UX best practices for customer-facing apps](https://learn.microsoft.com/en-us/entra/external-id/customers/concept-branding-customers)
430- **Token Management**: [Token lifetimes and policies](https://learn.microsoft.com/en-us/entra/identity-platform/configurable-token-lifetimes)
431 
432## Step 14: Security Considerations for External Tenants
433 
434### Authentication Security
435 
4361. **Use strong password policies**: Configure in user flow settings
4372. **Enable MFA**: Add multi-factor authentication to user flows
4383. **Implement account protection**: Configure suspicious activity detection
4394. **Rate limiting**: Protect against brute force attacks
440 
441### Token Security
442 
4431. **Minimal scopes**: Request only necessary API permissions
4442. **Token validation**: Always validate tokens server-side
4453. **Secure storage**: Use iOS Keychain for token storage
4464. **Token refresh**: Implement proper token refresh logic
4475. **Revocation**: Support token and session revocation
448 
449### Data Protection
450 
4511. **HTTPS only**: Ensure all communication uses HTTPS
4522. **Certificate pinning**: Consider implementing for production
4533. **Data encryption**: Encrypt sensitive data at rest
4544. **PII handling**: Follow privacy regulations (GDPR, CCPA)
455 
456### App Security
457 
4581. **Code obfuscation**: Protect sensitive logic in production
4592. **Jailbreak detection**: Consider detecting compromised devices
4603. **Input validation**: Validate all user inputs
4614. **Secure coding**: Follow OWASP Mobile Security guidelines
462 
463---
464 
465**Source**: [Microsoft Learn - Quickstart: Sign in users in a sample mobile app (External Tenants)](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-mobile-app-sign-in?tabs=ios-macos-external&pivots=external)
466