--- title: Configuring social sign-on in Advanced Identity Cloud or PingAM description: PingOne Advanced Identity Cloud PingAM Android iOS JavaScript component: orchsdks page_id: orchsdks:journey:use-cases/external-idp/before-you-begin canonical_url: https://developer.pingidentity.com/orchsdks/journey/use-cases/external-idp/before-you-begin.html revdate: Fri, 13 May 2022 09:39:02 +0200 section_ids: configure_external_identity_providers: Configure external identity providers apple: Configuring Apple as an external identity provider signing_up_for_an_apple_developer_account: Signing up for an Apple developer account setting_up_application_redirection: Setting up application redirection the_redirect_url: The redirect URL setting_up_apple_sign_in: Setting up Apple sign in creating_an_app_id: Creating an app ID creating_a_service_id: Creating a service ID configuring_the_apple_sign_in_service: Configuring the Apple sign in service creating_a_key: Creating a key generating_a_client_secret: Generating a client secret configuring_the_client_id: Configuring the client ID facebook: Configuring Facebook as an external identity provider generating_a_hash_of_your_signing_key: Generating a hash of your signing key configuring_facebook_for_an_android_app: Configuring Facebook for an Android app configuring_facebook_for_an_ios_app: Configuring Facebook for an iOS app google: Configuring Google as an external identity provider enabling_native_android_social_authentication: Enabling native Android social authentication configure_advanced_identity_cloud_or_pingam: Configure Advanced Identity Cloud or PingAM enable_identity_providers: Enable identity providers configure_google_and_facebook: Configure Google and Facebook configure_apple: Configure Apple create_your_authentication_journey: Create your authentication journey create_users_for_a_specific_realm: Create users for a specific realm a_simple_social_authentication_journey: A simple social authentication journey social_authentication_and_local_username_password_journey: Social authentication and local username-password journey next_steps: Next Steps --- # Configuring social sign-on in Advanced Identity Cloud or PingAM [icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: android, set=fab]Android [icon: apple, set=fab]iOS [icon: js, set=fab]JavaScript In this section, you set your identity providers (IdP) to work with your apps through PingOne Advanced Identity Cloud and PingAM authentication journeys. ## Configure external identity providers [icon: apple, set=fab, size=3x] #### [Apple](#apple) Configure a Sign in with Apple client. [icon: facebook, set=fab, size=3x] #### [Facebook](#facebook) Configure Facebook for use as a social identity provider. [icon: google, set=fab, size=3x] #### [Google](#google) Configure Google for use as a social identity provider. ### Configuring Apple as an external identity provider #### Signing up for an Apple developer account You must enroll in the [Apple Developer program](https://developer.apple.com/programs/). | | | | - | ------------------------------------------------------------------------------------------- | | | *Apple Developer Enterprise Program* accounts are not able to configure Sign in with Apple. | #### Setting up application redirection After Apple processes the initial authorization request and the user is successfully authenticated, Sign in with Apple sends an HTTP POST request to PingOne Advanced Identity Cloud or PingAM containing the authorization results. For a web application (SPA) or an Android device, the POST request is sent to a dynamically created endpoint, specified in the Apple Sign In configuration as the redirect URL. ##### The redirect URL To complete Apple client set up, you need the full redirect URL. This URL is not made available until you fully set up the provider in PingAM. If you have already set up your Apple provider, the redirect URL resembles the following: ``` https:///am/oauth2//client/form_post/ ``` #### Setting up Apple sign in ##### Creating an app ID 1. Log in to your [Apple developer account](https://developer.apple.com/account). 2. In the Program resources category, under Certificates, Identifiers & Profiles, click Identifiers. 3. Click the plus button ([icon: plus, set=fa]) next to the Identifiers header. 4. Select App IDs, and click Continue. 5. Select App type, and click Continue. 6. Type a description of your app, and provide a `Bundle ID` using `reverse-domain name style`. For example `com.forgerock.ios.sdk.example`. 7. Select `Sign in with Apple`, and click Continue. 8. Review your entry, and click Register. ##### Creating a service ID 1. On the Identifiers page, click the plus button ([icon: plus, set=fa]) next to the Identifier header. 2. Select Service IDs, and click Continue. 3. Enter a description of your service. 4. Enter an `Identifier` that is similar to your app ID. For example, `.service`. 5. Click Continue. 6. Review your entry, and click Register. ##### Configuring the Apple sign in service 1. On the Identifiers page, click the dropdown next to the magnifying glass icon, and then select Services IDs. 2. Select the service ID you created. 3. Next to `Sign in with Apple`, click Configure. 4. Click the plus button next to the Website URLs header. 5. In Domains and Subdomains: * For JavaScript apps, enter the domains that host your app. For example, `sdkapp.example.org` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | During testing, do not use the `example.com` domain to host your application. Apple treats this domain differently than other domains, which can cause unexpected issues.Using `example.org` or any other domain does not present these same difficulties. | * For native Android and iOS apps, enter the domain of your PingOne Advanced Identity Cloud or PingAM instance. For example, `openam-forgerock-sdks.forgeblocks.com` 6. In Return URLs, enter the URL that Apple redirects users to after authentication. Users must be redirected back to PingOne Advanced Identity Cloud or PingAM to continue their authentication journey. The URL to use is dynamically created by PingOne Advanced Identity Cloud or PingAM when you configure identity providers, and uses the following syntax: * Advanced Identity Cloud `https:///am/oauth2//client/form_post/` * PingAM `https:///openam/oauth2/client/form_post/` 7. Click Next. 8. Review, and click Done. #### Creating a key Store your key in a safe location. You cannot download keys more than once. 1. On the developer account page, in the left navigation panel, click Keys. 2. Click the plus button next to the Keys header. 3. Enter your key name, and select Sign in with Apple. 4. Click Configure, select your primary app ID, and click Save. 5. Click Continue. 6. Review, and click Register. #### Generating a client secret The client secret for Apple sign is a JSON Web token (JWT). The JWT is more complex than a simple string. A common way of generating the JWT is to use the [jwt/ruby-jwt library](https://github.com/jwt/ruby-jwt). Before you create the JWT, you need to understand certain requirements. To learn about these requirements, see Apple's documentation about [generating and validating tokens](https://developer.apple.com/documentation/sign_in_with_apple/generate_and_validate_tokens#3262048). #### Configuring the client ID * For **Native iOS**: The `client_id` should be the `AppID` (bundle identifier) from the Apple Development portal. * For **Web** or **Android**: The `client_id` should be the `ServiceID` from the Apple Development portal. Example signing script: ```rb require "jwt" key_file = [Key file name] team_id = [Team ID] client_id = [AppID or Service ID] key_id = [Key ID] validity_period = 180 # In days. Max 180 (6 months) according to Apple docs. private_key = OpenSSL::PKey::EC.new IO.read key_file token = JWT.encode( { iss: team_id, iat: Time.now.to_i, exp: Time.now.to_i + 86400 * validity_period, aud: "https://appleid.apple.com", sub: client_id }, private_key, "ES256", header_fields= { kid: key_id } ) puts token ``` ### Configuring Facebook as an external identity provider To use Facebook as an Identity Provider, visit the [Facebook for Developers page](https://developers.facebook.com/apps), and follow these steps: 1. Click the Create App button. 2. Select Consumer for app type, and click Next. 3. Enter your app's display name and contact email. 4. Click the Create app button. 5. On the Add products to your app page, under Facebook Login, click Set up. 6. In the left navigation panel, click Settings > Basic. 7. Take note of the App ID and App secret values. #### Generating a hash of your signing key The default keystore password for Android Studio is `android`. 1. To generate a key hash value, in a terminal window, enter the following command: ``` keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64 ``` 2. Note the key hash value for later use. #### Configuring Facebook for an Android app 1. On the [developer apps page](https://developers.facebook.com/apps), double-click an Android app. 2. In the left navigation panel, select Settings > Basic. 3. At the bottom of the page, click Add platform, select Android, and click Next. 4. In the Select Android Store dialog, select a store. For example, Google Play. 5. Click Next. 6. Scroll down to the Android section. 7. In the Key hashes field, enter the key hash value you generated earlier. 8. In the Package Names field, enter your app's Google Play Package Name. The name is often a reverse domain name, such as `com.example.app`. 9. In the Class Name field, enter your app's class name. 10. Click Save changes. #### Configuring Facebook for an iOS app 1. On the [developer apps page](https://developers.facebook.com/apps), select iOS. 2. Click Next. 3. Enter your Bundle ID. The name is often a reverse domain name, such as `com.example.app`. 4. Click Save changes. 5. In the left navigation panel, under Facebook Login, select Quickstart. 6. Click iOS. 7. Read the information, and select your package manager. 8. Click Next. 9. Enter your Bundle ID. 10. Click Save. 11. Click Continue. 12. Select your single sign-on settings. 13. When you get to Configure Your info.plist, configure your `info.plist` file with the XML snippet that contains data for your app. ### Configuring Google as an external identity provider To use Google as an IdP, visit [Google's API Dashboard](https://console.cloud.google.com/apis/dashboard), and follow these steps: 1. In the left navigation, click Credentials. 2. Click CREATE CREDENTIALS > OAuth client ID. * For an Android app 1. Select `Android` as the value for Application Type. 2. In the Name field, type a name for this application. 3. Enter the package name from the `AndroidManifest.xml` file. 4. Enter the SHA-1 certificate fingerprint. Use the following command to get the fingerprint: ``` keytool -keystore path-to-debug-or-production-keystore -list -v ``` 5. Click Create. * For an iOS app 1. Select `iOS` as the value for Application Type. 2. In the Name field, type a name for this application. 3. Enter the bundle id as listed in the app's `Info.plist` file. 4. If the app is listed in the Apple App Store, enter the Apple ID of the app. 5. Enter the Team ID that Apple assigned to your team. 6. Click Create. * []()For a JavaScript app 1. Select `Web application` as the value for Application Type. 2. In the Name field, type a name for this application. 3. Under Authorized JavaScript Origins, add the origins of the apps that use Google as an IdP. Origins include scheme, domain, and port. 4. Under Authorized redirect URIs, add the full redirect URLs of your apps that handle the redirection from Google after user login. 5. Click Create. #### Enabling native Android social authentication To enable native Android social authentication, you must create two OAuth 2.0 clients in the Google API console: 1. Create an OAuth 2.0 client for the Android application itself. See [the step for an Android app](#sl1-create-android-app) above. 2. Create a separate OAuth 2.0 client to allow Advanced Identity Cloud or PingAM to communicate with the Google APIs. See [the step for a JavaScript app](#sl-create-javascript-app) above. ## Configure Advanced Identity Cloud or PingAM ### Enable identity providers If you are using **Advanced Identity Cloud**: 1. Log in to the PingOne Advanced Identity Cloud tenant as an administrator. 2. Click Native Consoles. 3. Click Access Management. If you are using **PingAM**: 1. Log in to the Access Management administrative console. For both servers: 1. Click Services. 2. Click Social Identity Providers Service, or create it by clicking Add a Service. Once in the service, ensure it is enabled. 3. To manage your IdPs, click the Secondary Configurations tab. Setting up your configuration for providers is mostly the same, but there are a few differences with Apple that are described below. You will likely need a configuration for each platform that you develop. Use a naming scheme that's easy to remember, such as `google_web`, `google_ios`, `google_android`. #### Configure Google and Facebook 1. Under Secondary Configuration, click Add a Secondary Configuration, and choose the provider to configure. The following fields are required: * Client ID This is the ID for the client registered with the IdP. For native Android, set up the client with the second OAuth set of credentials generated using the web configuration. * Client Secret This is the secret for the client registered with the IdP. * Facebook Facebook provides a client secret. * Android You must set up the secret with the second OAuth set of credentials generated using the Web configuration. * iOS The Google Credentials do not provide a client secret. * Redirect URL The redirect URL/URI for your application after the user authenticates with the provider. * Scope Delimiter `" "` (a literal space character) 2. For native iOS and Android apps, set Enable Native Nonce to `OFF`. The option is `ON` by default. 3. Click Create. 4. Ensure that the configuration is enabled, and the `Transform Script` is set to `Google Profile Normalization`, or `Facebook Profile Normalization`. #### Configure Apple 1. Under Secondary Configuration, click Add a Secondary Configuration, and choose the Apple Provider Configuration. The following fields are required: * Client ID For native iOS, use the app ID created in the Apple developer page. For Android or Web, use the service ID. * Client Secret The JWT client secret you generated. * Redirect URL * Native iOS Use the `` of your app. The `` can vary as it does not impact the flow. * Android or Web For **PingAM**, use `/am/oauth2/client/form_post/`. For example, the configuration name here is `apple_web`. You can also add the redirect URI from the OAuth2.0 client settings. For **Advanced Identity Cloud**, use `/am/oauth2//client/form_post/`. * (Optional) Redirect after form post URL This is only needed for configurations that use an PingOne Advanced Identity Cloud or PingAM endpoint for handling the POST redirection from Apple. The value of this field is the URL/URI of the Android or web app handling the remainder of the login flow. * Scope Delimiter `" "` (a literal space character) * OAuth Scopes Include the value `email` in this field to include the user's Apple ID email in the JWT response and the identity token. If you add the email scope after a user agrees to provide scopes, the JWT response and the identity token will not include the user's Apple ID email. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To troubleshoot when the JWT response does not include the user's Apple ID email.1) Sign in with your Apple ID used for authentication at the [Apple ID page](https://appleid.apple.com). 2) Under Security > Sign in with Apple, click Manage apps & websites > Apps & websites using Apple ID. 3) Select the application you are developing using Sign in with Apple. 4) Click Stop using Apple ID. 5) Attempt to re-authenticate in your app.For more information, read [Sign in with Apple - Updated Scope Not Reflected in JWT Claims](https://developer.apple.com/forums/thread/678930). | * Well Known Endpoint `https://appleid.apple.com/.well-known/openid-configuration` * Issuer `https://appleid.apple.com` 2. Click Create to save your configuration. 3. Add these values to complete the configuration: * Response Mode * Native iOS Use `Default`. * Android or Web Use `FORM_POST`. * Transform Script Ensure `Apple Profile Normalization` is selected. ### Create your authentication journey After configuring the provider services, the next step is to build your authentication journey. There are nearly unlimited number of ways to compose authentication journeys. This page covers the basics. We have two different *sets* of authentication nodes that provide social login capabilities. This page focuses on the node sets supported by the Orchestration SDKs: * The Select Identity Provider node The Select Identity Provider node has the following important settings. * Include local authentication When enabled, this includes an additional "provider" in the `SelectIdPCallback` called `localAuthentication`. This also enables a different outcome of the node that you can connect to a local authentication path. The node will now have two outcomes: `Social Authentication`, and `Local Authentication`. * Filter enabled providers This setting further reduces the number of providers passed to your application. This is often used when you have providers configured for different platforms, and you only want the platform specific providers sent to the application. For more information, see the [Select Identity Provider node](https://docs.pingidentity.com/auth-node-ref/latest/select-identity-provider.html) reference. * Social Provider Handler node The Social Provider Handler node has the following important settings: * Transformation Script Set `Normalized Profile to Managed User`. * Client Type If the browser is used for IdP authentication (always the case for JavaScript), `BROWSER` is the correct value. If you are using the IdP's SDK with native mobile for authentication, then `NATIVE` is the correct choice. For more information, see the [Social Provider Handler node](https://docs.pingidentity.com/auth-node-ref/latest/social-provider-handler.html) reference. ### Create users for a specific realm To create users from a specific realm, link the Create node and the Patch node to the IDM users and their realm. For example, for users in the alpha realm, set the Create node and the Patch node as follows: * Create Object node Set Identity Resource to `managed/alpha_user`. * Patch Object node Set Identity Resource to `managed/alpha_user`. For more information, see the [Create Object node](https://docs.pingidentity.com/auth-node-ref/latest/create-object.html), and [Patch Object node](https://docs.pingidentity.com/auth-node-ref/latest/patch-object.html) references. ### A simple social authentication journey Start with the simplest journey. A user is presented with a choice of providers, the choice is made, and the user is taken to the IdP to authenticate. Upon the user's return, the user management capabilities read the identity information from the provider to verify, allow, or deny access to the system. ![social login journey](../../../_images/social-login-journey.png)Figure 1. Social login journey To add a choice of local authentication, enable the feature in the Select Identity Provider node, mentioned above, to create an alternative path for local credentials. ![social login journey with local authn](../../../_images/social-login-journey-with-local-authn.png)Figure 2. Social login journey with local credentials ### Social authentication and local username-password journey This is one of the more common authentication journeys seen across the web. This is a choice between using a third-party identity provider, or using first-party credentials with username and password directly. The UI for this combination looks like this: ![Social login choice](../../../_images/platform-social-login.png) To compose this type of journey, use a Page node to combine the following nodes: * Password Collector/Platform Password * Select Identity Provider (enable `Include local authentication`) ![Social login journey with choice](../../../_images/social-login-journey-combo.png) ## Next Steps In this section you completed the following tasks: * Added client credentials in your IdPs so that your app and server can connect * Configured your server with the details of the client credentials you created in the IdPs You can now proceed to configuring your client apps to step through the auth journeys and perform social sign-on: [icon: android, set=fab, size=3x] #### [Android](android/index.html) Configure an Android app for social sign-on [icon: apple, set=fab, size=3x] #### [iOS](ios/index.html) Configure an iOS app for social sign-on [icon: js, set=fab, size=3x] #### [JavaScript](javascript/index.html) Configure a JavaScript app for social sign-on