Authenticating with the Automated Device Enrollment program
Communicate securely with the web service using a server token.
Overview
The Automated Device Enrollment program uses a server token to allow a device management service to securely communicate with the program’s service.
Get an Automated Device Enrollment program server token
To get a server token, the user must complete the following steps. You can help by automating some of the steps.
Generate a public-private key pair in Privacy Enhanced Mail (PEM) format for your device management service, and store the private key securely on the service.
Sign into Apple School Manager or Apple Business.
Create a new device management server.
Upload a PEM-encoded X.509 certificate that contains the public key generated in step 1.
Download the S/MIME-encrypted (Secure/Multipurpose Internet Mail Extensions) token file generated by the web portal.
Decrypt the S/MIME token.
Upload the token file to the device management service.
The token consists of these 4 items: the consumer key, the consumer secret, the access token, and the access secret. See Examining server tokens for more details.
Deploy the server token
The server tokens can be deployed automatically or manually.
- Automatically
The device management service must automatically decrypt this file when it’s uploaded, using the private key for the Automated Device Enrollment program web services.
- Manually
Use the private key and an S/MIME encryption utility to manually decrypt the encrypted token file before it’s uploaded to the device management service. You then use the plain-text token file for authentication with the Automated Device Enrollment program services.
Use the OAuth credentials
Each service request to the enrollment service must include an X-ADM-Auth-Session header. If the request doesn’t have a valid X-ADM-Auth-Session header, or the auth token has expired, the server returns an HTTP 401 Unauthorized error. A new X-ADM-Auth-Session can be requested by using the https://mdmenrollment.apple.com/session endpoint. This endpoint supports the OAuth 1.0a protocol for accessing protected resources.
OAuth requests must provide the server-token fields along with a timestamp (in seconds since January 1, 1970 00:00:00 GMT) and a cryptographically random anti-replay value that must be unique for all requests made with a given timestamp. Sign the request using HMAC-SHA1, as described in http://oauth.net/core/1.0a/#signing_process. A request might look like:
GET /session HTTP/1.1
Authorization: OAuth realm="ADM",
oauth_consumer_key="CK_00fadb3d36c6094cf479838455321b7c",
oauth_token="AT_O2109279022Oe03b641fd6f07d7face7894211d521fd8bef09c3O137392",
oauth_signature_method="HMAC-SHA1",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_timestamp="137131200",
oauth_nonce="4572616e48616d6d65724c61686176",
oauth_version="1.0"
The token service validates the request and replies with a JSON payload containing a single key, auth_session_token, that contains the new X-ADM-Auth-Session token. A sample response might look like:
HTTP/1.1 200 OK
Date: Thu, 28 Feb 2013 02:24:28 GMT
Content-Type: application/json;charset=UTF8
Content-Length: 47
Connection: close
{
"auth_session_token" : "87a235815b8d6661ac73329f75815b8d6661ac73329f815"
}
After a period of time, the token expires and the service returns a 401 error code. When this happens, you must request a new session token.