App Attestation¶

Introduction¶

SAP BTP SDK for iOS v9.1 introduces app attestation (called "managed device attestation" in Apple documentation), a security feature that allows app developers to verify the integrity of their app on a user's device. This is achieved using a cryptographic key that is unique to the device and the app.

Using app attestation, when a user's device requests access to a server-side API, SAP Mobile Services verifies that the request is coming from a legitimate instance of the app on a legitimate device.

This helps to prevent unauthorized access to the server-side API, as an attacker would need both the app and the device's cryptographic key to access the server-side API.

How It Works¶

The SAP BTP SDK for iOS uses Apple's DeviceCheck framework to perform attestation and assertion. The complete process is explained in Establishing your app’s integrity

The SDK verifies the result of attestation and assertion with SAP Mobile Services. An attestation token is issued by SAP Mobile Services after successfully verifying the result of assertion.

The SDK then adds the attestation token to each request that is sent from the application.

Enabling App Attestation¶

You can enable app attestation by using SAP BTP SDK Assistant for iOS v9.1 or by filling in the required information and enabling iOS Attestation in the Attestation tab in mobile services cockpit.

iOS Attestation Settings

Once attestation is enabled, add the newly introduced ApplicationAttestationStep to the onboardingSteps and restoringSteps in OnboardingFlowProvider.swift, right after the authentication step.

For example, for an app with OAuth2 authentication:

    public var onboardingSteps: [OnboardingStep] {
        return [
            ...
            OAuth2AuthenticationStep(),
            ApplicationAttestationStep(),
            ...
        ]
    }

    public var restoringSteps: [OnboardingStep] {
        return [
            ...
            OAuth2AuthenticationStep(),
            ApplicationAttestationStep(),
            ...
        ]
    }

Note

If you use SAP BTP SDK Assistant for iOS v9.1, the required code is automatically added as part of the app generation process.

You can also use AttestationObserver from SAPFoundation instead of the ApplicationAttestationStep if you prefer.

Initialize an instance of AttestationObserver and register it to SAPURLSession

    do {
        // Create an instance of `AttestationService` using the initializer.
         let service = try AttestationService(sapCpmsSettingsParameters: settingsParameters,
         sapUrlSession: urlSession, store: persistentStore, attestationSettings: settings)

         // Create an instance of `AttestationObserver` using the service.
         let observer = AttestationObserver(attestationService: service)
         sapURLSession.register(observer)
     } catch {
         // catch error
     }

When attestation is enforced, the initializer for AttestationService throws AttestationError.debugTokenPreconditionFailed if any of the requirements for using a debug token are not fulfilled.

Once the code changes have been made, add the app attestation capability to the application target. This adds an App Attest Environment key to the entitlement file with a string value denoting the environment that will be used for attestation.

App Attestation Entitlements

Note

If you have a large user base for your app, Apple recommends enabling attestation in stages to avoid overwhelming Apple servers.

Enforcing App Attestation¶

After you enable attestation, you can enforce it in mobile services cockpit. Enforcing attestation makes it compulsory for a request to have an attestation token in the request header. Otherwise, SAP Mobile Services rejects the request.

Debug Token¶

SAP Mobile Services Cockpit provides support for a debug token that can be used to run attestation-enabled apps on platforms where the App Attest service from Apple is not supported, such as the iOS Simulator, Mac Catalyst, or physical devices.

Starting with version 9.2, SAP BTP SDK for iOS supports the debug token. When a debug token is added to a request header, the attestation check is skipped in mobile services cockpit.

Note

The debug token should only be used during development, as it skips the attestation check on mobile services cockpit.

To use the debug token, the admin needs to enable attestation in the mobile services cockpit and generate a debug token. Additionally, there are specific requirements that need to be met for using the debug token, as described below.

Requirements¶

In Xcode, add the '-AppAttestDebugEnabled' argument to the Run action of the application scheme in Arguments Passed on Launch.
Add the 'App Attest Debug Token' key in AppParameters.plist with the value of the debug token from mobile services cockpit.

The debug token can also be used on a physical device if all the requirements are met.

Warning

Please ensure that you remove the requirements for using a debug token when releasing your app to the App Store. Otherwise, the debug token will always be used, and the legitimacy of the app on the user's device cannot be verified.

How the Debug Token Is Used¶

During the initialization of AttestationService, the usage of the debug token is determined based on the requirements for its use and the platform's support for the App Attest service.

Once the requirements are fulfilled, if the physical device supports App Attest, the application will not go through the regular attestation and assertion flow to obtain an attestation token from mobile services cockpit. Instead, it will use the supplied debug token and add it to the request header.
If the requirements are not fulfilled and the physical device supports App Attest, then it will go through the normal app attestation and assertion flow as described in How It Works.
For platforms where App Attest is not supported, if the conditions are met, then the debug token will be used. If any of the requirements are not met, and attestation is enforced, then AttestationError.debugTokenPreconditionFailed is thrown when initializing AttestationService, with an associated value of the reason for the failure.

Last update: June 12, 2023