On command line, add ability to connect to Apple Business Manager

[zhumo]

Goal

As a Fleet admin, I want to be able to connect Fleet to my Apple Business Manager account so that I can automatically enroll new, macOS hosts to Fleet. This way, I can order a new MacBook that automatically appears in Fleet when it's unboxed.

Related

• Parent epic: #7676
• Apple Push Certificates Portal: #7456

Child issues

• 8724

• 8725

• 8726

• 8733

• 9068

Requirements

• Fleet Premium only
• Fleet admin can generate a public key for Apple Business Manager (ABM)
• Fleet admin can configure a server token for ABM
• Fleet admin can configure the team that ABM hosts are added to when they automatically enroll
• Docs for renewing the ABM server token

Reference

• Apple docs: Link to a third-party MDM server in Apple Business Manager
• Apple docs: Manage server tokens in Apple Business Manager

Commands

Step 1 - Download ABM key

Issue: https://github.com/fleetdm/fleet/issues/8724

$ fleetctl generate mdm-apple-bm
Generating Apple Business Manager public key and private key...

Success! 

Generated your public key at {/Users/Mo}/fleet-mdm-apple-bm-public-key.pem

Generated your private key at  {/Users/Mo}/fleet-mdm-apple-bm-private-key.key

Visit https://business.apple.com/ and create a new MDM server with the public key. Then, download the new MDM server's token. 

Next, deploy Fleet with with `mdm` configuration: https://fleetdm.com/docs/deploying/configuration#mdm

If keys exist in the current working directory and the user runs fleetctl generate mdm-apple-bm, these files are overwritten.

Step 2 - Configure the server token in Fleet

Issue: https://github.com/fleetdm/fleet/issues/8725

$ fleet serve --mdm_apple_bm_server_token=path/to/server_token --mdm_apple_bm_key=path/to/private_key

Example YAML

mdm:
  apple_bm_server_token: path/to/server_token
  apple_bm_key: path/to/private_key

Document ABM server token renewal

Issue: #8725 (Task 3)

Apple Business Manager - See status

Issue: #8726

When no mdm-apple-bm token exists

$ fleetctl get mdm-apple-bm
Error: No Apple Business Manager server token found. Use `fleetctl generate mdm-apple-bm` and then `fleet serve` with `mdm` configuration automatically enroll macOS hosts to Fleet.

When a normal-state server token exists with no default team

$ fleetctl get mdm-apple-bm
Apple ID:               user@fleetdevicemanagement.com
Organization name:      Fleet Device Management, Inc.
MDM Server URL:         Apple Application Integration 2 
Renew date:             September 30, 2023
Default team:           No Team

There is a default team "Workstations" and the cert is within 30 days of expiration

$ fleetctl get mdm-apple-bm
Apple ID:               user@fleetdevicemanagement.com
Organization name:      Fleet Device Management, Inc.
MDM Server URL:         Apple Application Integration 2 
Renew date:             September 30, 2023
Default team:           Workstations

WARNING: Your Apple Business Manager (ABM) server token is less than 30 days from expiration. If it expires, laptops newly purchased via ABM will not automatically enroll in Fleet. To renew your ABM server token, follow these instructions: https://fleetdm.com/docs/using-fleet/faq#how-can-i-renew-my-apple-business-manager-server-token

^^^ The warning text above is in yellow

When the cert is expired

$ fleetctl get mdm-apple-bm
Apple ID:               user@fleetdevicemanagement.com
Organization name:      Fleet Device Management, Inc.
MDM Server URL:         Apple Application Integration 2 
Renew date:             September 30, 2023
Default team:           Workstations

ERROR: Your Apple Business Manager (ABM) server token is expired. Laptops newly purchased via ABM will not automatically enroll in Fleet. To renew your ABM server token, follow these instructions: https://fleetdm.com/docs/using-fleet/faq#how-can-i-renew-my-apple-business-manager-server-token

^^^ The error text above is in red

Set default team for ABM auto-enrollment

apiVersion: v1
kind: config
spec:
  mdm:
    apple_bm_default_team: Workstations

