Social Login

Apple

This document explains how to configure

Apple

as an external social Identity Provider (IdP) for your application by creating an application at

Apple

, creating an Identity Provider in Okta, testing the configuration, and creating a sign-in button.

Okta manages the connection to the IdP for your application, sitting between your application and the IdP that authenticates your users. The industry-standard term for this is Inbound Federation. When a user signs in, you can link the user’s

Apple

account to an existing Okta user profile or choose to create a new user profile using Just-In-Time (JIT) provisioning.

Note: We also support additional services such as directories and credential providers. See the Okta Integration Network Catalog (opens new window) to browse all integrations by use case.

---

Learning outcomes

Configure a social Identity Provider so that your users can quickly sign up or sign in to your application by using their social Identity Provider account.

What you need

• Okta Developer Edition organization (opens new window)
• An OpenID Connect (OIDC) app integration in Okta for the app that you want to add authentication to. You can create a new OIDC app integration (opens new window) or use an existing one.
• An account with

  with Apple (opens new window)

---

Create an app at the Identity Provider

At Apple, create the client application that you want to use for authenticating and authorizing your users. See Sign in with Apple (opens new window).

There are three steps necessary to configure the Identity Provider at Apple:

• Create an App ID: An App ID enables your app to access available services and identifies your app in a provisioning profile with Apple.
• Create a Services ID: The Services ID identifies the particular instance of your app. The Services ID is used as the OAuth client_id.
• Create a private key for client authentication: Apple uses a public/private key pair as the client secret. You must register a new private key with Apple and download the key file to use with Okta.

Create an App ID

1. From the Apple Developer Dashboard (opens new window) left navigation, click Certificates, IDs & Profiles.

2. Select Identifiers from the left and then click the blue plus icon.

3. Select App IDs if it isn't already selected, and then click Continue.

4. Enter a description and a Bundle ID for the App ID. Apple recommends using a reverse-domain name style string for the Bundle ID (for example, if the domain your app runs on is example.com, then enter com.example as the Bundle ID.)

   Note: You can't edit this identifier after you create it, you can only remove it and create a new one.

5. Scroll down and select the Sign In with Apple check box, click Continue, and then Register.

Create a Services ID

1. On the Identifiers page, click the blue plus icon, and select Services IDs.

2. After you click Continue, enter a name for the identifier in the Description box. This is what the user sees when they sign in.

3. In the Identifier box, enter the identifier in a reverse-domain name style string (for example, if the domain your app runs on is example.com, then enter com.example.client as the identifier.). This identifier becomes the OAuth client_id.

   Note: The Services ID identifier can't be the same as the App ID identifier.

4. Click Continue and then Register. The Identifiers page appears.

5. Select the identifier that you just created.

6. Select the Sign In with Apple check box, and then click Configure to define the domain your app is running on and the redirect URLs used during the OAuth flow.

7. If it isn't already selected, select the App ID that you just created from the Primary App ID drop-down box.

8. Enter the domain name where your app runs in the Domains and Subdomains box. Be sure to enter a real domain. Domains such as localhost or IP addresses such as 127.0.0.1 won't work.

9. In the Return URLs box, paste the Okta redirect URI into the Return URLs box. The redirect URI sent in the authorize request from the client needs to match the redirect URI in the Identity Provider (IdP). This is the URL where the IdP returns the authentication response (the access token and the ID token). It needs to be a secure domain that you own. This URL has the same structure for most Identity Providers in Okta and is constructed using your Okta subdomain and then the callback endpoint.

   For example, if your Okta subdomain is called company, then the URL would be: https://company.okta.com/oauth2/v1/authorize/callback. If you have configured a custom domain in your Okta Org, use that value to construct your redirect URI, such as https://login.company.com/oauth2/v1/authorize/callback.

   Include all base domains (Okta domain and custom domain) that your users will interact with in the allowed redirect URI list.

10. Click Next, Done, Continue, and then Save.

Create a private key for client authentication

Register a new private key for sign in with Apple.

1. On the Certificates, Identifiers, & Profiles page, select Keys and then Create a key.

