Sign In with Apple

November 4, 2019

Sascha Preibisch
Sr. Software Architect

I recently took on the task of implementing Apple’s new “Sign In with Apple” feature. The implementation is based on OAuth and OpenID Connect, which allowed me to use tools that I already had.

But some other aspects of the implementation weren’t as straightforward. I learned a few lessons along the way that I think will be helpful—and aren’t obvious when reading through their documentation—so I’m sharing them here.

Please note the information that follows applies only to web applications using the OAuth authorization_code flow via REST API, not the JavaScript version.

Before You Get Started

As mentioned previously, the Apple implementation is a bit more involved than other providers like Google. Because of Apple’s emphasis on keeping their users’ privacy truly private (which I am a big supporter of), before you implement Sign in with Apple, you must meet a couple requirements first and be aware of some additional nuances.

Prerequisites:

You must create an Apple developer account here

You do this with all providers, but in this case it is not free of charge

You must own the domain

In the process of configuring your application, you need to be able to prove that you are in control of the domain for which you want to leverage the feature. If you do not have this proof, you won’t get ahead. Also note that only https is supported.

Things To Be Aware Of:

Support for SPF mailing addresses

Apple’s documentation is a little light on this, but you must have support for SPF mailing addresses. The intent is to prevent anyone besides yourself from sending emails to the users signed in to your application. To support SPF, you need to add a TXT record to your DNS server.

No user details, no documented scope definitions, no /userinfo endpoint

Thus far in my development, I haven’t been successful in gathering a name or an email address of a user that has signed in. The only value I was able to retrieve was the sub value (subject). I also didn’t find a list of documented OAuth/OpenID Connect scope values, and a /userinfo endpoint does not exist either. I did find something interesting, though, that I share further down.

Now that you’re aware of what’s coming, you can create the developer account and start developing the support for Sign In with Apple.

Configure an Application

Since I started from scratch, with no previous development experience in the Apple universe, I went through the complete setup including the generation of a developer certificate. Here is a comprehensive list of tasks as documented by Apple.

Start by locating the Certificates, Identifiers & Profiles menu in the developer console and following the steps provided here.

Certificates

Choose Developer ID Application
You’ll need to submit a CSR (Certificate Signing Request). If you have Java available, try these commands (just replace the secrets and your name in the dname value, and re-create the double-quotes in your terminal):
- Generate a private key:
  - $JAVA_HOME/bin/keytool -genkey -alias apple-dev -keystore private.p12 -storetype PKCS12 -keyalg RSA -storepass supersecretpassword -keypass supersecretpassword -validity 365 -keysize 2018 -dname “CN=Your Name Dev Key”
- Generate the CSR:
  - $JAVA_HOME/bin/keytool -certreq -alias apple-dev -file appleDev.csr -keystore private.p12 -storepass supersecretpassword -dname “CN=Your Name Dev Key”
Upload the generated file “appleDev.csr”

Identifiers

App ID
- Check Sign In with Apple as a feature (it’s quite far down the list)
- Next to it, check Enable as a primary App ID
Service ID
- The identifier you create will be your client_id later
- Associate the feature Sign In with Apple
- In that configuration page you will also have to register your redirect_uri

Keys

Create a private key that you will download *NOTE: you can only download it once
This key will be used by you to generate the client_secret for your application, expressed as a JWT
The shown Key ID has to be used as kid in the JWT header
Your Team_ID will be the issuer
Your Service ID generated earlier will be the sub

To confirm your domain ownership, open Sign In with Apple
- Two things are verified:
  - That you control the target domains
  - That you support the SPF mailing protocol
- To complete this process, you have to open this page, leave it and come back.
- After you’ve done that, you can download the file apple-developer-domain-association.txt which is needed for the domain verification.

Establish support for the SPF protocol
- To send an email to Apple users that have signed in to your web application, you have to support SPF as mentioned previously. The Links section at the bottom of this post provides some sources that explain more details on that.
- Use the referenced testing tool to get your record straight. Here are examples:
  - At your DNS server add an SPF record. It may look like this:
    - v=spf1 a include:yourmailserverdomain.com ~all
  - If your DNS server doesn’t provide the category SPF, you can add a TXT record. I did this in digitalocean.com and required the record to be in double-quotes:
    - Record Type: TXT
    - Domain: @
    - Value: “v=spf1 a include:yourmailserverdomain.com ~all”

