auth0-net-ios

What this skill does

# auth0-net-ios Integration

Add Auth0 authentication to .NET iOS applications. This skill integrates the `Auth0.OidcClient.iOS` NuGet package which uses `ASWebAuthenticationSession` for secure OIDC-based login and logout flows with PKCE.

> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
> ```bash
> gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("ios-")) | .tag_name | ltrimstr("ios-")] | .[0]'
> ```
> Use the returned version in all dependency lines instead of any hardcoded version below.

## Prerequisites

- .NET 8.0 SDK or later (.NET 9 also supported — use `net9.0-ios` target framework)
- JetBrains Rider or VS Code with C# Dev Kit (with iOS workload)
- macOS with Xcode 15+
- iOS 14.0+ deployment target
- Auth0 account with a Native application configured
- Node.js 20+ (for Auth0 CLI automated setup)

## When NOT to Use

| Use Case | Recommended Skill |
|----------|------------------|
| .NET MAUI cross-platform app (iOS + Android + Windows) | `auth0-maui` |
| .NET Android-only app | `auth0-net-android` |
| iOS-only Swift app | `auth0-swift` |
| ASP.NET Core server-side web app | `auth0-aspnetcore-authentication` |
| ASP.NET Core Web API (JWT validation) | `auth0-aspnetcore-api` |
| React Native mobile app | `auth0-react-native` |

## Quick Start Workflow

> **Agent instruction:** Before starting, examine the user's project:
> 1. Identify the .NET version from the `.csproj` file (`TargetFramework`)
> 2. Check for existing authentication implementations — search for existing login/logout handlers and hook into them if found (reuse existing UI elements like login buttons rather than creating duplicates)
> 3. Note the project's Bundle Identifier from `Info.plist` or `.csproj`
> 4. Look for existing `Auth0Client` or `Auth0ClientOptions` usage to avoid duplicate configuration

1. **Install SDK**: `dotnet add package Auth0.OidcClient.iOS`
2. **Configure Auth0**: See [Setup Guide](./references/setup.md) for automatic or manual configuration.
3. **Integrate authentication**: Add `Auth0Client` instantiation, register the URL scheme in `Info.plist`, and wire login/logout to UI actions.
4. **Handle callback**: Implement `OpenUrl` in `AppDelegate` and call `ActivityMediator.Instance.Send(url.AbsoluteString)`.
5. **Build and verify**: `dotnet build`

> **Agent instruction:** When writing the Auth0Client configuration:
> - The iOS SDK does NOT require passing an Activity context — just `new Auth0Client(options)`.
> - **Always set `Scope = "openid profile email offline_access"`** — the `offline_access` scope is required to receive refresh tokens, enabling silent token renewal without re-prompting the user.
> - The callback URL is automatically derived from the Bundle Identifier: `{BundleId}://{domain}/ios/{BundleId}/callback`.
> - The Bundle Identifier must be registered as a URL scheme in `Info.plist`.
> - The `AppDelegate` must handle `OpenUrl` and call `ActivityMediator.Instance.Send(url.AbsoluteString)`.
> - **Store tokens securely**: After successful login, persist `AccessToken` and `RefreshToken` using iOS Keychain (via `Security` framework or a wrapper like `KeychainAccess`). Never store tokens in `UserDefaults` or in-memory variables only.
>
> After writing configuration and code, verify the build succeeds:
> ```bash
> dotnet build
> ```
> If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.

## WebAuth — How Authentication Works

The SDK uses ASWebAuthenticationSession (the secure system browser). When `LoginAsync()` is called:

1. SDK constructs the `/authorize` URL with PKCE parameters (code verifier + challenge)
2. ASWebAuthenticationSession opens showing the Auth0 login page
3. User authenticates (login form, social connections, MFA, etc.)
4. Auth0 redirects to the native callback URL: `{BundleId}://{domain}/ios/{BundleId}/callback`
5. iOS intercepts the URL scheme and delivers it to `AppDelegate.OpenUrl`
6. `ActivityMediator.Instance.Send(url.AbsoluteString)` completes the token exchange
7. SDK returns `LoginResult` with access token, ID token, refresh token, and user claims