Run fleetctl apply -f path/to/yml. Verify that the team exists. Reject if the team does not with an error message. Note: it is case insensitive.

MISC

Help pages

fleetctl generate

We add a new subcommand in the help page for the generate command.

$ fleetctl generate
NAME:
   fleetctl generate - Generate useful or required files

USAGE:
   fleetctl generate mdm-apple-bm

SUBCOMMANDS:
    mdm-apple-bm     generate Apple Business Manager public key to enable automatic enrollment for macOS hosts.

fleetctl generate mdm-apple-bm

General help page for fleetctl generate mdm-apple-bm. This requires the --help flag. When blank, it will automatically generate the public key.

$ fleetctl generate mdm-apple-bm --help
NAME:
   fleetctl generate mdm-apple-bm - generate Apple Business Manager public key to enable automatic enrollment for macOS hosts.

USAGE:
   fleetctl generate mdm-apple-bm

fleetctl get

$ fleetctl get
NAME:
   fleetctl get - Get/list resources

USAGE:
   fleetctl get command [command options] [arguments...]

COMMANDS:
   ... REMAINS SAME BUT ADD:
   mdm-apple-bm                                                      Show information about Apple Business Manager for automatic enrollment

OPTIONS:
   --help, -h  show help (default: false)

Error states

fleet serve --mdm_apple_bm_server_token required file does not exist

Matches current behavior of fleetctl: Error: open does/not/exist: no such file or directory (Try fleetctl apply -f does/not/exist)

fleet serve --mdm_apple_bm_server_token validation error from Apple

$ fleet serve --mdm_apple_bm_server_token=path/to/token
Error! Failed to decrypt. 

If there is an error, reuse the pre-existing certs (if any).

Note that dynamic error message above. Return whatever Apple returns.

[noahtalerman]

@zhumo I assigned you. Can you please review the CLI experience?

FYI the plan, as specified by this issue, is for Fleet to decrypted the server token for the user. This way, the user sets the server token in Fleet without having to see or use a key.

In dogfood, we currently provide the user with a key. We ask the user to decrypt using key: https://github.com/fleetdm/fleet/blob/apple-mdm-proposal/proposals/apple-mdm/mvp-dogfood/setup.md#3-finalize-dep-setup

[noahtalerman]

the plan, as specified by this issue, is for Fleet to decrypted the server token for the user. This way, the user sets the server token in Fleet without having to see or use a key.

The above plan is similar to the Apple Developer plan: https://github.com/fleetdm/fleet/issues/7456#issuecomment-1281084665

@lucasmrod how difficult will it be to achieve the above?

@GuillaumeRoss do you have any thoughts on the above?

[noahtalerman]

@zwass can you check if we need to configure a token and a key for ABM? The current specs only specify a token.

[noahtalerman]

@michalnicp does a Fleet user need to configure a key for Apple Business Manager? The current specs only specify configuring a token.

[zwass]

@noahtalerman Good question. Fleet only ends up needing a token, but a key is needed to decrypt the token that Apple provides.

I think this is probably best achieved with a workflow like:

1. User runs fleetctl generate apple-bm-key (this generates a certificate and key)
2. User uploads certificate to ABM and downloads encrypted token (p7m) from ABM.
3. User runs fleectl generate apple-bm-token (this decrypts and outputs the token)
4. User configures Fleet with decrypted token.

Does this make sense? An alternate option is to remove the separate command for decrypting the token and instead have the user configure Fleet with both the encrypted token and the key.

[noahtalerman]

TODO @noahtalerman:

• DONE Update the help text to indicate what kind of files you get from Fleet. We think it's a .p7m
• DONE The user should receive the certificate and key
• TODO File a separate issue for this: Need an error state for Apple's terms of service updates (fleetctl and UI)
• WONT Need a message that lets the user know "If already configured, ..."
• DONE Update default team to just Workstations

[noahtalerman]

I think this is probably best achieved with a workflow like

@zwass is this workflow missing a "User configures Fleet with key" step?

An alternate option is to remove the separate command for decrypting the token and instead have the user configure Fleet with both the encrypted token and the key.

