Rate this page

Linked External Identity Authenticator

Schema URN
urn:pingidentity:scim:api:messages:2.0:ExternalIdentityAuthenticationRequest

The Linked External Identity authenticator allows an end user to authenticate using an account managed by an external identity provider such as Facebook or Google. The user’s external identity will be linked to a local account, and the user may be prompted to provide additional required attributes, if necessary. This authenticator should be used with the Login flow.

Field Type Description
status string Indicates the authenticator state. Values are unavailable, ready, failure, or success.
providers array Any array of provider objects, described in the table below.
callbackUrl string The auth UI’s callback URI. The external IDP will redirect the user’s browser to this URI after the user has authenticated.
provider string The name of the external IDP at which the end user will authenticate.
providerRedirectUrl string A URI at the external IDP that the auth UI should redirect the end user’s browser to. This will initiate the login process at the external IDP.
callbackParameters complex An object consisting of query parameters received from an external IDP’s OAuth 2 redirect response. The auth UI is responsible for setting this field.
externalResourceAttributes complex An object consisting of attributes retrieved from the external IDP. The field names will match local account attribute names.
externalIdentityToken string A state token managed by the Auth API. The auth UI should not modify this value.
error string An error code set by the server after an authentication attempt is made.
errorDetail string A human-readable error description.

A provider object:

Field Type Description
name string The display name of the external identity provider.
description string A human-readable description of the external identity provider.
type string The type of external identity provider. Value may be one of facebook, google, or oidc (OpenID Connect).

Setup

Before the Linked External Identity authenticator can be used, the Data Governance Broker must be registered as an app with the external identity provider. This includes:

  • Obtaining a client ID and client secret from the external identity provider. These client credentials will need to be stored in the Broker’s configuration.
  • Determining the scopes or permissions to be requested from the external identity provider.
  • Registering a callback URI with the external identity provider. This is an auth UI endpoint that will receive OAuth 2 redirect responses from the external identity provider.

Only the last of these, the callback URI, is of concern to the auth UI.

Facebook

For more information about configuring external identity login for Facebook, see the Facebook Login documentation. Client credentials can be obtained using the Facebook Developers site.

Google

For more information about configuring external identity login for Google, see the Google Sign-In for server-side apps documentation. Client credentials can be obtained using the Google API Console.

Authentication

Submit callback URI

The auth UI begins by submitting its callback URI to the Auth API, along with the name of the external identity provider to be used.

{
  "urn:pingidentity:scim:api:messages:2.0:ExternalIdentityAuthenticationRequest": {
    "provider": "Facebook",
    "callbackUrl": "https://example.com/auth-ui/callback.html"
  }
}

Redirect to external IDP

The Broker responds with a providerRedirectUrl, which is an OAuth 2 request to the external IDP. The auth UI should redirect the end user’s browser to this URI. Before doing so, though, the auth UI should store the current flow URI so that the user’s authentication session can be restored later. For client-side auth UIs, the SessionStorage object can be used.

Once the auth UI redirects to the providerRedirectUrl, control will pass to the external IDP, and the end user will be prompted to log in.

{
  "urn:pingidentity:scim:api:messages:2.0:ExternalIdentityAuthenticationRequest": {
    "provider": "Facebook",
    "providers": [{
      "name": "Facebook",
      "description": "Log in with your Facebook account",
      "type": "facebook"
    }],
    "providerRedirectUrl": "https://www.facebook.com/v2.5/dialog/oauth?response_type=code&client_id=0547572417&redirect_uri=https://example.com/auth-ui/callback.html&scope=email+public_profile&state=76bffba2-f074-45c5-8ad2-9ee0139b41b0",
    "status": "failure"
  }
}

Be aware that the authenticator’s status field here will be set to failure. This is an indication that this authenticator’s authentication state is in progress.

Submit external IDP response

When the end user has completed login at the external IDP, it will redirect the browser back to the auth UI’s callback URI.

The auth UI should load the previously saved flow URI, then submit all query parameters received through the callback URI to the Auth API as fields of the callbackParameters object. Typically, these will be an authorization code (code) and a state value (state).

{
  "urn:pingidentity:scim:api:messages:2.0:ExternalIdentityAuthenticationRequest": {
    "provider": "Facebook",
    "callbackParameters": {
      "code": "AQCUdqzm4gMnO54q8w6xxKgQ-w6Z0G7OiUdRks_SwsYfjFl4gBfAIqfbWmhyF6Hy0Lv_FNhpN3sH8TTT1lJ-4ZlAX7LHRX0wCWXlN392UU0uuJ3vaqKhTnUk11orWuKJY13bWYqyOvZTaetqbsP0turctEUxf3R0UJd7b_xtkWnMUCMaezgBhHzlOpza0c6e-0vKTAeynEBsRtrTFrSMPId53IUBJwtJUzc63Ak75XGdVSl_tfoCGM3rULKaH9yKz0V9FZLv-eOQ14r94o5MOpMW2y61K4RmPSAoDU1sfKeGqavUZN4VJDngUMNyMQcqPV2gvItlkP5-gvpznvHn-JjvOzTm_MlzeaPPgQYi5W35xg",
      "state": "76bffba2-f074-45c5-8ad2-9ee0139b41b0"
    }
  }
}

The Broker will use the authorization code obtained from the auth UI to request an access token from the external IDP, and it will then retrieve the user’s profile from the external IDP.

If the end user’s external IDP account is already linked to a local account, then the flow will end here. Otherwise, the Auth API will return an error code of noLinkedAccount. In that case, the auth UI will need to use the Registration Authenticator to create a new local account for linking. The auth UI may optionally use the attribute values in externalResourceAttributes to prepopulate its account registration form.

{
  "urn:pingidentity:scim:api:messages:2.0:ExternalIdentityAuthenticationRequest": {
    "provider": "Facebook",
    "providers": [{
      "name": "Facebook",
      "description": "Log in with your Facebook account",
      "type": "facebook"
    }],
    "externalResourceAttributes": {
      "name.familyName": "Philip",
      "name.givenName": "Dick"
    },
    "externalIdentityToken": "ARH5F9BcpEQgvFXa4ou5XScewjvmAAAAAAAAAAAiLXCjZpj9AVGCHMDq4qy5eYqKOsbExIf2eh_6iugMe50XqHOJw7r6vUpKn0V0LMdSdYviPFshioGplddPADhsauDFKeHB4ST7UPNcwhls12tVRIL1167fyKBg63-6ojlJfXbF6Zj8uO9t3atEpodXVprbAV2JPwNWok6U822Qm8AnPAY_P3ZGcpkSrcpSKmrCwxVcbgokjzML81Og3E9HbDdHRc6otYt_4yTAuBw_B4TwGLTicVUx2WLp45kZFGLWKUHKBUKmQzxXcSmibHKlq_hqdfbC6QZopGHkvM9Zk5jWS5eIdluC8A0Ap15NcZArOzmAsvCwGtvJ9qFez3dlQHrlNGL6GjzO_xmeg-ZeM9MJ4vcl6F8ra-isD494demFuFHP0GOuJAG-8iszRXJ5YldKiCx6m39zx59cPuUq4g",
    "status": "failure",
    "error": "noLinkedAccount"
  }
}