2. Give your key a name, select the Sign In with Apple check box, and click Configure.

3. Select your App ID from the Primary App ID drop-down box and click Save. Apple generates a new private key.

4. Click Continue, Register, and then Download.

   Important: Make sure that you save the downloaded key file because you can't get it back later. Apple removes the server copy, so you can only download the key file once.

5. Click Done, and then on the Keys page, click the key that you just created and make note of the Key ID. You need it in the next section.

6. Make note of the Team ID, which is a 10 character (alphanumeric) ID in your Apple developer account. You can find this ID in the upper-right corner of your Apple developer dashboard just below your account name.

Hide My Email for Sign in with Apple

If you choose to hide your email (opens new window), you need to update your email sources within Apple's Developer Settings:

1. From the Apple Developer Dashboard (opens new window) left navigation, click Certificates, IDs & Profiles, and then More.
2. Click Configure.
3. Click the plus sign (+) next to Email Sources and add mailrelay.okta.com in the Domains and Subdomains box.
4. Click Next, Register, and then Done.
5. Verify your changes by signing in to your Okta Admin Console, selecting Sign in with Apple, and verifying that a verification email is successfully sent to you.

Create the Identity Provider in Okta

To add

Apple

as an Identity Provider in Okta:

1. In the Admin Console, go to Security > Identity Providers.

2. Click Add Identity Provider, and then select

   Apple

   IdP.

3. Click Next.

4. In the General Settings section, define the following:

   • Name: Enter a name for the Identity Provider configuration.

   • Client ID: Paste the Services ID that you obtained from Apple when you configured the Identity Provider in the previous section. The Services ID identifies the particular instance of your app and is used as the OAuth client_id.

   • Client Secret Signing Key: Click Browse files and locate the key file (.p8 format) that you downloaded from Apple when you created the private key for client authentication in the previous section.

   • Key ID: Enter the Key ID that you obtained from Apple when you created the private key for client authentication in the previous section. The Key ID represents the private key generated by Apple.

   • Team ID: Enter your Apple Team ID value from your Apple developer account. You can find this ID in the upper-right corner of your Apple developer dashboard just below your account name.

   • Scopes: Leave the defaults. These scopes are included when Okta makes an OpenID Connect request to Apple. See the scope (opens new window) property for Sign in with Apple.

     By default, Okta requires the email attribute for a user. The email scope is required to create and link the user to Okta's Universal Directory. For Just In Time (JIT) provisioning, Okta also requires the firstName and lastName attributes for a user. Include the name scope if the Identity Provider needs to support JIT.

5. Click Finish. A page appears that displays the IdP's configuration.

Note: If you want to use a specific Redirect Domain instead of the Dynamic default, you can use either Org URL or Custom URL. See issuerMode in the Identity Provider attributes section.

6. Copy both the Authorize URL and the Redirect URI, which ends in /authorize/callback.

Note: When you're setting up your IdP in Okta, there's a number of settings that allow you to finely control the social sign-in behavior. While the provider-specific instructions show one possible configuration, Account Linking and JIT Provisioning discusses configuration options in more detail so that you can choose the right configuration for your use case.

Note: See the Identity Providers API for request and response examples when creating an Identity Provider in Okta using the API.

Test the integration

You can test your integration by configuring a routing rule (opens new window) to use

Apple

as the Identity Provider.

Alternatively, you can use the Authorize URL to simulate the authorization flow. The Okta Identity Provider that you created generated an authorize URL with a number of blank parameters that you can fill in to test the flow with the Identity Provider. The authorize URL initiates the authorization flow that authenticates the user with the Identity Provider.

In the URL, replace ${yourOktaDomain} with your org's base URL, and then replace the following values:

• client_id: Use the client_id value from your Okta app integration. This is not the client_id from the Identity Provider. For example, 0oawjqpb2wcUAWM8C0h7.

• response_type: Determines which flow is used. For the Implicit flow, use id_token. For the Authorization Code flow, use code.

• response_mode: Determines how the authorization response is returned. Use fragment.

