Configure a native iOS application to support Passkeys with Okta by enabling associated domains and adding the application bundle identifier to the Okta organization endpoint. This configuration allows the iOS application to authenticate users using Web Authentication (WebAuthn) Passkeys.

• Okta Identity Engine (OIE)
• iOS
• okta-mobile-swift SDK (idx library)
• Passkeys / Web Authentication (WebAuthn)

What are the prerequisites for configuring Passkeys?

Ensure the environment meets the following prerequisites before configuring the iOS application.

• Configure a Native OpenID Connect (OIDC) application.
• Configure Authentication Policies to allow or require Passkeys (FIDO/WebAuthn).

Review the following documentation for the prerequisite steps.

• iOS IDX Sample App
• Global / Application sign on policies

The following instructions use an Okta organization with a custom domain URL of <app.example.com> and an iOS Application with the Bundle Identifier <com.example.okta-sample.IdxAuthSignInZB7BFQ36KK>.

How does an administrator enable associated domains for the iOS application?

Enable associated domains in XCode and add a new entry for web credentials by following these steps.

1. Navigate to the Project Settings in XCode.
2. Under Signing and Capabilities, check if Associated Domains is enabled.
3. If not enabled, click + Capability and add Associated Domains.
4. Add a new Associated Domain entry for Web Credentials.

Enter the following code to specify the Okta organization domain URL that the application uses.

webcredentials:<app.example.com>?mode=developer

Adding ?mode=developer allows iOS devices to retrieve the apple-app-site-association file from Okta directly (https://<app.example.com>/.well-known/apple-app-site-association) instead of the Apple Content Delivery Network (CDN). Review the Apple Docs for more information.

The following image displays a sample configuration in XCode.

How does an administrator add the iOS application bundle identifier to the organization endpoint?

Use the Okta Admin Dashboard or the Associated Domains Customizations API to add the iOS Application Bundle ID to the appropriate organization brand.

Execute the following API call to add the iOS Application Bundle ID to the appropriate organization brand.

curl --location --request PUT 'https://{ORG}/api/v1/brands/{BRAND_ID}/well-known-uris/apple-app-site-association/customized' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: SSWS 00...' \
--data '{
    "representation": {
      "webcredentials": {
        "apps": [
          "ZB7BFQ36KK.com.example.okta-sample.IdxAuthSignInZB7BFQ36KK"
        ]
      }
    }
}'

Okta adds an entry to the organization /.well-known/apple-app-site-association endpoint for the specified brand.

{
   "authsrv": {
      "apps": [
         "B7xxxxxxxx.com.okta.mobile",
         "B7xxxxxxxx.com.okta.mobile.auth-service-extension",
         "B7xxxxxxxx.com.okta.authenticator.beta",
         "B7xxxxxxxx.com.okta.authenticator.beta.auth-service-extension",
         "7Wxxxxxxxx.com.okta.mobile.internalrelease",
         "7Wxxxxxxxx.com.okta.mobile.internalrelease.auth-service-extension"
      ]
   },
   "webcredentials": {
      "apps": [
         "ZB7BFQ36KK.com.example.okta-sample.IdxAuthSignInZB7BFQ36KK"
      ]
   }
}

What additional steps does developer mode require?

If the associated domain entry specifies ?mode=developer, the device requires enabling the associated domains development setting.

The following image displays the developer settings on an iOS device.

Related References

• Configure Associated Domains
• okta-mobile-swift SDK
• IDX Sample App
• iOS Associated Domains Capability