# Connect Apple Business to Trustaige

> Make Trustaige the sign-in for your Managed Apple Accounts, sync the accounts from your directory, and send Apple your security events.

Source: https://docs.trustaige.com/manage/apple-business

Apple Business lets you choose the identity provider your organization's
Managed Apple Accounts sign in with. Choose Trustaige, and your people sign in
to their iPhone, iPad, Mac, Apple Vision Pro, Shared iPad and iCloud on the web
with the passkey they already use for everything else. Nobody is issued an Apple
password, so there is none to forget, reset or phish.

Apple builds this on three open standards. You set each one up yourself, in an
app you create in the hub, so you can see exactly what each connection does and
change it later:

| Connection | Standard | Direction | What it does |
|---|---|---|---|
| **Sign-in** | OpenID Connect | Apple asks Trustaige | A person proves it's them with their passkey, and Apple signs them in to their Managed Apple Account. |
| **Security events** | Shared Signals | Trustaige tells Apple | When someone's sessions end or their passkeys change, Apple hears about it within seconds. Apple creates and manages this stream itself, under an administrator's approval. |
| **Directory sync** | SCIM 2.0 | Trustaige pushes to Apple | Managed Apple Accounts are created, updated and removed from your directory. |

How it fits together, once it's set up:

*Steps 1 to 5 happen at every sign-in. Steps 6 and 7 happen whenever something changes in Trustaige.*

1. Person → Apple: signs in with their work email
2. Apple → Trustaige: sends them to Trustaige
3. Person ↔ Trustaige: passkey
4. Trustaige → Apple: ID token: email and name
5. Apple → Person: Managed Apple Account signed in
6. Trustaige → Apple: directory sync: create, update, disable (SCIM)
7. Trustaige → Apple: session-revoked, credential-change (Shared Signals)

## Before you begin

| You need | Why |
|---|---|
| An **Apple Business** account with the **Administrator** role | Only a role that can set up federation and connect an identity provider can do the steps in Apple Business. |
| A **domain verified** in Apple Business | Federation applies to one domain at a time. If you haven't verified it yet, Apple gives you 14 days to add its DNS record. |
| A Trustaige administrator who may **receive security signals** | Apple asks this person to sign in while it connects, and they approve Apple's event stream. The **Receive security signals** permission, the **Settings** permission, or superadmin all qualify. |
| Members whose Trustaige email is on that domain | Apple matches each person to their Managed Apple Account by email address. |
| A first and last name for everyone who will sign in | Apple refuses a sign-in without both. Trustaige sends the **First name** and **Last name** on the person's profile or, when those are empty, their display name split at its first space. Someone known by one name needs a last name added. |

Devices need iOS 15.5, iPadOS 15.5, macOS 12.4, visionOS 1.1 or later. Nothing
here needs iOS 27 or macOS 27.

> **Important:** Apple doesn't let an account whose role can set up federation sign in with
> federation itself. Do the Apple Business steps with an administrator account,
> and keep using a separate account for your own day-to-day sign-in. Once you
> finish step 3, nobody can create a personal Apple Account at your domain any
> more.

Allow about half an hour. Steps 1 to 4 can be spread out; step 5 can't: Apple
gives you four calendar days from creating its directory-sync client to finish
connecting it.

## 1. Create the app

Apple signs people in with a client ID and secret that you give it, so start
with an app of your own.

1. In the hub, go to **Apps**. Under **In-house applications**, click
   **Create in-house app**.
2. Name it **Apple Business**, and continue.
3. Under **Protocol**, choose **OpenID Connect**. Under **What kind of
   application is this?**, choose **Web app**: Apple keeps a client secret.
4. Under **Redirect URIs**, add Apple's:
   `https://gsa-ws.apple.com/grandslam/GsService2/acs`
5. Check the summary and click **Create application**.
6. On the app's page, in **Credentials**, copy the **Client ID** and the
   **Client Secret**. Keep them somewhere safe until step 3.

A web app can already use refresh tokens, which Apple needs to keep the
connection alive on its own. You don't need to change anything else on it.

**Choose who can use it.** In the app's **Access** section, click **Assign
groups** and choose the group whose people should have Managed Apple Accounts,
for example *Apple users*. Apple recommends allowing only specific accounts, and
the same group is what directory sync pushes in step 5. With no group assigned,
every member of your organization except guests can sign in, but directory sync
has no one to push.

## 2. Turn on Admin approval

Apple uses the one client ID and secret for both sign-in and its event stream,
so its stream can't have a credential of its own. It works under an
administrator's approval instead.

