Overview

General Terms

OAuth 2.0

OAuth 2.0 is a protocol that "...enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf."

OAuth App

System that facilitates the authorization code flow ("three-legged OAuth"). This system supports the generation of an authorization code which is subsequently passed into a request for an access token using the authorization_code grant type.

The term "OAuth App" is used in Apple Business to disambiguate it from a Service Account.

Service Account

System that facilitates access to resources when signed requests for resources are received ("two-legged OAuth"). This system implements the client_credentials grant type.

Overview

An OAuth App ("app") requests authorization to read or modify data in a user's Apple Business account. An app is registered by a third-party partner ("partner") in Apple Business.

A user's first interaction with the partner's app occurs when they decide to link their Apple Business account to their partner's platform account. The partner's platform directs the user to Apple Business. When the user approves a request to link the respective accounts, the partner's platform receives a temporary authorization code.

The partner's platform must use the authorization code within five (5) minutes of receipt and request its exchange for an access token using the authorization_code grant type. For the next sixty (60) minutes, the partner's platform may use this access token to access Apple Business API. A request for an access token using the authorization_code grant type should only occur once.

When the access token expires, the partner requests a new access token using the refresh_token grant type. Thereafter, the partner should only request a new access token using the refresh_token grant type.

Illustration

Availability

• Only a partner that has production API access may create an app.
• Only an Administrator role may create an app.

Dependencies

The Authorization Code and Access Token flows depend upon registration of an app and partner supported features.

Register App in Apple Business

1. Go to your company's profile page, select the "API" tab, and create an app

• Give your app a distinct name
• Add a company member as the contact person for the app
• Add one or more redirection endpoints

Redirection Endpoint

• MUST NOT include a fragment
• MUST NOT include user information
• MUST NOT resolve to a localhost
• MUST be a complete redirect, not a pattern

After successfully registering your app, you're provided with a client_id, and a client_secret which is displayed one time.

Recommendations

• Immediately encrypt the client_secret or store as hashed version, not as plain text.
• Restrict access to the client_secret by requiring "reauthorization" to confirm a user's password before displaying the client_secret.
• If the security of the client_secret is compromised, immediately request a new one.

Partner Supported Features

Successful integration with Apple Business requires the following:

• Code verifier to generate, on demand, a code_verifier value
• Code challenge to derive, on demand, a code_challenge value
• "Link accounts" feature to allow a user to invoke the authorization code flow