Complete domain verification
- The downloaded file has to be located here in your web project: https://{your-domain}/.well-known/apple-developer-domain-association.txt. The content of this file is large and looks like this:

MIIP1wYJKoZIhvcNAQcCoIIPyDCCD8QCAQExCzAJBgUrDgMCGgUAMGwGCSqGSIb3DQEHAaBfBF17

InRlYW1JZCI6IkZaUE5VS1JORkIiLCJkb21haW4iOiJvYXV0aC5ibG9nIiwiZGF0ZUNyZWF0ZWQi

...

WBTHhIlGqFkw03X_AcdUUdTvL-vYyc_yHSocwOFAYzFi8Ds_NNBoxbZ5mmWxQbNAKIOSo30q_0V8

msBMLV7lR3_0E3zl

Congratulations! If you’ve mastered this part of the journey, the implementation itself can begin.

Implement the OAuth Flow

If you are experienced with implementing the OAuth authorization_code flow—and handling OpenID Connect scenarios—this implementation is similar. Nevertheless, I’ll share what worked for me.

NOTE: All values in {...} brackets have to be URLEncoded. This is a common oversight, so ensuring this will save you some time and frustration.

Authorization Request

Here is the request I created:

GET https://appleid.apple.com/auth/authorize?

client_id={client_id}

&response_type=code

&redirect_uri={redirect_uri}

&scope={scope}

&response_mode=form_post

&state={state}

Looks familiar, yes? BUT there are two hidden details:

scope
- I used “openid email name,” and it seemed to work even though I never got back any of those requested details. According to a forum entry, those will be supported soon.
- The string must be encoded as:

openid%20email%20name

instead of

openid+email+name

This last detail is IMPORTANT. If you are using java URLEncoder.encode(scope, “UTF-8”) you will end up with the latter. Use a library that supports %20 or do this as a short-term fix: URLEncoder.encode(scope, “UTF-8”).replaceAll(“[+]”, “%20”)

response_mode=form_post
- Your request fails if you are requesting more than “scope=openid” and not using response_mode=form_post.
- Be prepared to handle responses to your redirect_uri via POST!

In my request, I also used PKCE where the request includes these additional parameters:

code_challenge={code_challenge}&code_challenge_method=S256

This does not harm the flow. To be honest, though, I have no idea if PKCE is actually supported or not.

After the user is taken through the authentication and authorization process, the response will include the given state and the issued code, just as usual:

{redirect_uri}?state={state}&code={code}

Token Exchange Request

After you receive the authorization_code, you need to exchange the code for an access_token. The token response will include an id_token as well. The access_token currently has no use but the id_token does. All user information will be found within that token.

Method: POST
URL: https://appleid.apple.com/auth/token
Header: Content-Type: application/x-www-form-urlencoded
Body:

client_id={client_id}

&client_secret={client_secret}

&grant_type=authorization_code

&code={code}

&redirect_uri={redirect_uri}

client_id
- This is the service identifier that you created in the developer console. It’s a value that includes your Team_ID.

client_secret
- This is the biggest difference to other solutions. You have to generate the secret yourself based on your application’s private key which was generated during the configuration process in the developer console!
- The generated string has to be a signed JWT using the ES256 algorithm
- You set the expiration date in seconds (up to six months)
- The complete content of the JWT is explained here
- For your convenience, we’ve built a simple to use Java tool here: Client Secret Generator

Redirect_uri
- Nothing different here, just make sure it is the same value as in your initial authorization request

After receiving the token response you have to validate the id_token. Luckily, Apple supports JWKS. This is the endpoint:

GET https://appleid.apple.com/auth/keys

Do yourself a favor and do not implement the JWT validation process yourself! Use existing libraries such as jose4j following this example.

Conclusion

You now know everything that I know about Sign In with Apple. If you felt this was too much, here are the highlights to remember:

URLEncode spaces in scope with %20 instead of +
Include response_mode=form_post if you’re requesting more than scope=openid
Generate the client_secret BUT NEVER place the associated private key on your web server!

Thanks for reading and please leave constructive criticism, enhancement requests or joyful shout-outs in the comments!