AppAuth-iOS

AppAuth is a best-practice client library for native apps using OAuth and OpenID Connect. Its design principles include:

• Standards-Based: It aims for a 1:1 mapping to official specifications (OAuth 2.0, PKCE, OIDC, etc.) while following language-specific idioms. It does not hide the complexity of the underlying specs.
• No Workarounds: AppAuth implements pure standards. It does not support or work around provider-specific hacks, non-standard protocols, or implementation errors in identity providers. If a provider's implementation deviates from the standard, you should use AppAuth's extension points (like additionalParameters) rather than expecting a core library fix.
• Security First: By sticking to well-researched identity standards, the library maintains a high security posture. It explicitly rejects non-best-practice patterns, such as using embedded WebViews.

AppAuth supports both manual token exchanges and convenience methods. The recommended approach is using convenience methods that return an OIDAuthState object.

OIDAuthState is a central class that:

• Tracks authorization and token requests/responses.
• Provides a convenience method to perform API calls with fresh tokens.
• Is the only object you need to serialize to retain the authorization state of a session across app launches.

The example project requires manual configuration with your Identity Provider (IdP) details to function. You need to provide an Issuer, a Client ID, and a Redirect URI.

1. Update Swift Configuration

In the file AppAuthExampleViewController.swift, update the following constants:

• kIssuer: The IdP's issuer URL.
• kClientID: Your registered client ID.
• kRedirectURI: Your registered redirect URI.

2. Update Info.plist URL Schemes

You must register your redirect URI's scheme in the project's Info.plist so the app can handle the callback:

1. Expand the URL types (CFBundleURLTypes) section.
2. Replace com.example.app with the scheme of your redirect URI.

Note: The scheme is the part of the URI before the colon (:). For example, if your redirect URI is com.example.app:/oauth2redirect/example-provider, the scheme is com.example.app.

AppAuth is designed to be extensible to reduce its core surface area. You can achieve support for non-standard protocols or specific provider requirements through existing extension points:

1. Additional Parameters: Use the additionalParameters dictionary to pass simple extra parameters in requests.
2. Grant Types: The TokenRequest can be used to support grant types beyond the standard ones implemented by the library.

This extensibility allows features like the tvOS device flow to be implemented on top of the core library without modifying the AppAuth source code.

To use the AppAuth sample with the public IdentityServer4 demo instance (https://demo.identityserver.io), update the following constants in your project configuration:

1. Set the kIssuer to the demo URL.
2. Set the kClientID to native.code.
3. Set the kRedirectURI to io.identityserver.demo:/oauthredirect (ensure this matches your app's registered URL scheme in Info.plist).

// set the issuer
static NSString *const kIssuer = @"https://demo.identityserver.io";

// client ID for code flow + PKCE
static NSString *const kClientID =
    @"native.code";

// some redirect URI (must match the plist setting)
static NSString *const kRedirectURI =
    @"io.identityserver.demo:/oauthredirect";

To use AppAuth with Okta, you must first create a Native application in the Okta Admin Console.

1. Navigate to the Okta Admin dashboard and select Create New App.
2. Choose Native as the platform and OpenID Connect as the Sign on method.
3. Configure the following settings:
   • Application Name: A unique name for your app.
   • Redirect URIs: Use a custom scheme format, e.g., com.oktapreview.yoursubdomain://callback_url.
   • Allowed grant types: Select Authorization Code.
4. Assign Users or Groups to the client to ensure they have permission to authenticate.
5. Copy the Client ID provided in the application settings.

You can manually integrate AppAuth as a static library by following these steps:

1. Create an Xcode Workspace.
2. Add AppAuth.xcodeproj to your Workspace.
3. Include libAppAuth as a linked library for your target (under General -> Linked Framework and Libraries).
4. Add AppAuth-iOS/Source to your target's header search paths (Build Settings -> Header Search Paths).

Note: There is no static library available for AppAuthTV.

The example requires your own OpenID Connect (OIDC) client credentials to function. It reads these values from an .xcconfig file.

1. Create a local override file by copying the default configuration:

   cp Config/Example.xcconfig Config/Example.local.xcconfig

2. Edit Config/Example.local.xcconfig to provide your provider's details.
3. If you encounter issues with values not updating, run Product > Clean Build Folder in Xcode to clear cached Info.plist substitutions.

You can configure AppAuth by specifying endpoints directly or via discovery.

Direct Configuration

Specify the authorization and token endpoints manually using OIDServiceConfiguration (iOS/macOS) or OIDTVServiceConfiguration (tvOS).

Discovery

Use the issuer URL to automatically discover endpoints via OIDAuthorizationService.discoverConfiguration(forIssuer:) (iOS/macOS) or OIDTVAuthorizationService (tvOS).