Apple

Overview

The Akeeba Social Login - Sign in with Apple plugin allows you to use the Sign in with Apple service. This lets users with an Apple ID to register and login to your site. Users on Apple devices with biometric access features (TouchID, FaceID) can register and login to your site using biometric controls.

Please note that the Sign in with Apple feature is very finicky on Apple's side and a pain to set up. This is a feature that makes most sense if you are using your Joomla site to provide a login feature for an iOS, iPadOS, macOS or tvOS app. You can of course use it without an app but it's currently a lot of pain without clear benefits. Please bear in mind that all the restrictions and requirements outlined below are imposed by Apple itself and we cannot work around them. We consider this feature something that only very advanced users with a deep understanding of the Apple developer ecosystem should try integrating on their site.

Caveats

The Sign in with Apple service is provided by Apple, Inc for a fee. It requires you to have an up-to-date Apple Developer membership which, at the time of this writing, costs US$99 per year.

The user signing up with Apple may choose to remit their real email address or an anonymised, proxy email address handled by Apple. In the latter case it's impossible to match existing user accounts with a new sign-in coming through Apple unless the user has logged in to your site, edited their user profile and linked their Apple account with their Joomla user account.

Setup on Apple Developer

DISCLAIMER: This part of our documentation describing the interaction with a third party service is for information purposes only. It should be treated as indicative and used at your own risk. Akeeba Ltd can only attest that this part of the documentation has been the faithful transcription of the steps we took at the time of its writing. We strongly recommend that you consult the documentation of the third party service for accurate instructions. Should the behavior of the third party service differ from what is published in our documentation you should consult the support of the third party service provider. Do not seek support from us for such matters; Akeeba Ltd cannot provide support for third party services, is not responsible for or notified about any changes in said services, nor is it obligated to update the documentation pursuant such changes.

Conceptually, there are four distinct items you need to set up on the Apple Developer site to enable the Sign in with Apple feature for your site:

• An App ID. This does not necessarily mean that you need to create an iOS, iPadOS, macOS or tvOS application for your site. It's simply an identifier. If you already have an existing application you can use the App ID you have already created. Caveat: if you do NOT have an iOS, iPadOS, macOS or tvOS application for your site you will see a grey square in the Sign in with Apple interface instead of your site's logo. There's no workaround to that. Also note that the Description of the App ID is what your users see as the name of your site when they are signing up / logging into your site and in their Apple ID account under Security.
• A Services ID linked to the App ID (or a Bundle ID which includes the App ID). This is what enables the Sign in with Apple feature.
• A Key which is linked to the Services ID. This is used to identify your site to Apple's servers during the sing in process.
• Email forwarding setup. If you do not complete this step the Sign in with Apple will always fail.

Further to that, do note the requirements for your site:

• Your site must be using HTTPS and support at least TLS v1.2. You cannot use Sign in with Apple on HTTP sites or HTTPS sites which only support TLS v1.1 or earlier.
• Your site must use SPF or DKIM to validate email sending. You cannot use Sign in with Apple if your site does not have an SPF or DKIM record or if it has no MX record.
• All emails used by your site and your site staff must be registered in the Apple Developer site for email forwarding and they must belong to an SPF- or DKIM-enabled domain that you have also registered in the Apple Developer site.
• You can only assign an email address to one set of domains. You cannot use the same email address on multiple domains.

These are limitations of the Apple platform and we can NOT work around them.

Create an App ID

Go to https://developer.apple.com/account/

Click on “Certificates, IDs and Profiles” from left hand menu.

Click on “Identifiers”.

From the top right click the dropdown next to the magnifier glass and select App IDs.

Click the + icon to add a new identifier.

Select “App IDs”, click on Continue.

Select “App”, click on Continue.

The Description you enter here is what will be visible to users logging into your site. Best use the same name as your site.

For Bundle ID select Explicit and type a reverse domain, e.g. com.example for loging into any subdomain of example.com.

Scroll down the Capabilities list and select Sign In with Apple.

Go back towards the top right and click on Continue.

Finally, click on Register.

Create a Services ID

Go to https://developer.apple.com/account/

“Certificates, IDs and Profiles” from left hand menu.

“Identifiers”

From the top right click the dropdown next to the magnifier glass and select Service IDs

Click the + icon to add a new identifier.

Select “Services IDs”, click on Continue.

• Description: anything you like e.g. "My Site Login"
• Identifier: reverse domain, e.g. com.example for loging into any subdomain of example.com.

Click on Register

Click on the identifier you just created.

Check the Enabled checkbox next to Sign In with Apple. Then click the Configure button next to it. A popup appears.

There are two text areas:

• Domains and Subdomains. Comma separated list of domains and subdomains e.g. example.com, www.example.com
• Return URLs. Comma separated list of authorized return URLs, one for each subdomain defined above, in the form of http://www.example.com/index.php?option=com_ajax&group=sociallogin&plugin=apple&format=raw