• scope: Determines the claims that are returned in the ID token. Include the scopes that you want to request authorization for and separate each with a %20 (space character). You need to include at least the openid scope. You can request any of the standard OpenID Connect scopes about users, such as profile and email as well as any custom scopes specific to your Identity Provider.

• redirect_uri: The location where Okta returns a browser after the user finishes authenticating with their Identity Provider. This URL must start with https and must match one of the redirect URIs that you configured in the previous section.

• state: Protects against cross-site request forgery (CSRF). This can be set to any value.

• nonce: A string included in the returned ID token. Use it to associate a client session with an ID token and to mitigate replay attacks. This can be set to any value.

For a full explanation of all of these parameters, see: /authorize Request parameters.

An example of a complete URL looks like this:

https://${yourOktaDomain}/oauth2/v1/authorize?idp=${idp_id}&client_id=${client_id}&response_type=id_token&response_mode=fragment&scope=openid%20email&redirect_uri=https%3A%2F%2FyourAppUrlHere.com%2F&state=WM6D&nonce=YsG76jo

To test your authorization URL, enter the complete authorization URL in a browser. Do this in your browser's privacy or incognito mode to avoid false positive or negative results.

If everything is configured properly:

• The user is redirected to the Identity Provider's sign-in page.
• After successful authentication, the user is redirected to the redirect URI that you specified, along with an #id_token= fragment in the URL. The value of this parameter is your Okta OpenID Connect ID token.

If something is configured incorrectly, the authorization response contains error information to help you resolve the issue.

Note: With Sign In with Apple, when a user signs in, Apple offers the user the option to either share their email address or hide it. If the user chooses to hide their email address, Apple generates a random email address and sends that to Okta. However, Apple maintains the mapping between this random email address and the user's original email address. The user must choose the Share My Email option if you want to link the user's Apple account to an existing account in Okta. A user can choose this option only when the user is signing in with Apple to Okta for the first time.

Add the Identity Provider to the embedded Okta Sign-In Widget

Note: This section only applies to Okta Classic Engine.
If you're using Okta Identity Engine, the Sign in with IdP option is available on the widget after you create the Identity Provider in your Okta org and configure the routing rule (opens new window). No additional code is required. See Identify your Okta solution (opens new window) to determine your Okta version and Upgrade your widget for upgrade considerations to Identity Engine.

The Okta Sign-In Widget (opens new window) is an embeddable JavaScript widget that reproduces the look and behavior of the standard Okta sign-in page. You can add a Sign in with

Apple

button to the widget by adding the following code to your Okta Sign-In Widget configuration.

    config.idps= [
        { type: 'APPLE', id: 'Your_IDP_ID' }
    ];
    config.idpDisplay = "SECONDARY";

Replace Your_IDP_ID with the Identity Provider ID from your Identity Provider that you created in Okta in the Create the Identity Provider in Okta section. To find your Identity Provider ID:

1. In the Admin console, go to Security > Identity Providers.
2. On the Identity Providers page, select the Identity Provider tab.
3. Select your Identity Provider from the list. IdP ID contains your Identity Provider ID.

Add the Identity Provider to the custom Okta-hosted sign-in page

Note: This section only applies to Okta Classic Engine.
If you're using Okta Identity Engine, the Sign in with IdP option is available on the widget after you create an Identity Provider in your Okta org and configure the routing rule (opens new window). See Identify your Okta solution (opens new window) to determine your Okta version.

If you configured a custom Okta-hosted Sign-In Widget, you can add a Sign in with

Apple

button by adding the following code beneath the var config = OktaUtil.getSignInWidgetConfig(); line in the Sign-in page code editor of the Admin Console.

    config.idps= [
        { type: 'APPLE', id: 'Your_IDP_ID' }
    ];
    config.idpDisplay = "SECONDARY";

Replace Your_IDP_ID with the Identity Provider ID from your Identity Provider that you created in Okta in the Create the Identity Provider in Okta section.

Next steps

You should now understand how to add a social Identity Provider and have successfully added and tested the integration.

To map Okta attributes to app attributes, use the Profile Editor (opens new window).

To add another Identity Provider, start by choosing an external Identity Provider.