Obtain Apple Credentials
com.domainname.appname
).+
) on the top.Services IDs
from the list of options and click ‘Continue’ and then provide your app information.Identifiers
in the
sidebar, then select Services IDs
from the dropdown menu on the right.Services ID
you created in the previous step.Sign In With Apple
for the Services ID
by clicking the checkbox next to it.Configure
.App ID
as your Primary App ID
.+
) next to Website URLs
.Domains and Subdomains
input (do not add a scheme,
e.g. https://
, or path information).Return URLs
input, enter the complete redirect URL of your app which you found in the
previous step.Next
at the bottom right.Done
at the bottom to close the modal.Edit your Services ID Configuration
view, click Continue
at the top right, then click Save
.Next, you need to create a Key
and download a Key
file. You need this file to
generate your client secret in the next step.
Keys
in the sidebar,
then click the add button (+
) next to the Keys
heading.Key Name
.Key Name
input, check Sign in with Apple
.Configure
to the right.Configure Key
view, select your previously registered App ID
in thePrimary App ID
dropdown.Save
on the top right.Register a New Key
view, click Continue
, then click Register
on the top right.Download Your Key
view, click Download
on the top right to save the key file.Done
on the top right.Sign in with Apple requires a client secret to authorize API requests. The secret must be a JSON Web Token (JWT) signed with the Elliptic Curve Digital Signature Algorithm (ECDSA) with the P-256 curve and the SHA-256 hash algorithm.
To make secret generation as easy as possible, we provide a script that can be executed using Docker. If you do not have Docker installed, see the official installation instructions.
The script requires the following information:
private_key
: This is the path to the key file you downloaded in the previous step.
Per default the key file name should look like this: AuthKey_XXXXXXXXXX.p8
. Because we use Docker in this case, we
will use the path to the key file on your filesystem to mount the file into the Docker container (we’ll get to this,
see the command below).team_id
: This is the Team ID your Apple Developer account is associated with.
services_id
: This is Services ID
you created in the Register a Services ID step. You
can always review this ID in the Apple Developer console:
Identifiers
in the sidebar,
then select Services IDs
from the dropdown menu on the right.Identifier
column).key_id
: This is the ID of the private key from the previous step.
The XXXXXXXXXX
part of the default AuthKey_XXXXXXXXXX.p8
filename is the key ID. You can
also review this ID in the Apple Developer console:
Keys
in the sidebar,
then select Services IDs
.View Key Details
> Key ID
As previously mentioned, we will mount the private_key
to the container by mapping the path on your filesystem to
a path on the container filesystem, e.g. ~/Downloads/AuthKey_XXXXXXXXXX.p8:/tmp/AuthKey_XXXXXXXXXX.p8
.
From the command line, run (replace <...>
placeholders with your data):
The command will save the client secret in a file client_secret.txt
.
Secrets expire after 6 months and must be regenerated before the expiration.
Configure Apple Credentials with Hanko
Head back to Identity providers in Hanko and under ‘Identity provider settings’ configure the following:
Error Redirect URL: This URL, on your frontend, is where the Hanko API redirects if an error occurs during third-party sign-in. With hanko-elements web components, it should link to the page embedding the web component to process errors correctly.
Allowed Redirect URL: A URL on your frontend that the Hanko API can redirect to after a successful third-party authentication. Using hanko-elements web components? Make it the URL of the embedding page.
Supports wildcard matching through globbing:
https://*.example.com
matches https://foo.example.com
and https://bar.example.com
.https://foo.example.com/*
matches URLs like https://foo.example.com/page1
and https://foo.example.com/page2
.In the ‘Providers’ section, select Google and enable its toggle switch.
Input the earlier noted ‘Services ID’ and ‘Secret Key’, then click ‘Save’.
Implement Apple Login in Your Frontend Application
Whether you choose to use the pre-designed UI from the @teamhanko/hanko-elements
package or opt for a custom UI with the @teamhanko/hanko-frontend-sdk
will determine your approach to frontend integration.
Integrate the <hanko-auth>
component from hanko-elements
based on our frontend guides. If everything is good, the component will display a button for signing in with ‘Github’ in login view.
Make sure to configure the page the web component is embedded on as your error redirect URL as well as an allowed redirect URL.
Post successful GitHub authentication, the backend sets a session cookie and errors during authentication are displayed within the component accordingly.
Integrate the <hanko-auth>
component from hanko-elements
based on our frontend guides. If everything is good, the component will display a button for signing in with ‘Github’ in login view.
Make sure to configure the page the web component is embedded on as your error redirect URL as well as an allowed redirect URL.
Post successful GitHub authentication, the backend sets a session cookie and errors during authentication are displayed within the component accordingly.
For a custom UI, initialize third party sign-in using @teamhanko/hanko-frontend-sdk
.
Create Hanko client instance and call thirdParty.auth
with github as the provider.
On successful authentication, the API redirects you to the given redirect URL. The URL query includes a one time token that must be exchanged for a JWT. Use the token.validate
method on your client to validate the token:
On success, the API issues a JWT which is then set by the SDK as a cookie (hanko). All other SDK methods can now use the cookie to make authenticated requests to the API.
Sign in with Apple gives allows users to hide their original email address when authorizing your app during the authentication flow and instead use an anonymous, automatically generated email address. Emails are then routed through Apples private relay email service. In order to send email messages through the relay service to the users’ personal inboxes (Hanko sends out passcodes for email verification and account recovery), you’ll need to register your outbound email domains. All registered domains must create Sender Policy Framework (SPF) DNS TXT records in order to transit Apple’s private mail relay.
If a user signs up using Sign in with Apple
and chooses to hide their real email address, then the
private relay address will become the primary email for the user. Should a user then choose to sign in with an email
address (and not via Sign in with Apple
), then the private relay email address must be used, not the real email
address associated with her Apple account.
Services
in the
left sidebar.Sign in with Apple for Email Communication
panel, click Configure
.Email Sources
heading, click the add (+
) button.Register your email sources
modal, enter your Domains and Subdomains
and/or specific Email Addresses
.
hanko.io
in
the Domains and Subdomains
input. You do not need to provide an SPF DNS record by yourself.Domains and Subdomains
input. Remember to provide an SPF DNS record for your domain in order
to pass Apple’s SPF check.Next
, then click Register
.Email Sources
table. Emails are only relayed if the SPF check (see the Status
column) was successful.If you use Hanko Cloud and are on a paid subscription tier you can configure your own SMTP server.
Organization
.Project
.Settings
, then select SMTP
.Sender email address
should be registered as an email source in the Apple developer
console to allow communication through Apple’s private relay service (see the previous step).Save
.