Ueberauth plugin for Apple OAuth / Sign In with Apple
Ueberauth is an authentication framework for Elixir applications that specializes in OAuth. This library is one of many plugins (called Strategies) that allow Ueberauth to integrate with different identity providers. Specifically, this one implements an OAuth integration with Apple, for their Sign In with Apple service.
Apple's OAuth implementation is different than you may expect. Please keep the following in mind:
-
There are only two scopes available,
name
andemail
, for retrieving personal information about the user signing in. Neither scope provides access to any API endpoints; instead they change the data returned during the sign-in process. -
If any scopes are requested during sign-in, the response from Apple must be in the form of a form POST request to your application. Otherwise, a GET request with query parameters will occur. Accepting POST callbacks require additional setup with Ueberauth that may not be necessary for other providers.
-
Because scoped requests must use a form POST request, any cookies that will be read during the callback phase must have
SameSite=None
(and, therefore,Secure
). Otherwise the browser will block them from being sent along with the POST because it is not a top-level navigation. -
Apple requires a Primary App ID (with the Sign In with Apple capability enabled), Services ID, and Private Key to be set up in their Apple Developer Console before integration can occur.
-
Apple OAuth Client Secrets are generated from a Private Key and have a maximum lifetime of six months.
-
Users may choose not to share their information with your application, in which case an anonymized private relay email address will be supplied during the callback phase.
-
Apple does not supply the user's name in callback responses after the first time.
For detailed instructions, see Getting Started.
-
Set up a Services ID and download a Private Key in the Apple Developer Console. See Getting Started or the official documentation for more information
-
Add
:ueberauth_apple
to your list of dependencies inmix.exs
and runmix deps.get
:
def deps do
[
# ...
{:ueberauth, "~> 0.10"},
{:ueberauth_apple, "~> 0.6.1"}
]
end
- Add this library as a new provider for Ueberauth (see Getting Started for more information on the available options):
config :ueberauth, Ueberauth,
providers: [
# Default configuration: does not retrieve name or email address during sign-in.
apple: {Ueberauth.Strategy.Apple, []}
# Alternative configuration: retrieve name and email during sign-in.
apple: {Ueberauth.Strategy.Apple, callback_methods: ["POST"], default_scope: "name email"}
]
- Configure the provider (see Getting Started for more information on generating client secrets):
config :ueberauth, Ueberauth.Strategy.Apple.OAuth,
client_id: System.get_env("APPLE_CLIENT_ID"),
client_secret: {MyApp.Apple, :client_secret}
-
Create a Client Secret generator function. (Apple's Client Secrets are generated from a Private Key and have a maximum life of six months.)
-
Integrate Ueberauth with the rest of your application (usually: router and controller). See Getting Started or the Ueberauth Example application.
Making a request to /auth/apple
will redirect to the Apple sign-in page with the relevant query parameters.
You can include a scope
query param to configure the scopes at runtime: /auth/apple?scope=name%20email
.
The default scopes can also be configured in the provider definition.
To guard against client-side request modification, it's important to still check the domain in info.urls[:website]
within the Ueberauth.Auth
struct if you want to limit sign-in to a specific domain.
Thank you to Loop Social for the original implementation of this library.
Thank you to CodeSandbox for updates and maintenance of this library.
Please see LICENSE for licensing details.