Article

Configuring Your Webpage for Sign in with Apple

Ensure your webpage is ready to authorize users through Sign in with Apple.

Overview

Use HTML and JavaScript to add Sign in with Apple to your webpage. Configure the authorization object and add a button that allows users to sign in to your webpage with their Apple ID.

Embed Sign in with Apple JS in Your Webpage

Use the script tag and link to Apple’s hosted version of the Sign in with Apple JS framework:

<script type="text/javascript" src="https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js"></script>

Configure the Authorization Object

To get started quickly, configure Sign in with Apple JS with a default markup setup. Alternatively, use JavaScript to configure the authorization object, or use a combination of the two.

You can configure the authorization object using only markup by setting the meta tags in the header section and displaying a Sign in with Apple button, as in the following example:

<html>
    <head>
        <meta name="appleid-signin-client-id" content="[CLIENT_ID]">
        <meta name="appleid-signin-scope" content="[SCOPES]">
        <meta name="appleid-signin-redirect-uri" content="[REDIRECT_URI]">
        <meta name="appleid-signin-state" content="[STATE]">
        <meta name="appleid-signin-use-popup" content="true"> <!-- or false defaults to false -->
    </head>
    <body>
        <div id="appleid-signin" data-color="black" data-border="true" data-type="sign in"></div>
        <script type="text/javascript" src="https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js"></script>
    </body>
</html>

You can also configure the authorization object using the JavaScript APIs and display a Sign in with Apple button, as in the following example:

<html>
    <head>
    </head>
    <body>
        <script type="text/javascript" src="https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js"></script>
        <div id="appleid-signin" data-color="black" data-border="true" data-type="sign in"></div>
        <script type="text/javascript">
            AppleID.auth.init({
                clientId : '[CLIENT_ID]',
                scope : '[SCOPES]',
                redirectURI : '[REDIRECT_URI]',
                state : '[STATE]',
                usePopup : true //or false defaults to false
            });
        </script>
    </body>
</html>

You can combine the two options by setting the meta tags in the header and also use the JavaScript APIs. This provides a default implementation through the meta tags, but provides you with the ability to override the initial information using the JavaScript APIs.

Handle the Authorization Response

After the user clicks the Sign in with Apple button, the authorization information is sent to Apple. Apple processes the authorization request, an HTTP POST request containing the results of the authorization is sent to the URL provided in redirectURI. The HTTP body contains the result parameters with a content-type of application/x-www-form-urlencoded. A successful response contains the following parameters:

code

A single-use authentication code that is valid for five minutes.

id_token

A JSON web token containing the user’s identify information.

state

The state passed by the init function.

user

A JSON string containing the data requested in the scope property. The returned data is in the following format: { "name": { "firstName": string, "lastName": string }, "email": string }

If an error occurs, the HTTP body contains the following parameters:

error

The returned error code.

state

The state passed by the init function.

If you use the pop-up option, your app sends the authorization information to Apple when the user clicks the Sign in with Apple button. After Apple processes the authorization request, a DOM Event is dispatched containing the results of the authorization. The AppleIDSignInOnSuccess event is dispatched when the authorization succeeds, and AppleIDSignInOnFailure in case of a failure.

To handle the response, add an event listener:

//Listen for authorization success
document.addEventListener('AppleIDSignInOnSuccess', (data) => {
     //handle successful response
});
//Listen for authorization failures
document.addEventListener('AppleIDSignInOnFailure', (error) => {
     //handle error.
});

If the authorization flow started using the signIn function, it returns a promise that will get resolved if the authorization succeeds, or rejected if fails.

Here is an example of how to handle the response when usign the signIn function.

try {
     const data = await AppleID.auth.signIn()
} catch ( error ) {
     //handle error.
}

This data object is returned upon authorization success:

{
     "authorization": {
       "state": "[STATE]",
       "grant_code": "[CODE]",
       "id_token": "[ID_TOKEN]"
     },
     "user": {
       "email": "[EMAIL]",
       "name": {
         "firstName": "[FIRST_NAME]",
         "lastName": "[LAST_NAME]"
       }
     }
}

This data object is returned upon authorization failure:

{
    "error": "[ERROR_CODE]"
}

See Also

Essentials

Displaying Sign in with Apple Buttons

Use CSS styles and data attributes to display and configure Sign in with Apple buttons in browsers.

Communicating Using the Private Email Relay Service

Communicate with users who opted to use an anonymous email address with Sign in with Apple.