# Enroll Apple devices with a work email > Point your domain's Apple enrollment record at Trustaige so people enroll iPhones, iPads and Macs by signing in with their work email. Source: https://docs.trustaige.com/manage/apple-account-enrollment Replace these placeholders with your organization's own values: - ``: Your domain, for example `example.com`. The domain in your people’s email addresses, as proved in the hub. - ``: Organization short ID, for example `a1B2c3D4e5F6`. The part after /o/ in your hub’s address. This page is for whoever runs the website at your organization's email domain. Your Trustaige administrator wants people to enroll their iPhones, iPads and Macs by signing in with their work email, and for that, Apple devices must find Trustaige through one small file on your domain. You should have received two values from them: your **email domain** and your **organization short ID**. Type them into the values panel and every address below fills in. The whole job is one redirect, usually one line of configuration: | What | Value | |---|---| | Your domain must answer | `https:///.well-known/com.apple.remotemanagement` | | With a redirect to | `https://id.trustaige.com/mdm/apple/discovery/` | | Or with this file, as `application/json` | [The record](#host-the-file-yourself) | Pick your web server or host and follow its section: [nginx](#redirect-with-nginx), [Cloudflare](#redirect-with-cloudflare), [Vercel](#redirect-with-vercel), [Netlify](#redirect-with-netlify) or [Apache](#redirect-with-apache). Then [check it is served](#check-it-is-served). ## How it works When someone chooses **Sign In to Work or School Account** on an Apple device and types their work email, the device takes the domain after the `@` and asks that domain where to enroll. Your domain answers with a short JSON record that names Trustaige. The device then opens Trustaige's sign-in, the person proves it's them with their passkey, and the device downloads its enrollment profile and installs it. There's no profile file to send around and no QR code. *Your domain is involved only in steps 1 and 2. If you host the record yourself, step 1 returns it directly and step 3 is skipped.* 1. Device → Your domain: GET /.well-known/com.apple.remotemanagement 2. Your domain → Device: 301 to Trustaige's copy of the record 3. Device → Trustaige: GET /mdm/apple/discovery/{short ID} 4. Trustaige → Device: record: mdm-adde, BaseURL 5. Device → Trustaige: POST BaseURL 6. Trustaige → Device: 401: sign in at …/auth (apple-as-web) 7. Device ↔ Trustaige: person signs in with their passkey 8. Device → Trustaige: POST BaseURL with the access token 9. Trustaige → Device: enrollment profile Apple devices follow the redirect, so the lightest setup is a permanent redirect to the copy of the record Trustaige hosts for your organization. That copy is always current, and it stops advertising Trustaige on its own if your organization stops managing Apple devices. You can also serve the record yourself; see [Host the file yourself](#host-the-file-yourself). ## What you need | You need | Why | |---|---| | The ability to change what `https:///` serves | Apple asks the exact domain in people's email addresses, over HTTPS, with a valid certificate. A `www.` site alone isn't enough; if the bare domain already redirects to `www.`, add the rule on the `www.` site, since the device follows each redirect in turn. | | The organization short ID | It's part of the redirect target. Your administrator copies it from **Work email enrollment** in the hub. | | A public answer | The hub checks the record from the internet, and so do devices on mobile networks. A domain that only resolves inside your network won't work. | Nothing on your site changes except this one path. The redirect never carries your visitors anywhere, because only Apple devices ask for it. ## Redirect with nginx Add this to the `server` block that serves your bare domain on port 443: ```nginx title="nginx.conf" {6-8} server { listen 443 ssl; server_name ; # your existing configuration location = /.well-known/com.apple.remotemanagement { return 301 https://id.trustaige.com/mdm/apple/discovery/; } } ``` Test and reload: ```bash sudo nginx -t && sudo nginx -s reload ``` Then [check it is served](#check-it-is-served). ## Redirect with Cloudflare Use this when your domain's DNS is on Cloudflare and the bare domain's record is **Proxied** (the orange cloud). Redirect Rules apply only to proxied traffic. 1. In the Cloudflare dashboard, open your domain and go to **Rules → Redirect Rules**, then **Create rule**. 2. Under **When incoming requests match**, choose **Custom filter expression** and set: **URI Path** **equals** `/.well-known/com.apple.remotemanagement`. In the expression editor that is: ```text title="Expression" (http.request.uri.path eq "/.well-known/com.apple.remotemanagement") ``` 3. Under **Then**, choose a **Static** redirect to `https://id.trustaige.com/mdm/apple/discovery/` with status code **301**. 4. Deploy the rule. The same rule, in short: ```text title="Dashboard → Redirect Rules" Rules → Redirect Rules → Create rule: When incoming requests match: URI Path equals /.well-known/com.apple.remotemanagement Then: Static redirect to https://id.trustaige.com/mdm/apple/discovery/, status 301 ``` Then [check it is served](#check-it-is-served). ## Redirect with Vercel Add the redirect to `vercel.json` at the root of the project that serves your bare domain. If the file already has a `redirects` array, add the entry to it. ```json title="vercel.json" {3} { "redirects": [ { "source": "/.well-known/com.apple.remotemanagement", "destination": "https://id.trustaige.com/mdm/apple/discovery/", "permanent": true } ] } ``` Deploy to production. Vercel answers a permanent redirect with status 308, which Apple devices follow like a 301. Then [check it is served](#check-it-is-served). ## Redirect with Netlify Add this line to the `_redirects` file in your site's publish directory (the folder Netlify deploys, such as `public` or `dist`), creating the file if it doesn't exist: ```text title="_redirects" /.well-known/com.apple.remotemanagement https://id.trustaige.com/mdm/apple/discovery/ 301 ``` If you configure redirects in `netlify.toml` instead, the same rule is: ```toml title="netlify.toml" [[redirects]] from = "/.well-known/com.apple.remotemanagement" to = "https://id.trustaige.com/mdm/apple/discovery/" status = 301 force = true ``` Deploy, then [check it is served](#check-it-is-served). ## Redirect with Apache Add this line to the `.htaccess` file at the root of your bare domain's site, or to its `` block. It needs `mod_alias`, which is on by default, and, in `.htaccess`, `AllowOverride FileInfo` or `All`. ```apache title=".htaccess" Redirect 301 /.well-known/com.apple.remotemanagement https://id.trustaige.com/mdm/apple/discovery/ ``` If you edited the virtual host, test and reload: ```bash sudo apachectl configtest && sudo apachectl graceful ``` Then [check it is served](#check-it-is-served). ## Host the file yourself If you'd rather not redirect, serve this record at `/.well-known/com.apple.remotemanagement` on your bare domain: ```json title="com.apple.remotemanagement" { "Servers": [ { "Version": "mdm-adde", "BaseURL": "https://id.trustaige.com/mdm/apple/account-enroll/" } ] } ``` It must come back with status 200 and `Content-Type: application/json`. Apple requires that content type, and most servers send a file without a known extension as `application/octet-stream`, so set it explicitly: ```nginx title="nginx.conf" location = /.well-known/com.apple.remotemanagement { default_type application/json; alias /var/www/well-known/com.apple.remotemanagement; } ``` ```apache title=".htaccess" ForceType application/json ``` `mdm-adde` tells the device to do an account-driven Device Enrollment, which is the only kind Trustaige serves. A record you host doesn't change when your organization does: if it ever stops managing Apple devices, remove the file. ## Check it is served Ask for the record the way a device does, following redirects: ```bash curl -sSL -D - https:///.well-known/com.apple.remotemanagement ``` With a redirect, you should see the redirect, then Trustaige's answer (the HTTP version and other headers vary): ```http title="Expected response" {1-2,4-5} HTTP/2 301 location: https://id.trustaige.com/mdm/apple/discovery/ HTTP/2 200 content-type: application/json cache-control: no-store {"Servers":[{"Version":"mdm-adde","BaseURL":"https://id.trustaige.com/mdm/apple/account-enroll/"}]} ``` If you host the file yourself, you see a single `200` with `content-type: application/json` and your file's contents. Either way, the `BaseURL` must end in your organization short ID. A `404` from Trustaige's copy means the redirect works but your organization isn't ready: the Apple push certificate isn't set up yet, or Apple device management isn't available to your organization. Tell your administrator. You can also check the enrollment address the record points to. Asked without a sign-in, it answers `401` and tells the device where to send the person to sign in: ```bash curl -si -X POST https://id.trustaige.com/mdm/apple/account-enroll/ ``` ```http title="Expected response" HTTP/2 401 www-authenticate: Bearer method="apple-as-web" url="https://id.trustaige.com/mdm/apple/account-enroll//auth" ``` Last, tell your administrator it's done. They run the hub's own check (below), which fetches the record from the internet and confirms it. ## Set up in the hub This part is for the Trustaige administrator. You need the **Scale** plan and permission to manage devices. 1. Set up the Apple push certificate first ([Apple devices](/manage/apple-devices#1-create-the-push-certificate)). Until it exists, the **Work email enrollment** card says "Set up the APNs push certificate above first — your domain's enrollment record stays inactive until the push channel exists." 2. In **Devices → Providers → Apple**, find **Work email enrollment** and click **Set up your domain**. 3. Step 1, **Point** *your domain* **at Trustaige**, shows the address Apple devices look up, `https:///.well-known/com.apple.remotemanagement`, the address to redirect it to, and your **Organization short ID**, each with a Copy button. Send this page to whoever runs your website, with your domain and organization short ID. 4. Once they've added it, click **Verify domain** in step 2, **Verify the record**. The hub fetches the record the way an Apple device does, following redirects, and checks it has a server entry whose `BaseURL` is your organization's enrollment address. You'll see **Domain verified** with "Discovery record correctly points "mdm-adde" enrollment at this server", and the card's header shows **Domain verified**. **Raw response** shows what your domain returned. Click **Re-verify** to check again later. The domain is your organization's own domain, the one shown in step 1's title. The hub sets up work email enrollment for that one domain. The card also tells you where Managed Apple Accounts stand. Apple finishes every work email enrollment by having the person sign in to their **Managed Apple Account**, issued through Apple Business Manager. With Apple Business Manager connected, the card says so; without it, it asks you to connect it first. To have people sign in to those accounts with their Trustaige passkey as well, connect [Apple Business](/manage/apple-business). ## What the person sees Devices need iOS 17, iPadOS 17 or macOS 14 or later. 1. **iPhone or iPad:** open **Settings → General → VPN & Device Management**. **Mac:** open **System Settings → General → Device Management**. 2. Choose **Sign In to Work or School Account** and type their work email. 3. Trustaige's sign-in opens inside the device's sign-in sheet. They sign in with their passkey. If they're signed in to another organization, Trustaige asks them to sign in to yours. 4. The device downloads its enrollment profile and installs it, then asks them to sign in to their Managed Apple Account to finish. The device then appears under **Devices → Fleet**, tied to the person who signed in, and your policies apply as for any other enrolled device. ## Turn it off Remove the redirect (or the file) from your domain. Devices that already enrolled stay enrolled; new ones can no longer find Trustaige by email. To remove management from an enrolled device, see [Remove a device from management](/manage/apple-devices#remove-a-device-from-management). ## Troubleshooting **“Failed to reach https://…/.well-known/com.apple.remotemanagement”** The hub couldn't connect to your domain over HTTPS: no answer, a DNS name that only resolves inside your network, or a certificate that isn't valid for the bare domain. The error underneath says which. Run the [curl check](#check-it-is-served) from outside your network. **“Discovery endpoint returned HTTP 404”** If curl shows the redirect and then a 404 from `id.trustaige.com`, the redirect is right and your organization isn't ready: set up the Apple push certificate first. If the 404 comes from your own server, the rule isn't in effect: check it's on the site that serves the bare domain, that it's deployed, and on Cloudflare that the record is **Proxied**. **“Response is not a valid service discovery record”** Your domain answered 200 but not with the JSON record, often your site's normal page or a "not found" page served with status 200. **Raw response** shows what came back. Check the path is exactly `/.well-known/com.apple.remotemanagement`, with no extension. **“Discovery record does not contain a server entry pointing to …”** The record is JSON but its `BaseURL` isn't your organization's enrollment address, usually a mistyped short ID in the redirect or the file. Compare it with the address in the message. **“Failed to read response body”** Your domain started answering and stopped. Try again; if it persists, check your server's logs for that path. **The hub says Domain verified, but devices can't find the server** The hub checks the record's contents, not its content type, and Apple requires `application/json`. If you host the file yourself, check the `content-type` line in the [curl check](#check-it-is-served). Also check the person typed an email address at exactly your domain. **“Apple enrollment is not available for your organization yet”** The person signed in, but Apple device management isn't available to your organization. Ask Trustaige support. ## Apple's documentation - [Account-driven enrollment methods](https://support.apple.com/guide/deployment/account-driven-enrollment-methods-dep4d9e9cd26/web), Apple Platform Deployment - [Onboarding users with account-driven enrollment](https://developer.apple.com/documentation/devicemanagement/onboarding-users-with-account-driven-enrollment) - [Implementing the simple authentication account-driven enrollment flow](https://developer.apple.com/documentation/devicemanagement/implementing-the-simple-authentication-account-driven-enrollment-flow), which describes the record and the redirect