I prefer this option. This way, we remove the separate command and the expected steps for configuring Apple Business Manager are the same as configuring TLS.

Zach, please feel free to update CLI designs for Apple Business Manager and Apple Push Certificates Portal (commands or configuration). If you make changes, please @ mention me. This way, I can make sure these changes align with the experience in the UI.

[noahtalerman]

@zwass I assigned you this issue. Can you please take a look at the specs to see if this is ready for engineering?

FYI I made these changes to the specs following our decisions in "Connect to Apple Developer" call on 2022-11-01. These decisions are documented in more details in a separate issue here: https://github.com/fleetdm/fleet/issues/7456#issuecomment-1299109592

• Existing keys are overwritten when the user runs the command to generate new keys again.
• Update the help text so that it doesn't seem like we expect the server to (a) be configured via CLI flags and (b) be running as only a single instance on the same host where fleetctl is being run.
• Remove the y/n confirmation step.

cc @zhumo @michalnicp

[lukeheath]

@mna Assigning this epic over to you to review specs and add estimates. Please assign back to me once the child issues have been estimated. Thanks!

[michalnicp]

The fleetctl get mdm-apple-bm command outputs a lot of information that is not relevant to the dep token that gets created as part of fleetctl generate mdm-apple-bm. Are these supposed to be complimentary? If no, perhaps we should change the name of the command to avoid confusion and only output relevant information to the dep token.

$ fleetctl get mdm-apple-bm
Apple ID:               user@fleetdevicemanagement.com
Organization name:      Fleet Device Management, Inc.
MDM Server URL:         Apple Application Integration 2 
Renew date:             September 30, 2023
Default team:           No Team

I am assuming the "Renew date" here is the date the dep token expires. I think we should be more specific here so that the user knows what exactly needs to be renewed. Other things that expire related to apple mdm are the apns certificate and the scep certificate.

Is the "Apple ID" above the apple ID used for the mdm server in apple business manager. Afaik, there is no way to get this from the dep token. We would have to ask for it when generating the certificate eg fleetctl generate mdm-apple-bm --apple-id and save it to the database. This would also mean that fleet needs to be running. We are expecting that users are able to complete required setup for apple mdm without fleet running. Also, there is a potential for multiple apple ids to be used for mdm. One can be used for creating the mdm server in Apple Business Manager, and another can be used for creating the apns certificate.

The "Default team", "Organization Name", and "MDM Server URL" is not configured in Apple Business Manager. Outputting it here could cause confusion about where users should go to configure/change this.

[michalnicp]

In the following config

apiVersion: v1
kind: config
spec:
  mdm:
    apple_bm_default_team: Workstations

are we expecting to set a different default team for automatic vs manual enrollments? Are we missing a config field for manual enrollments? Why are we prefixing with apple_bm, this is not a setting that is applied in Apple Business Manager, or even in the dep profile that gets assigned to devices.

I propose that we change this to default_team and make it so devices are associated with the default team regardless of whether they are dep (automatically) enrolled or manually enrolled.

[lukeheath]

@michalnicp Thanks for your comments. @mna will be back online Monday and is taking over the specs from here.

[michalnicp]

