Sync user accounts from your identity provider in Apple Business Essentials
In Apple Business Essentials, you can use OpenID Connect (OIDC) or System for Cross-domain Identity Management (SCIM) to sync user accounts from your identity provider (IdP). Using this system, you merge Apple Business Essentials properties (such as roles) with user account data imported from your IdP. When you use SCIM to sync users, the account information is added as read-only until you disconnect. At that time, the accounts become manual accounts, and attributes in these accounts (such as user names) can then be edited. The initial sync takes longer to perform than subsequent cycles do. Consult your IdP’s documentation to learn how often they sync users to Apple Business Essentials.
Important: You have only 4 calendar days to complete the token transfer to your IdP and successfully establish a connection, or you must begin the process again.
Before you begin
Before you sync to your IdP using an OIDC connection, you must do the following:
Configure and verify the domain you want to use. See Add and verify a domain.
Configure, federate, and enable a domain. See Use federated authentication with your identity provider.
Have on call an IdP administrator with permissions to edit settings.
Make sure you have the following information, then contact your IdP:
Unique identifier field for users: The value of this attribute is normally the email address of the user. This is used to create the user’s Managed Apple Account. For example, it may be userName.
Authentication method: SAML 2.0.
Authentication mode: OAuth 2.
Single sign-on URL: Consult your IdP’s documentation.
Authorization callback URL: Consult your IdP’s documentation.
IdP user accounts and Apple Business Essentials
When a user is copied from your IdP using SCIM to Apple Business Essentials, the default role is Staff.
Note: User groups from your IdP aren’t synced to Apple Business Essentials. If you want the same groups, you can create new groups in Apple Business Essentials and add users to them.
Sign-in attribute
Apple Business Essentials requires that the attribute used for the Managed Apple Account be unique. This is normally the user’s email address. If a user has an attribute that’s exactly the same as an existing Apple Business Essentials user with the role of Administrator, no syncing is performed and the source field remains unchanged.
Person ID
When an IdP user account is synced to Apple Business Essentials, a Person ID is created for the Apple Business Essentials user account. The Person ID is used to identify conflicting user accounts.
Important considerations if you modify the Person ID:
If you modify the Person ID for a user account previously imported from your IdP, that user account is no longer paired with the IdP.
If you modify the Person ID for a user account previously imported from your IdP and want to reconnect the user account, you must resolve the conflict.
Sign in to your IdP
Sign in to your IdP as an administrator, then do one of the following:
Locate the app created by your IdP. You may be able to skip several steps in this task.
Navigate to where you can create an app or connection.
Create the app with the following information:
Important: Remember the name of the SCIM app because you may need it for the authorization callback URL.
Apple Business Essentials: Use AppleBusinessEssentialsSCIM.
App type: Use SCIM.
Authentication method: Use SAML 2.0.
Single sign-on URL used for recipient and destination: Consult your IdP’s documentation.
Audience URI: Use Entity ID.
Save the changes.
Configure the SCIM app provisioning settings
Locate the provisioning section of your IdP SCIM app, then enter the following values:
SCIM connector base URL: https://federation.apple.com/feeds/business/scim
Access token URI: https://appleaccount.apple.com/auth/oauth2/v2/token
Authorization URI: https://appleaccount.apple.com/auth/oauth2/v2/authorize
Client ID: 123
Client secret: 123
Important: Because you don’t yet know the actual SCIM Client ID and Client secret, 123 is used as a placeholder. You replace these values in a later task.
Authentication mode: OAuth 2.
Unique identifier field for users: Consult your IdP’s documentation.
Important: Make sure you match the case of the identifier.
Supported provisioning actions:
Import new users and profile updates.
Push new users.
Push profile updates.
Save the changes.
Create the authorization callback URL
You must create an authorized callback URL for Apple Business Essentials to get user records from your IdP using SCIM. This callback URL is based on the name of the SCIM app you created in your IdP.
Remember the name for your SCIM app. For example:
Apple Business Essentials: AppleBusinessEssentialsSCIM
Paste the app name inside the following URL. For example:
https://identity-provider.com/admin/app/AppleBusinessEssentialsSCIM/oauth/callback
Save the authorization callback URL.
You paste it into Apple Business Essentials in the next task.
Create and copy SCIM client information to your IdP
In Apple Business Essentials, sign in with a user that has the role of Administrator or People Manager.
Select your name at the bottom of the sidebar, select Preferences
, then select Managed Apple Accounts 
.Select Enable next to Custom Sync.
Paste in the authorization callback URL from the previous task, then select Create.
Select SCIM Application, then select Create.
Open a new text file or spreadsheet, then enter the following values from Apple Business Essentials:
For the OIDC client ID, paste the SCIM client ID.
For the OIDC client secret, paste the SCIM client secret.
Select Copy next to Client ID, then paste the client ID in the file.
Select Client Secret, choose how long the secret should be active before it expires (6, 9, or 12 months), then paste the client secret in the file.
Important: If you delete or forget the client secret before you paste it into your IdP SCIM app, you must create a new client secret.
Select Done.
Paste the client ID and client secret in your IdP SCIM app and verify the connection
Return to the provisioning section of your IdP SCIM app, then paste in the following values:
Apple Business Essentials SCIM Client ID
Apple Business Essentials SCIM Client secret
Save the changes.
If your IdP allows you to test authentication using an IdP administrator account, you can test it now. For example, there might be a button “Authenticate with [AppleSchoolManagerSCIM], [AppleBusinessManagerSCIM],[AppleBusinessEssentialsSCIM],” or whatever you named your SCIM app.
Enter your IdP administrator name and password, then enter the two-factor authentication value.
Read any authorization information carefully. If you agree, select Continue.
If necessary, you can now turn on federated authentication for this domain.
Your IdP and Apple Business Essentials are now configured to sync specific user attribute changes from your IdP to Apple Business Essentials.