Add Apple Login
Obtain Apple Credentials
- Let’s get the redirect url first from Hanko console, as you’ll need it in a moment. To do so, sign in to Hanko and select your project. Navigate to ‘Settings’ in the left sidebar and then to ‘Identity Providers’. Copy the ‘Redirect URL’ from here.
Register App ID and Services ID
- To get started you need an Apple developer account and after you sign in, you’ll need to register an App ID.
- In Certificates, Identifiers & Profiles, click ‘Identifiers’ in the sidebar, then click the add button (+) on the top left.
- Select ‘App IDs’ from the list of options and click ‘Continue’. Then ‘Select App’ as the type and click ‘Continue’.
- Provide your app information: App ‘Description’ and ‘Bundle ID’ (Apple recommends using a reverse-domain name style string i.e.,
com.domainname.appname
). - In the ‘Capabilities’ tab below, check ‘Sign in with Apple’ and Click ‘Continue’, then review the registration information, then click ‘Register’.
- Now, you also need to register a ‘Services ID’. Go to Certificates, Identifiers & Profiles, click ‘Identifiers’ in the
sidebar, then click the add button (
+
) on the top. - Select
Services IDs
from the list of options and click ‘Continue’ and then provide your app information. - Click ‘Continue’, then ‘Register’.
Configure your Services ID
- On Certificates, Identifiers & Profiles, click
Identifiers
in the sidebar, then selectServices IDs
from the dropdown menu on the right. - Select the
Services ID
you created in the previous step. - Enable
Sign In With Apple
for theServices ID
by clicking the checkbox next to it. - Click
Configure
. - Select your previously registered
App ID
as yourPrimary App ID
. - In the shown modal, click the add button (
+
) next toWebsite URLs
. - Add the domain of your redirect URL to the
Domains and Subdomains
input (do not add a scheme, e.g.https://
, or path information). - In the
Return URLs
input, enter the complete redirect URL of your app which you found in the previous step. - Click
Next
at the bottom right. - Click
Done
at the bottom to close the modal. - Back on the
Edit your Services ID Configuration
view, clickContinue
at the top right, then clickSave
.
Create Key and download Key file
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.
- On Certificates, Identifiers & Profiles, click
Keys
in the sidebar, then click the add button (+
) next to theKeys
heading. - Enter a
Key Name
. - In the options table below the
Key Name
input, checkSign in with Apple
. - In the same table row, click
Configure
to the right. - In the
Configure Key
view, select your previously registeredApp ID
in thePrimary App ID
dropdown. - Click
Save
on the top right. - Back on the
Register a New Key
view, clickContinue
, then clickRegister
on the top right. - On the
Download Your Key
view, clickDownload
on the top right to save the key file. - Click
Done
on the top right.
Generate a client secret
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.- See Locate your Team ID in the official Apple documentation.
services_id
: This isServices ID
you created in the Register a Services ID step. You can always review this ID in the Apple Developer console:- On Certificates, Identifiers & Profiles, click
Identifiers
in the sidebar, then selectServices IDs
from the dropdown menu on the right. - Find the relevant entry in the list (the required value is the value in the
Identifier
column).
- On Certificates, Identifiers & Profiles, click
key_id
: This is the ID of the private key from the previous step. TheXXXXXXXXXX
part of the defaultAuthKey_XXXXXXXXXX.p8
filename is the key ID. You can also review this ID in the Apple Developer console:- On Certificates, Identifiers & Profiles, click
Keys
in the sidebar, then selectServices IDs
. - Select your key in the list.
- The ID can be found under
View Key Details
>Key ID
- On Certificates, Identifiers & Profiles, click
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):
docker run -v <key_file_on_host>:<key_file_in_container> ghcr.io/teamhanko/hanko siwa \
--private_key <key_file_in_container> \
--team_id <your_team_id> \
--services_id <your_services_id> \
--key_id <your_key_id> > client_secret.txt
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
matcheshttps://foo.example.com
andhttps://bar.example.com
.https://foo.example.com/*
matches URLs likehttps://foo.example.com/page1
andhttps://foo.example.com/page2
.- Use ** to act as a super-wildcard/match-all.
-
-
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 fromhanko-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.
On using Apple’s private email relay service
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.
Register domains with Apple
- On Certificates, Identifiers & Profiles, click
Services
in the left sidebar. - In the
Sign in with Apple for Email Communication
panel, clickConfigure
. - Next to the
Email Sources
heading, click the add (+
) button. - In the
Register your email sources
modal, enter yourDomains and Subdomains
and/or specificEmail Addresses
.- If you use Hanko Cloud and do not want to use a custom SMTP server, enter
hanko.io
in theDomains and Subdomains
input. You do not need to provide an SPF DNS record by yourself. - If you use Hanko Cloud and do want to use a custom SMTP server, enter your
custom domain in the
Domains and Subdomains
input. Remember to provide an SPF DNS record for your domain in order to pass Apple’s SPF check.
- If you use Hanko Cloud and do not want to use a custom SMTP server, enter
- Click
Next
, then clickRegister
. - Your domains should be listed in the
Email Sources
table. Emails are only relayed if the SPF check (see theStatus
column) was successful.
Configure SMTP with Hanko
If you use Hanko Cloud and are on a paid subscription tier you can configure your own SMTP server.
- Sign in to cloud.hanko.io.
- Select your
Organization
. - Select your
Project
. - In the left sidebar, click
Settings
, then selectSMTP
. - Enter your SMTP credentials and sender data.
- The domain of your
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).
- The domain of your
- Click
Save
.
Was this page helpful?