IPATool Authentication Methods: Store Authentication Protocol (SAP) and Keychain Storage

IPATool authenticates with Apple's App Store using the Store Authentication Protocol (SAP), supporting email and password login with optional two-factor authentication (2FA), persisting credentials in the macOS keychain, and providing explicit revocation commands.

The majd/ipatool command-line interface implements a secure authentication workflow for accessing iOS app packages from the App Store. Understanding the authentication methods provided by IPATool requires examining how the tool leverages Apple's proprietary Store Authentication Protocol alongside native macOS security features. The implementation spans multiple packages including core appstore logic, SAP cryptographic signing, and system keychain integration.

Store Authentication Protocol (SAP) Login Flow

The primary authentication method uses SAP to communicate with Apple's authentication endpoint at /WebObjects/MZFinance.woa/wa/authenticate. Located in pkg/appstore/appstore_login.go, the Login function orchestrates a multi-step cryptographic handshake that establishes a trusted session with Apple's servers.

Machine Identity and Configuration Bag

Before transmitting credentials, IPATool establishes a machine identity using the device MAC address to generate a GUID and machine ID. The pkg/appstore/appstore_bag.go file implements bag retrieval, fetching SAP configuration from Apple's servers to obtain the AuthEndpoint and other protocol parameters required for the authentication sequence.

Cryptographic Request Signing

The internal/sap/signer.go file implements the SAP action signer, which cryptographically signs login requests according to Apple's protocol requirements. This signing process ensures the authentication payload meets Apple's security standards before transmission to the App Store servers.

Authentication Transmission and Retry Logic

The sendAuthenticationRequest function in pkg/appstore/appstore_login.go handles the actual HTTP transmission, implementing retry logic for transient HTTP errors (204 and 5xx status codes) and following pod redirects automatically. When Apple redirects to a different authentication pod, parseLoginResponse validates that the redirect URL points to the expected authentication path (/WebObjects/MZFinance.woa/wa/authenticate) before retrying the login request with the new pod URL.

Two-Factor Authentication (2FA) Handling

When Apple requires additional verification, the login flow returns ErrAuthCodeRequired. Users must then retry the login with the AuthCode field populated. The cmd/auth.go file contains loginCmd, which orchestrates interactive prompting for 2FA codes when the initial authentication attempt indicates multi-factor authentication is required.

The following example demonstrates the interactive login flow:

// CLI command: `ipatool auth login -e user@example.com -p secret`
output, err := dependencies.AppStore.Login(appstore.LoginInput{
    Email:    "user@example.com",
    Password: "secret",
    AuthCode: "", // Omitted - will be requested if Apple asks for 2FA
})
if err != nil {
    // Handle errors such as appstore.ErrAuthCodeRequired
}
fmt.Printf("Logged in as %s (%s)\n", output.Account.Name, output.Account.Email)

When 2FA is required, provide the code on the second attempt:

// First attempt fails with ErrAuthCodeRequired → retry with auth code
output, err := dependencies.AppStore.Login(appstore.LoginInput{
    Email:    "user@example.com",
    Password: "secret",
    AuthCode: "123456", // 2FA code from Apple
})

Credential Storage in macOS Keychain

After successful authentication, IPATool persists account data using the macOS keychain. The Account struct—containing the user's name, email, password-token, directory-services ID, storefront, and pod information—is marshalled to JSON and stored under the service name ipatool-auth.service.

The pkg/keychain/keychain.go file provides the generic wrapper for these operations, while pkg/appstore/appstore_account_info.go implements the AccountInfo method for retrieving stored credentials. Subsequent CLI commands access this stored data without requiring re-entry of the Apple ID password.

Retrieve stored account information using:

info, err := dependencies.AppStore.AccountInfo()
if err != nil {
    // No stored credentials or keychain error
}
fmt.Printf("Current account: %s (%s)\n", info.Account.Name, info.Account.Email)

Revoking Authentication

To terminate an authenticated session, IPATool provides the revocation method implemented in pkg/appstore/appstore_revoke.go. The Revoke function deletes the stored "account" entry from the keychain, effectively logging the user out. This is exposed through the revokeCmd in cmd/auth.go.

Execute revocation using:

if err := dependencies.AppStore.Revoke(); err != nil {
    // Handle revocation error
}
fmt.Println("Credentials revoked – you are now logged out")

Summary

• Store Authentication Protocol (SAP) provides the cryptographic foundation for IPATool's authentication with Apple's /WebObjects/MZFinance.woa/wa/authenticate endpoint.
• Three core operations comprise the authentication interface: Login (with optional 2FA), AccountInfo (keychain retrieval), and Revoke (credential deletion).
• Machine identity is derived from the device MAC address to generate GUIDs and authentication tokens as implemented in pkg/appstore/appstore_login.go.
• macOS keychain securely persists JSON-encoded account data under the service name ipatool-auth.service, eliminating the need for repeated password entry.
• Pod redirect handling and transient error retry logic ensure robust authentication across Apple's distributed infrastructure.

Frequently Asked Questions

How does IPATool handle two-factor authentication?

IPATool detects 2FA requirements through the ErrAuthCodeRequired error returned by parseLoginResponse in pkg/appstore/appstore_login.go. When this error occurs, the CLI prompts for a 2FA code and retries the authentication request with the AuthCode field populated in the LoginInput struct.

Where does IPATool store my Apple ID credentials?

IPATool stores credentials in the macOS keychain under the service name ipatool-auth.service. The implementation in pkg/keychain/keychain.go handles the secure storage of JSON-encoded account data including authentication tokens, eliminating the need to store plaintext passwords in configuration files.

What protocol does IPATool use to authenticate with Apple?

IPATool uses Apple's proprietary Store Authentication Protocol (SAP). The implementation involves cryptographic request signing via internal/sap/signer.go and configuration retrieval through the bag endpoint as defined in pkg/appstore/appstore_bag.go.

How do I completely log out of IPATool?

Execute the ipatool auth revoke command, which calls the Revoke function in pkg/appstore/appstore_revoke.go. This removes the account entry from the macOS keychain, invalidating the stored authentication tokens and requiring fresh credentials on the next login attempt.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}