Click Next, then Done.

Click on the Continue button towards the top right.

Caveat: you cannot use localhost; or any domain name which doesn't have DNS set up yet; or a domain name that resolves to any of the reserved IP ranges (internal networks and localhost IPs). Moreover, you should make sure that your domain name is using SPF or DKIM for its emails.

Create a Private Key

Go to https://developer.apple.com/account/

“Certificates, IDs and Profiles” from left hand menu.

“Keys”

Click the + icon to add a new key.

Key Name: anything you like, e.g. "Site Login Key"

Check the Sign in with Apple checkbox. Then click the Configure button next to it.

For the Primary App ID select the App ID you created at the beginning of these instructions and click on Save.

Back to the Register a New Key page, click on the Continue button towards the top right.

Finally, click on Register.

Now click on Download to download your key file. This is a text file. You will need its contents to set up the plugin.

Do not forget to set up the email forwarding

As noted above, it requires SPF or DKIM for the domain.

You must set up the email addresses you are using for your site's emails and any emails which will be corresponding with your clients. This is important if you are using a forum or ticket system which uses a different email address than the one configured on your site's Global Configuration; or more than one people are likely to reply to contact forms or other transactional emails sent by your site to the user's Apple-proxied email address.

Plugin options

Client ID (Services ID) Enter the Services ID you created on the Apple Developer site.

Team ID Enter the Team ID from your Apple Developer account. You can see it at the top right corner of the Apple Developer page under your team's name.

Key ID When you created a Key earlier you were displayed the Key ID. You need to enter it here.

Secret Key When you created a Key earlier you were asked to download a file. This file has a name similar to AuthKey_ABCDEF01234.p8. The p8 extension means “PKCS#8 encoded” which is the same encoding as all HTTPS certificates you've seen. In other words, this is actually a text file. Open it with a text file editor such as TextEdit (macOS), Notepad (Windows) or gEdit (Ubuntu) and copy all of its contents. Paste them to the Secret Key text area in the plugin settings.

Allow social login to non-linked accounts When enabled allows users to log in despite not having linked their Apple account to their site user account. Caveat: for this to work the user must choose to share their real email address with your site and this email address must match exactly the email address associated with their user account on your Joomla! site.

Create new user accounts Creates a new Joomla! user when a user tries to log in via Apple but there is no Joomla! user account associated with either the Apple ID or the email address they chose to share with your site. If user registration is disabled no account will be created and an error will be raised – unless the “Ignore Joomla! setting for creating user accounts” option below is enabled. The new Joomla! user will have a username derived from the full name the user chose to share with your site, the email address the user chose to share with your site and a long, random password (which the user can change once they have logged in). Set this to No to prevent creation of user accounts through Apple login.

It is possible that no full name is shared with your site. This can happen for two reasons. First, the user opted out from sharing their full name with your site. Second, something you will see happening when testing the integration, the user is trying to create a new user account with an Apple ID that was already associated with the App ID you are using on your site. The latter can occur if you deleted the user that was created when the user first signed into your site with Apple or if you are using the same App ID for more than one sites. In case there was no full name shared through the Sign in with Apple for any reason SocialLogin will create a random name and username made up from a non-offensive English adjective and a non-offensive English noun, e.g. “Lunar Pizza”. This is most likely not a username they'd like to keep. For this reason you should let users change their username; it's in the Options page of the Users component in your Joomla's backend.

Ignore Joomla! setting for creating user accounts When both this option and the Create new user accounts option above are enabled a new user will always be created, even if you have disabled user registration in the options of Joomla's Users page.

Bypass user validation Only applies when creating new user accounts. When enabled the new user will be created active, without going through the Joomla! user account validation. This means that no account activation email will be sent to the user or the administrators of the Joomla! site. This makes perfect sense since Apple has already verified that the user is in control of the email address they are using with their Apple account.

Use image button We strongly recommend that you leave this option enabled. Apple requires that the Sign in with Apple button be displayed using an image they generate through their servers. Enabling this option does exactly that unless you are using Joomla 4 and have enabled the Joomla 4 additional login button integration in the System - Akeeba SocialLogin plugin's options. If this option is disabled a regular button is rendered with the Apple logo and text which can be translated or changed through Joomla's language overrides feature.

Button styling When enabled custom CSS for login, link and unlink button styling will be output to the page header. Disable this option if you intend to use your own CSS to style the buttons. You should keep this option enabled even if you use the image button option above.

Icon class The icon CSS class to use in the login (if “Use image button” is disabled or using Joomla 4 with the Joomla 4-specific additional login button integration), link and unlink buttons. Useful to use an icon font such as FontAwesome or Glyphicons to render the logo. If it's left empty, a PNG image with the Apple logo will be used instead.