Just as an additional note, we now have fleetctl get mdm-apple-bm and fleetctl get mdm-apple (https://github.com/fleetdm/fleet/issues/7456). Should we combine these and display all information related to apple mdm?

[noahtalerman]

are we expecting to set a different default team for automatic vs manual enrollments? Are we missing a config field for manual enrollments?

@michalnicp no. The plan is for Fleet to only allow a default team for hosts that automatically enroll.

The expected workflow for automatic is...IT admins orders new macOS host -> host gets shipped and shows up in Fleet assigned to the default team in Fleet (IT admin can transfer to a new team if desired) -> host is unboxed -> host receives the configuration profile assigned to its team.

For hosts that manually enroll (turn on MDM), we expect the IT admin to have already transferred these hosts to a team in Fleet.

The expected workflow for manual is...IT admin adds host to Fleet (IT admin can transfer to a new team if desired) -> device user turns on MDM via Fleet Desktop -> host receives the configuration profile assigned to its team.

Why are we prefixing with apple_bm?

We're prefixing with apple_bm because we'd like users to know that this setting applies to the Apple Business Manager integration. The plan is for the setting to appear under Apple Business Manger section in the UI:

I propose that we change this to default_team and make it so devices are associated with the default team regardless of whether they are dep (automatically) enrolled or manually enrolled.

Do you think we should change the name if the setting only applies to hosts that automatically enroll?

[noahtalerman]

we now have fleetctl get mdm-apple-bm and fleetctl get mdm-apple (https://github.com/fleetdm/fleet/issues/7456). Should we combine these and display all information related to apple mdm?

@michalnicp @zwass why? Is this to reduce the number of commands for the user? Does this make implementation easier?

We decided to have separate commands because the user can set up Apple Push Certificates Portal (APNs) without setting up Apple Business Manager (ABM). Note that only Fleet Premium users can set up ABM.

We think it will be common for APNs to be set up and not ABM.

[michalnicp]

For hosts that manually enroll (turn on MDM), we expect the IT admin to have already transferred these hosts to a team in Fleet.

Okay, so we are not supporting assigning a default team to manually enrolled hosts.

Do you think we should change the name if the setting only applies to hosts that automatically enroll?

No, I suppose not.

@noahtalerman

[michalnicp]

we now have fleetctl get mdm-apple-bm and fleetctl get mdm-apple (https://github.com/fleetdm/fleet/issues/7456). Should we combine these and display all information related to apple mdm?

@michalnicp @zwass why? Is this to reduce the number of commands for the user? Does this make implementation easier?

This would give users a single complete to be able to check the status of mdm. With the current design, users have to run multiple commands to identify if there is a problem. fleetctl get apple-mdm-bm could show no errors, but there may be a problem because the apns certificate is expired, which is only reported by fleetctl get apple-mdm. Also, because these commands are so similar, it's easy to get these two mixed up. @noahtalerman

[noahtalerman]

With the current design, users have to run multiple commands to identify if there is a problem

@michalnicp this is a good point. I think this falls under a different "check status of all MDM integrations (ABM and APNs)" workflow or problem.

I prefer to have 2 commands because we're prioritizing the "set up Apple Business Manager" workflow over over the "check status of ABM and APNs" workflow.

The expected workflow for set up using fleetctl is fleetctl generate apple-mdm-bm -> fleet serve -> fleetctl get apple-mdm-bm

My understanding is that having 2 commands now does not prevent us, or make it more difficult, to have 1 command later. I could be wrong.

I agree that 1 command could provide a better solution for the check stats of ABM and APNs workflow.

[noahtalerman]

@michalnicp below is the response to your questions you posed in this comment: https://github.com/fleetdm/fleet/issues/7515#issuecomment-1317760621

The fleetctl get mdm-apple-bm command outputs a lot of information that is not relevant to the dep token that gets created as part of fleetctl generate mdm-apple-bm. Are these supposed to be complimentary?

Yes. The fleetctl get mdm-apple-bm and fleetctl generate mdm-apple-bm commands are expected to be used in 1 "set up Apple Business Manager" workflow.

the "Renew date" here is the date the dep token expires we should be more specific here so that the user knows what exactly needs to be renewed.

Yes. "Renew date" is the date when the token expires.

We will provide this information in help text when the token is about to expire:

WARNING: Your Apple Business Manager server token is less than 30 days from expiration. If it expires, laptops newly purchased via ABM will not automatically enroll in Fleet. Use `fleetctl generate mdm-apple-bm` and then `fleet serve` with `mdm configuration automatically enroll macOS hosts to Fleet.

Is the "Apple ID" above the apple ID used for the mdm server in apple business manager. Afaik, there is no way to get this from the dep token

Yes. I asked @mna to dig into this and let me know if there's no way to get the Apple ID via the token or some Apple API.

If we've confirmed we can't get the Apple ID, I will remove Apple ID from this issue's specs.

The "Default team", "Organization Name", and "MDM Server URL" is not configured in Apple Business Manager. Outputting it here could cause confusion about where users should go to configure/change this.

Right. "Default team" will come from the Fleet server. My understanding is that we could get "MDM Server URL" and "Organization Name" from an Apple API. Is this right?

We'd like to output this information here because all information is related to the integration with Apple Business Manager.

We expect user to look at their Apple Business Manager UI and fleetctl get mdm-apple-bm to verify "is Fleet connected to the right MDM server."

[michalnicp]

My understanding is that we could get "MDM Server URL" and "Organization Name" from an Apple API. Is this right?

@noahtalerman No, this is configured in Fleet only

[mna]

I asked @mna to dig into this and let me know if there's no way to get the Apple ID via the token or some Apple API.

@noahtalerman sorry if I missed something, but I wasn't aware you were waiting for info from my part regarding this, what I saw is that comment on the APNs ticket: https://github.com/fleetdm/fleet/issues/8596#issuecomment-1314495501 .

FWIW, I think Michal knows better than me the ins and outs (figuratively and literally!) of the Apple registration workflow. I did check all the information available in the parsed APNs cert and there's nothing in there that looks like an apple ID/email address (assuming that would be a fleetdm.com email address, this is the cert used for dogfood, but even looking for '@' doesn't find any).

[mna]

@noahtalerman @michalnicp Follow-up on the Apple ID thing, this Apple API seems to return what we want (at least for Apple Business Manager, not for APNs):

https://developer.apple.com/documentation/devicemanagement/accountdetail

admin_id The Apple ID of the person who generated the currently in-use tokens. org_name The organization name. server_name The name of the MDM server. urls The list of URLs available in the MDM service.

However, it is in the "Roster management" section of the docs and it has this mention:

This API isn’t supported for Apple Business Manager organizations.

But... this seems weird, as if this particular endpoint was misplaced in the docs (it doesn't seem to deal with "Manage classes for your students and teachers." like the rest of the section). Will have to try it out to make sure, I don't see an equivalent endpoint that returns this information in the rest of the "Device Assignment" section.

EDIT: this github repo documents that endpoint as being authenticated the same way as the other MDM device-related endpoints, so looks like that would work to get apple ID and other related info: https://github.com/4d-for-ios-sdk/Mobile-Device-Management-Protocol-Reference/blob/master/markdown/4-Profile_Management/4-Profile_Management.md#account-details

[mna]

@lukeheath Assigning back to you, the child issues have been spec'd and estimated.

[michalnicp]

In "Step 1 - Download ABM key", we are actually generating a certificate containing a public key to upload to Apple. Typically, we output certificates with the extension .crt to indicate that it is a certificate. I would recommend changing this to output fleet-apple-mdm-bm-public.crt and fleet-apple-mdm-bm.key for consistency with fleetctl generate apple-mdm

@noahtalerman

[noahtalerman]

this github repo documents that endpoint as being authenticated the same way as the other MDM device-related endpoints, so looks like that would work to get apple ID and other related info: https://github.com/4d-for-ios-sdk/Mobile-Device-Management-Protocol-Reference/blob/master/markdown/4-Profile_Management/4-Profile_Management.md#account-details

Sweet!

@mna I interpreted this as...we can get all info included in the spec: Apple ID, Organization name, MDM Server URL, Renew date

Please let me know if this isn't right.

[mna]

@noahtalerman Pending an actual test to call this endpoint with a valid Apple BM token, but yeah let's assume we can get all this information until proven otherwise. I'll get to it when I (or someone) start working on the get mdm-apple-bm ticket (soon).

[noahtalerman]

we are actually generating a certificate containing a public key to upload to Apple

@michalnicp is there a reason or preference for using .crt instead of .pem?

I prefer to use something like fleet-apple-mdm-bm-public-key.pem. This is because Jamf uses MDM-Token-Public-Key.pem.

[mna]

@noahtalerman I now have my Apple Business Manager server token and my MDM server, so I've been able to test getting the information via the Apple API. Here's what we have:

• Apple ID: we do have this, returned as e.g. "admin_id": "martin+mdmmanager@fleetdm.com"
• Organization name: we do have this: "org_name": "Fleet Device Management Inc."
• MDM Server URL: we do not have this as part of the Apple API. However, what exactly do we want to display for this field? Is this the same as the Fleet Server URL? If so we have it as part of the app config.
• Renew date: we do have this, it's a field that is part of the (decrypted) server token's JSON: "access_token_expiry": "2023-11-29T15:07:39Z"
• Default team: we do have this, we save it in our app config

So the only remaining question mark is for the MDM Server URL field.

[zhumo]

@mna I believe the MDM server is the fleet server under our approach, but maybe @roperzh can confirm that?

relatedly, I looked at my MDM enrollment profile and found this:

So it is pointing to some path in our server.

I should note that our colleagues in the industry do not show the MDM server URL.

[roperzh]

@zhumo thanks! I think Martin's question is aimed to double check about the meaning of "Server URL" because the examples show: MDM Server URL: Apple Application Integration 2.

If the example was wrong, then as you both suggested we can just provide Fleet's URL from app config.

I should note that our colleagues in the industry do not show the MDM server URL.

curious: do you mean in the macOS profile UI?

[zhumo]

Ah, no. I meant in the UI where the user sees the status of the integration.

Mo Zhu

Head of Product

fleetdm.com http://www.fleetdm.com | @fleetctl https://twitter.com/fleetctl

On Tue, Nov 29, 2022 at 9:55 AM Roberto Dip @.***> wrote:

@zhumo https://github.com/zhumo thanks! I think Martin's question is aimed to double check about the meaning of "Server URL" because the examples show: MDM Server URL: Apple Application Integration 2.

If the example was wrong, then as you both suggested we can just provide Fleet's URL from app config.

I should note that our colleagues in the industry do not show the MDM server URL.

curious: do you mean in the macOS profile UI?

— Reply to this email directly, view it on GitHub https://github.com/fleetdm/fleet/issues/7515#issuecomment-1331065854, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABI4PYWRGEWW7QYM5JMZ47TWKY7PJANCNFSM6AAAAAAQCMWVGM . You are receiving this because you were mentioned.Message ID: @.***>

[michalnicp]

we are actually generating a certificate containing a public key to upload to Apple

@michalnicp is there a reason or preference for using .crt instead of .pem?

I prefer to use something like fleet-apple-mdm-bm-public-key.pem. This is because Jamf uses MDM-Token-Public-Key.pem.

Yes, to be consistent with the fleetctl generate apple-mdm command, which outputs certificates with the extension .crt and pem encoded keys with the extension .key.

@noahtalerman

[michalnicp]

Organization name: we do have this: "org_name": "Fleet Device Management Inc."

Would there be any issues if the organization name from Apple is different than the organization configured in fleet? I could see this being confusing. Should we be more clear about where this data is coming from in the output/help text?

@mna @noahtalerman

[noahtalerman]

Yes, to be consistent with the fleetctl generate apple-mdm command

Ok makes sense to me 👍

@michalnicp what do you think about fleet-apple-mdm-bm-public-key.crt and fleet-apple-mdm-bm-private.key? In the UI we ask the user to go to ABM with their "public key":

[noahtalerman]

Would there be any issues if the organization name from Apple is different than the organization configured in fleet?

@michalnicp hmm, interesting point. What do you mean by issues?

Should we be more clear about where this data is coming from in the output/help text?

Personally, I think it's clear that the data is coming from Apple because it's shown when running the fleetctl-apple-bm command. This command's description informs the user that the info is about ABM. Here's the spec'd description: Show information about Apple Business Manager for automatic enrollment.

What do you think? Still confusing?

[michalnicp]

https://developer.apple.com/documentation/devicemanagement/accountdetail

I tried out this API and got the following response from dogfood

{
  "server_name": "Fleet Dogfood",
  "server_uuid": "xxx",
  "facilitator_id": "xxx",
  "org_name": "Fleet Device Management Inc.",
  "org_email": "xxx",
  "org_phone": "xxx",
  "org_address": "xxx"
}

Personally, I think it's clear that the data is coming from Apple because it's shown when running the fleetctl-apple-bm command. This command's description informs the user that the info is about ABM. Here's the spec'd description: Show information about Apple Business Manager for automatic enrollment.

What do you think? Still confusing?

Well, the mdm server url and the default team will be coming from fleet, not from Apple Business Manager. This command will be returning information from multiple sources. In the response above, the organization name is "Fleet Device Management Inc.", whereas in dogfood it is "Fleet Device Management". We are being inconsistent in our own environment with the org name, which is also confusing.

@noahtalerman

[michalnicp]

admin_id The Apple ID of the person who generated the currently in-use tokens. org_name The organization name. server_name The name of the MDM server. urls The list of URLs available in the MDM service.

However, it is in the "Roster management" section of the docs and it has this mention:

This API isn’t supported for Apple Business Manager organizations.

Tthe admin_id field is not returned from the accountdetail endpoint. It may be part of the spec in https://developer.apple.com/documentation/devicemanagement/accountdetail, but it's ommited for some reason. @mna @noahtalerman

[roperzh]

from Michal's response: weird thing is that the API is returning facilitator_id, which is:

The legacy equivalent to the admin_id key. This key is deprecated and may not be returned in future responses

[mna]

@michalnicp @noahtalerman @roperzh

The admin_id field is not returned from the accountdetail endpoint. It may be part of the spec in https://developer.apple.com/documentation/devicemanagement/accountdetail, but it's ommited for some reason.

It is returned when I test it with my personal ABM token:

status: 200
body: 
{
  "server_name": "Martin's MDM Server",
  "server_uuid": "redacted",
  "facilitator_id": "martin+mdmmanager@fleetdm.com",
  "admin_id": "martin+mdmmanager@fleetdm.com",
  "org_name": "Fleet Device Management Inc.",
  "org_email": "guillaume@fleetdm.com",
  "org_phone": "redacted",
  "org_address": "redacted",
  "org_id": "redacted",
  "org_id_hash": "redacted",
  "urls": [
    // omitted...
  ],
  "org_type": "org",
  "org_version": "v2"
}

My guess is that the dogfood org is an older version? You see the org_version field returned in my response, it is v2 while your response doesn't even has that field.

In any case, I'll fallback to facilitator_id if admin_id is not available, as the doc mentions they are the same:

facilitator_id : The legacy equivalent to the admin_id key.

[noahtalerman]

the mdm server url and the default team will be coming from fleet, not from Apple Business Manager. This command will be returning information from multiple sources

the organization name is "Fleet Device Management Inc.", whereas in dogfood it is "Fleet Device Management". We are being inconsistent in our own environment with the org name, which is also confusing.

@michalnicp good points. I like your suggestion about clarifying this in the help text. What messaging do you think we should use?

[fleet-release]

Clouds of hope,
Apple Business Manager link,
Fleet and users thrive.

[zhumo]

Confirm and celebrate:

@mna could you also document the ABM setup via command line in the MDM section of the docs? And renewal

[mna]

@zhumo @noahtalerman as for https://github.com/fleetdm/fleet/issues/7456#issuecomment-1400522203, seems like there may be some misunderstanding here, as https://github.com/fleetdm/fleet/issues/8799 (assigned to Noah) should take care of those docs as I understand it?

[noahtalerman]

@mna hey! Sorry for the confusion.

8799 did cover the renew docs. I updated this issue. It now covers creating the doc page where these docs will live. I forgot the document this change. Just now, I updated this issue's description to reflect this change.

We reopened the issue for this feature (story) because we'd like to start to treat missing docs like we treat bugs. If a story makes it to QA and a bug is found, Reed or I will move the story back to "In progress" with a description of the bug or missing docs.

I asked you to help write the docs because you worked most aspects of this story.

Does that make sense?

cc @lukeheath

[lukeheath]

Docs merged, closing issue.

[fleet-release]

Successfully configured Fleet with the Apple Business Manager server token.

Visit https://business.apple.com/ and create a new MDM server with the public key. Then, download the new MDM server's token.

Clouds part, connection made
Apple business manager key
Fleet automation, ease