Custom Social Login with Apple | Descope Documentation

When integrating Descope flows in a website, often you'll want to allow Social Login with Apple as one of the authentication methods for your users. However, when you sign in with the flow, the Apple sign-in page will not be personalized to your website domain by default. This tutorial will cover creating your custom Apple login so the login process is personalized to your domain.

Note

This guide is specifically for Apple Social Login.

The default Descope login app looks like the below within the Authentication Methods page within the Descope console for the Apple provider.

However, if you use the Descope login app, the sign-in page will default to show Create an account for Descope using your Apple ID "example@company.com".

Configuring the CNAME

You will need to create to enable a custom domain within your environment. If you still need to configure the custom domain, review the Configuring CNAME and Managing Sessions in Cookies guide for a step-by-step guide for configuring the custom domain and managing sessions within cookies.

Apple Configuration

Once you have a project with a configured custom domain, you can create the necessary items within Apple's developer portal.

Create Application ID

Once logged into your Apple developer account, go to Certificates, Identifiers & Profiles. Here, you will start by creating our Application ID. Click the + next to Identifiers and select App IDs.

After clicking continue to the next page, select the type as App and click continue.

Now configure the Description and the Bundle Id. If your domain is mycompany.com, the Bundle ID should be configured as com.mycompany.

While still on the same page, scroll down and check the Sign In with Apple box. You can click the Edit button depending on your configuration to select whether it is grouped to an existing primary App ID. Within this example, it is configured to Enable as a primary App ID.

Now click continue and then register to complete the application ID registration.

Create Service ID

Now go to Service Identifiers and ensure from the top right drop-down you are under Services IDs. We will then click + next to Identifiers and select Services IDs.

After clicking continue, you must configure your Description (which will be what the user sees during the Apple login process) and the Identifier. The identifier should be the CNAME configured for your application when stepping through the Configuring CNAME and Managing Sessions in Cookies guide. Since our domain for this example is mycompany.com, our CNAME would likely be auth.mycompany.com, so our Identifier will be com.mycompany.auth. After configuring, click continue and register to complete the service ID registration.

Create Key

Go to Keys and click the + next to Keys. Here you will give the key a name and check the box for Sign in with Apple.

Then click the edit icon to the right of Sign in with Apple. Then select your primary application ID, which you created here. Then click save, continue, and then register.

On the next screen, take note of Key ID and download the key.

Update the service ID

Now go to Service Identifiers and select the key you made above, then check the box for Sign in with Apple and click configure. Here, you will add any domains and subdomains associated with your application. For this example, the domains and subdomains would include minimally mycompany.com and auth.mycompany.com. Then you will also configure the callback URLs, which would also minimally be https://auth.mycompany.com/v1/auth/oauth/callback and https://auth.mycompany.com/v1/oauth/callback.

Then click done, continue, etc, until you have saved your Service ID. This completes the configuration within Apple.

Register domain for private relay

In cases where the user signs up with an option to hide their email, if correct domains are not setup, the email through relay service tends to not be sent to users' inboxes. There needs to be a way to handle apple's private email relay service. For this to be handled, go to this link and configure the applicable domains: auth.custom_domaim_cname.com & custom_domaim_cname.com. For more information, refer to thislink.

Configure Descope

Once you have successfully created your application within your Apple Developer account, it's time to configure your application within Descope. You will need to decrypt the key to get the client secret. Once you have the decrypted client secret, you can continue with the configuration within the Authentication Methods page.

Decrypt the key

Below, you can find example scripts for NodeJs and Python, allowing you to decrypt the key to get the client secret.

Install Dependencies

Terminal

npm install jsonwebtoken

Decryption Scripts

Update the placeholders within the script with your KeyID which was generated when you created the key, your ClientID which is the Identifier of the created service ID, and your TeamID which can be found at the top right of your Apple Developer console.

const jwt = require('jsonwebtoken');
const fs = require('fs');
 
// Replace the placeholders with your actual values
const keyFilePath = './AuthKey_<KeyID>.p8';
const teamId = '<TeamID>';
const clientId = '<ClientID>';
const keyId = '<KeyID>';
 
// Read the ECDSA key
const ecdsaKey = fs.readFileSync(keyFilePath, 'utf8');
 
// Define the headers and claims
const headers = {
    'kid': keyId
};
 
const currentTime = Math.floor(Date.now() / 1000);
const claims = {
    'iss': teamId,
    'iat': currentTime,
    'exp': currentTime + (180 * 24 * 60 * 60), // 180 days in seconds
    'aud': 'https://appleid.apple.com',
    'sub': clientId
};
 
// Encode the JWT
const token = jwt.sign(claims, ecdsaKey, {
    algorithm: 'ES256',
    header: headers
});
 
// Print the client ID and token
console.log(`client_id: ${clientId}`);
console.log(`client_secret: ${token}`);

Configure Provider

Go to Authentication Methods, select Apple, then select Use my own account and fill out the applicable details for Client ID and Client Secret. Optionally, you can choose to Manage tokens from provider if you want Descope to store the provider's access token in an encrypted state for later use.

Test Apple Provider

Test that your provider shows your company name during the login flow.

Was this helpful?

On this page