This is the standard OAuth 2.0 Authorization Code flow with PKCE, recommended for native mobile applications.

## Callback URL Configuration

The native callback URL for .NET iOS uses the Bundle Identifier as the scheme. The format is:

```text
YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback
```

Where `YOUR_BUNDLE_IDENTIFIER` is the Bundle Identifier for your application, such as `com.mycompany.myapplication`. For example: `com.mycompany.myapp://tenant.us.auth0.com/ios/com.mycompany.myapp/callback`.

> **Note:** Some Auth0 native SDKs use `https://{domain}/ios/{bundleId}/callback` or `{bundleId}.auth0://{domain}/ios/{bundleId}/callback` as the callback URL format. The .NET iOS SDK uses the Bundle Identifier directly as the URL scheme.

Ensure that the Callback URL is in lowercase.

This URL must be:
1. Registered in Auth0 Dashboard under **Allowed Callback URLs** and **Allowed Logout URLs**
2. Registered as a URL scheme in `Info.plist` under `CFBundleURLSchemes`

## Done When

- [ ] `Auth0.OidcClient.iOS` package installed (latest stable version)
- [ ] `Auth0Client` configured with Domain, ClientId, and `Scope = "openid profile email offline_access"`
- [ ] URL scheme registered in `Info.plist` matching the Bundle Identifier
- [ ] `AppDelegate.OpenUrl` implemented with `ActivityMediator.Instance.Send(url.AbsoluteString)`
- [ ] Callback URL added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs
- [ ] Tokens stored securely using iOS Keychain (`Security` framework with `SecKeyChain.Add`)
- [ ] Login/logout flow working
- [ ] Build succeeds with no errors

## Detailed Documentation

- **[Setup Guide](./references/setup.md)** — Auth0 tenant configuration, SDK installation, Info.plist URL scheme setup
- **[Integration Patterns](./references/integration.md)** — Login/logout flows, token access, user profile, error handling
- **[API Reference & Testing](./references/api.md)** — Full `Auth0ClientOptions` reference, claims, testing checklist, troubleshooting

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
| Missing callback URL in Auth0 Dashboard | Add `yourbundleid://{domain}/ios/yourbundleid/callback` to Allowed Callback URLs AND Allowed Logout URLs |
| Missing URL scheme in Info.plist | Add `CFBundleURLSchemes` entry matching your Bundle Identifier |
| Not handling `OpenUrl` in AppDelegate | Override `OpenUrl` and call `ActivityMediator.Instance.Send(url.AbsoluteString)` |
| Using `https://` prefix in Domain | Domain should be hostname only (e.g., `tenant.auth0.com`, not `https://tenant.auth0.com`) |
| Passing Activity context to Auth0Client (Android pattern) | iOS does not need context — just `new Auth0Client(options)` |
| URL scheme not matching Bundle Identifier | The CFBundleURLSchemes value must exactly match the Bundle Identifier |
| Storing tokens in `UserDefaults` or only in memory | Use iOS Keychain via the `Security` framework (`SecKeyChain.Add`) for token persistence |

## Testing Notes

> **Agent instruction:** Remind the user to test on a physical device in addition to simulators. Some WebAuth/ASWebAuthenticationSession behaviors may differ on physical devices vs. simulators. Test the full login → callback → token flow on real hardware before shipping.

**Physical Device Testing:**
- Login flow: ASWebAuthenticationSession opens → authenticate → returns to app
- Callback: `OpenUrl` fires in AppDelegate with correct URL
- Logout flow: Browser opens → session cleared → returns to app
- Cancel: User dismisses sheet → app handles `UserCancel` gracefully

## Related Skills

- **auth0-maui** — .NET MAUI cross-platform apps (iOS + Android + Windows)
- **auth0-ne