Sync user accounts from your identity provider in Apple School Manager
In Apple School Manager, 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 School Manager properties (such as grade level and 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 usernames) 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 School Manager.
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 Link to new domains.
Disconnect from your Student Information System (SIS) or stop uploads using SFTP.
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 ID. For example, it may be userName.
Authentication method: SAML 2.0.
Authentication mode: OAuth 2.
Single sign-on URL: Consult your IdP’s documentation.
Authorisation callback URL: Consult your IdP’s documentation.
IdP user accounts and Apple School Manager
When a user is copied from your IdP using SCIM to Apple School Manager, the default role is Student.
Note: User groups from your IdP are not synced to Apple School Manager.
Sign-in attribute
Apple School Manager requires that the attribute used for the Managed Apple ID be unique. This is normally the user’s email address. If a user has an attribute that is exactly the same as an existing Apple School Manager 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 School Manager, a Person ID is created for the Apple School Manager user account. This ID is used to identify conflicting user accounts. Also, the Person ID is automatically generated for users imported using SCIM or using SIS integration but not automatically generated from users imported using SFTP.
If SCIM is disconnected and SFTP is used to upload users again, new users are created unless the Person ID in the SFTP upload file matches the Person ID that was assigned by SCIM. See Upload Student Information System data to Apple School Manager.
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 authorisation callback URL.
Apple School Manager: Use AppleSchoolManagerSCIM.
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/school/scim
Access token URI: https://appleid.apple.com/auth/oauth2/v2/token
Authorisation URI: https://appleid.apple.com/auth/oauth2/v2/authorize
Client ID: 123
Client secret: 123
Important: Because you do not 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 authorisation callback URL
You must create an authorised callback URL for Apple School Manager 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 School Manager: AppleSchoolManagerSCIM
Paste the app name inside the following URL. For example:
https://identity-provider.com/admin/app/AppleSchoolManagerSCIM/oauth/callback
Save the authorisation callback URL.
You paste it into Apple School Manager in the next task.
Create and copy SCIM client information to your IdP
In Apple School Manager
, sign in with a user that has the role of Administrator, Site Manager or People Manager.Select your name at the bottom of the sidebar, select Preferences
, then select Managed Apple IDs
.Select Enable next to Custom Sync.
Paste in the authorisation 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 School Manager:
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 School Manager SCIM Client ID
Apple School Manager 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 authorisation information carefully. If you agree, select Continue.
If necessary, you can now turn on federated authentication for this domain.
Your IdP and Apple School Manager are now configured to sync specific user attribute changes from your IdP to Apple School Manager.