1. Open the app's **Signals** tab.
2. Choose **Admin approval**.

The tab now says **Waiting for an administrator's approval**, and shows the two
addresses you'll give Apple:

| Field | Value |
|---|---|
| **Transmitter metadata** | `https://id.trustaige.com/.well-known/ssf-configuration` |
| **OpenID configuration** | `https://id.trustaige.com/.well-known/openid-configuration` |

> **Note:** The approval is a record: **Approved by** a named administrator, on a date.
> It lets Apple manage its event stream and nothing else. It stops working the
> moment that person no longer holds the permission, or anyone revokes it on the
> **Signals** tab. The stream itself belongs to the app, so it keeps delivering
> while the approval is renewed.

## 3. Connect Trustaige in Apple Business

1. Sign in to [Apple Business](https://business.apple.com) and go to
   **Settings → Domains**.
2. Next to **User sign-in and directory sync**, select **Connect**.
3. Under **Choose Identity Provider**, choose the custom identity provider.
4. On **Set up your custom identity provider**, fill in:

   | Field | Value |
   |---|---|
   | **Name** | **Trustaige**. People see it on Apple's sign-in button, as **Sign in with Trustaige**. |
   | **Client ID**, **Client Secret** | From step 1 |
   | **SSF Config URL** | The **Transmitter metadata** address from step 2 |
   | **OpenID Config URL** | The **OpenID configuration** address from step 2 |

   The form also shows Apple's redirect URI; it's the one you added to the app in
   step 1.
5. Select **Continue**. Apple explains it will request the permissions it needs
   to sync your users and to prompt them to sign in again when their sign-in
   changes. Select **Sign in with Trustaige**.
6. Sign in with your passkey, as the administrator from **Before you begin**.
7. Trustaige asks you to approve **Apple Business** receiving security events
   about your organization's people, and lists what it will be told. Click
   **Approve**.
8. Apple shows **Trustaige Connected**. Select **Continue** to see the
   connection's settings.

On the app's **Signals** tab, **Admin approval** now says **Approved by** you.
Under **Streams** you'll find Apple's stream, pushing to
`federation.apple.com`, with the two events it asked for, **credential-change**
and **session-revoked**, and one acknowledged delivery: the verification event
Trustaige sends the moment Apple creates the stream.

Only someone who may receive security signals is ever shown the approval. The
people who sign in to their Managed Apple Accounts every day sign in as usual
and never see it.

## 4. Turn on sign-in with Trustaige

Apple turns this on only once no personal Apple Account uses your domain. If
one does, the domain's page says **unmanaged Apple Account found** and **Set
up** stays greyed out until you start domain capture.

> **Important:** Domain capture makes the owner of every personal Apple Account at your domain
> transfer it or change its email address, and once the domain is locked no
> personal Apple Account can use it again. Before you start, check the Apple
> Accounts your organization itself depends on: the Apple Developer account that
> signs your apps, the Apple Account your device management push certificate
> belongs to, App Store Connect, and Apps and Books. Move any that use an address
> at this domain to another address first. Apple's **Account Names List** of
> affected addresses is only produced once capture has started.

Your developer team doesn't have to stay on personal accounts. In Apple
Business, **Settings → Access Management → Apple Services → Developer** lets
Managed Apple Accounts use the Apple Developer Program, Xcode Cloud and the MFi
portal. Add your people's Managed Apple Accounts to your developer team and they
sign in with Trustaige, so someone you deactivate loses developer access too.
To make a Managed Apple Account the team's Account Holder, Apple asks you to
contact Apple Developer Support.

1. In Apple Business, go to **Settings → Domains** and select **Manage** next to
   your domain.
2. If Apple found unmanaged Apple Accounts, select **Get Started with Domain
   Capture**. Apple notifies their owners and gives them time to transfer the
   accounts or change their email.
3. Turn on **Sign In with Trustaige**. Apple locks the domain at the same time:
   **Lock Domain** shows on, and nobody can create a personal Apple Account with
   it any more.

To try it, take an iPhone or iPad that isn't signed in, open **Settings**, choose
to sign in, and enter a member's work email. Apple hands over to Trustaige, the
member signs in with their passkey, and the device finishes setting up their
Managed Apple Account with their name already on it. Use someone without an Apple
Business administrator role.

From now on, a person who signs in to an Apple device with their work email is
sent to Trustaige, and proves it's them with their passkey. Apple
creates their Managed Apple Account the first time they sign in, if directory
sync hasn't already.

## 5. Sync accounts from your directory

Sign-in alone creates an account the first time someone uses it, and never
removes one. Directory sync creates accounts before anyone signs in, keeps
names and addresses in step, and disables or removes accounts when people
leave.

Apple doesn't hand out a SCIM token. It issues your organization an OAuth client
for its directory feed, and an Apple Business administrator authorizes it.
Connect it that way:

1. In the hub, open the app's **Provisioning** tab and choose **OAuth 2.0
   client**. Copy the callback URL at the top of the form: Apple asks for it
   before it issues the client.
2. In Apple Business, set up directory sync for your domain with **Custom
   Sync**. When Apple asks for a redirect URI, paste the callback URL from step 1.
3. Apple opens **Managed Apple Accounts → Directory sync**, showing the
   **Authorisation callback URL** you gave it, a **Client ID**, **Status: Not
   Connected**, and its **Client Configurations**.
4. Under **Client Secret**, select **+ Client Secret**, choose how long it lasts
   (6, 9 or 12 months), and copy it: Apple shows it once.
5. Back on the **Provisioning** tab, fill in the form, copying each address from
   Apple's **Client Configurations**:

   | Hub field | Apple's label | Value today |
   |---|---|---|
   | **SCIM Endpoint URL** | **SCIM URL** | `https://federation.apple.com/feeds/business/scim` |
   | **Authorization URL** | **Authorisation Endpoint** | `https://appleid.apple.com/auth/oauth2/v2/authorize` |
   | **Token URL** | **Token Endpoint** | `https://appleid.apple.com/auth/oauth2/v2/token` |
   | **Client ID**, **Client secret** | **Client ID**, **Client Secret** | Apple's, from steps 3 and 4 |
   | **Secret expiry** | | The date the secret expires |
   | **Client authentication** | | **In the request body (client_secret_post)**: Apple's token endpoint takes the secret this way |
   | **Scope** | | Leave empty |

   Apple also lists a **Token Revoke URL**; the hub doesn't need it.

6. Under **When users are removed from the organization**, choose **Disable**:
   the person's Managed Apple Account is turned off but its data is kept.
   **Delete**, the default, removes the account and its data. Either way,
   someone who loses access to the app while still a member is only suspended.
7. Leave **Enable provisioning** on and click **Save, then authorize**.
8. Click **Authorize**. Apple asks you to sign in to Apple Business, then shows
   **Trustaige SCIM Application wants to access Apple Business Manager**, with
   access to **View and manage all users**. Select **Allow**.
9. You return to the app, which says **Connection authorized**. The tab shows
   **Authorized**, and Apple's **Directory sync** page no longer says **Not
   Connected**.

Directory sync now pushes the people in the app's groups, and the groups
themselves; **Last sync result** on the tab counts both. To push straight
away rather than wait for the next change, click **Sync Now**. While sync is on,
Apple Business shows synced accounts as read-only: changes are made in Trustaige.

What Apple receives for each person:

| Attribute | From |
|---|---|
| `userName` | Their username in Trustaige if they have one, otherwise their email. For Apple it has to be their work email. |
| `name`, `displayName` | Their name in your directory |
| `emails` | Their work email |
| `active` | Whether they can still sign in |

## Check that it works

| Check | Where | You should see |
|---|---|---|
| Apple's stream works under your approval | The app's **Signals** tab | **Approved by** your name, and Apple's stream with at least one acknowledged delivery |
| Directory sync is authorized | The app's **Provisioning** tab | **Authorized**, and a successful last sync |
| Accounts reached Apple | Apple Business, in its list of user accounts | Your group's people, read-only |
| Someone can sign in | An iPhone, iPad or Mac | Signing in with a work email opens Trustaige, and a passkey finishes it |

Try the last one with an account that has no Apple Business administrator role.

## What happens when something changes

| In Trustaige | At Apple |
|---|---|
| Someone joins the app's group | Directory sync creates their Managed Apple Account. |
| Their name or email changes | Directory sync updates the account. |
| They leave the group, or are deactivated | Directory sync disables or deletes the account, as you chose in step 5. |
| Their sessions end, or a passkey is added or removed | A `session-revoked` or `credential-change` event reaches Apple's stream within seconds, and Apple asks the person to sign in again on their devices. These are the two events Apple's stream asks for. |
| The approving administrator loses the permission, or the approval is revoked | Apple can no longer manage its stream, though the stream keeps delivering. Reconnect from Apple Business (step 3) and have an administrator approve it again. |

## Keep it running

- **The directory-sync secret expires** after the 6, 9 or 12 months you chose.
  Trustaige emails your administrators 30 days before. Create a new secret in
  Apple Business, then click **Replace secret** on the **Provisioning** tab; the
  authorization carries over.
- **The approving administrator leaves.** Apple can't change its stream until
  someone approves it again. The **Signals** tab marks the approval as no
  longer valid. Repeat step 3 with another administrator.
- **Tokens refresh on their own.** Neither connection needs attention between
  those events.

## Troubleshooting

**Apple says it could not verify the provided OIDC configuration**

Apple
signed you in but couldn't redeem the sign-in with the client ID and secret it
was given. Copy both again from the app's **Credentials**, check the app is
turned on, and check Apple's redirect URI is among its **Redirect URIs**. If you
regenerated the secret since, give Apple the new one.

**Apple says your account is missing a first or last name**

Apple refuses
anyone without both. In **Directory**, open the person and set their **First
name** and **Last name**, then sign in again.

**Apple's connection test fails, or Trustaige never asks you to approve**

The **Signals** tab must show **Admin approval**, and the person who signs in
must have the **Receive security signals** permission, the **Settings**
permission, or be a superadmin. Anyone else signs in normally and is never
asked, so Apple can't create its stream from their sign-in.

**Apple's authorization fails straight after you select Allow**

Check that
**Client authentication** is **In the request body (client_secret_post)**, save,
and click **Authorize again**. Apple's client ID and secret stay the same.

**The Provisioning tab says Needs authorizing again**

Apple refused the stored
authorization; the tab shows what Apple said. Click **Authorize again**. If you
created a new client in Apple Business, enter its client ID and secret first.

**The Provisioning tab says Not authorized yet after you clicked Authorize**

The callback URL in Apple Business must match the one on the tab exactly, and
you have four calendar days from creating Apple's client to finish.

**Nothing is synced**

Directory sync pushes only the members of the groups
assigned to the app. Assign a group, then click **Sync Now**.

**Someone can't sign in at Apple**

Their email in Trustaige must be their
Managed Apple Account's address, on the federated domain, and they must be able
to reach the app: in its group, or the app has no groups assigned. Apple Business
administrators can't sign in with federation at all.

**Apple shows the wrong user name**

Directory sync sends a person's username
when they have one. Remove the username in Trustaige, or make it their work
email.

## Reference

| What | Value |
|---|---|
| Redirect URI | `https://gsa-ws.apple.com/grandslam/GsService2/acs` |
| OpenID configuration URL | `https://id.trustaige.com/.well-known/openid-configuration` |
| SSF configuration URL | `https://id.trustaige.com/.well-known/ssf-configuration` |
| Scopes Apple requests | `openid`, `profile`, `email`, `offline_access`, `ssf.read`, `ssf.manage` |
| Directory sync callback URL | `https://id.trustaige.com/api/admin/provisioning/oauth/callback` |
| Apple's SCIM endpoint | `https://federation.apple.com/feeds/business/scim` |
| Apple's authorization URL | `https://appleid.apple.com/auth/oauth2/v2/authorize` |
| Apple's token URL | `https://appleid.apple.com/auth/oauth2/v2/token` |

**How the pieces fit.** When Apple signs someone in, the ID token carries their
email and, with `profile`, their `name`, `given_name` and `family_name`, so Apple
can name the account it creates. A sign-in that asks for `ssf.read` and
`ssf.manage` keeps them only for the administrator whose approval is on record;
for everyone else they are removed and the sign-in carries on. The token Apple
holds is checked against that approval on every call it makes to the stream.
Apple's stream asks for two events, `session-revoked` and `credential-change`,
pushed to an address under `https://federation.apple.com/feeds/business/caep/`,
and each concerns only people who can reach the app. Trustaige sends the stream a
verification event the moment Apple creates it, which Apple waits for.

## Apple's documentation

- [Intro to federated authentication with Apple Business](https://support.apple.com/guide/business/intro-to-federated-authentication-axmb19317543/web)
- [Use federated authentication with your identity provider](https://support.apple.com/guide/business/federated-authentication-identity-provider-axmfcab66783/web)
- [Verify a domain](https://support.apple.com/guide/business/verify-a-domain-axm48c3280c0/web)
- [Lock a domain](https://support.apple.com/guide/business/lock-a-domain-axmce04f4299/web)
- [Capture a domain](https://support.apple.com/guide/business/capture-a-domain-axm512ce43c3/web)