# Auth0 Net Ios

> >

- **Type:** Skill
- **Install:** `agentstack add skill-auth0-agent-skills-auth0-net-ios`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [auth0](https://agentstack.voostack.com/s/auth0)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [auth0](https://github.com/auth0)
- **Source:** https://github.com/auth0/agent-skills/tree/main/plugins/auth0/skills/auth0-net-ios

## Install

```sh
agentstack add skill-auth0-agent-skills-auth0-net-ios
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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-net-android** — .NET Android-only apps
- **auth0-swift** — iOS-only Swift apps
- **auth0-aspnetcore-authentication** — ASP.NET Core server-side web apps
- **auth0-aspnetcore-api** — ASP.NET Core Web API with JWT validation

## Quick Reference

```csharp
using Auth0.OidcClient;

var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    Scope = "openid profile email offline_access"
});

var loginResult = await client.LoginAsync();
BrowserResultType browserResult = await client.LogoutAsync();
```

> **Agent instruction:** Always include `offline_access` in the scope to enable refresh tokens. This allows the app to silently refresh access tokens without forcing the user to re-authenticate.
>
> **Agent instruction:** After login, always persist tokens to the iOS Keychain using the `Security` framework (`SecKeyChain.Add` with `SecAccessible.WhenUnlockedThisDeviceOnly`). Never store tokens in `UserDefaults` or leave them only in memory. Clear tokens on logout. See [Integration Patterns](./references/integration.md) for the full `SecureTokenStorage` helper class.

### Required Platform Configuration

These two pieces are required for the callback to work — see [Setup Guide](./references/setup.md) for full code:

1. **Info.plist**: Add `CFBundleURLSchemes` entry matching the Bundle Identifier
2. **AppDelegate**: Override `OpenUrl` and call `ActivityMediator.Instance.Send(url.AbsoluteString)`

For login with extra parameters, error handling, token refresh, user claims access, and complete ViewController examples, see [Integration Patterns](./references/integration.md).

## References

- [.NET Android & iOS Quickstart](https://auth0.com/docs/quickstart/native/net-android-ios)
- [GitHub Repository](https://github.com/auth0/auth0-oidc-client-net)
- [NuGet Package — Auth0.OidcClient.iOS](https://www.nuget.org/packages/Auth0.OidcClient.iOS)
- [SDK API Documentation](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html)
- [Auth0 Native App Documentation](https://auth0.com/docs/get-started/auth0-overview/create-applications/native-apps)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [auth0](https://github.com/auth0)
- **Source:** [auth0/agent-skills](https://github.com/auth0/agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-auth0-agent-skills-auth0-net-ios
- Seller: https://agentstack.voostack.com/s/auth0
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.