Rate this page

External Identity

Users in the Ping Identity Data Governance Broker’s user store may be associated with external identity providers such as Facebook or Google. Any external identity provider linked to a local user account may be used to log in the user. The externalIdentities sub-resource can be used to manage these external identity provider links.

The following table describes the fields of a single external identity resource.

Field Type Provided? Description
schemas array always The SCIM schema of the external identity resource. Always has the value urn:pingidentity:scim:api:messages:2.0:ExternalIdentity.
meta complex always Will always contain a resourceType sub-attribute with the value External Identity. Will always contain a location attribute with the external identity resource’s canonical URI.
id string always The external identity provider ID.
provider complex An object representing the external identity provider. Its fields are described in the following table.
providerUserId string The user ID at the external identity provider. Only present if the user is in fact linked to the external identity provider.
accessToken string The access token issued by the external identity provider. This may be used to retrieve additional data from the external identity provider. Only present if the user is in fact linked to the external identity provider.
refreshToken string The refresh token issued by the external identity provider. This may be used to request a new access token from the external identity provider. Only present if the user is in fact linked to the external identity provider. Currently only supported if the external identity provider is Google.

The value of the provider field is an object with the following fields:

Field Type Provided? Description
name string The name of the external identity provider.
description string A description of the external identity provider.
iconUrl string A URL of an icon for the external identity provider.
type string The type of external identity provider. May be facebook, google, oidc, or saml.
samlResponseBinding string The SAML response binding, if this is a SAML identity provider. May be artifact or post.

Retrieve a user’s external identity data

GET /scim/v2/Users/{id}/externalIdentities

GET /scim/v2/Me/externalIdentities

This retrieves a user’s external identity resources.

The response is formatted as a list response containing zero or more matching external identity resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request:

GET /scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 1108
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 18:25:47 GMT

{
    "Resources": [
        {
            "accessToken": "EAAMi0rzvU8sBAPZCkf...", 
            "id": "Facebook", 
            "meta": {
                "lastModified": "2016-07-30T18:13:34.766Z", 
                "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Facebook", 
                "resourceType": "External Identity"
            }, 
            "provider": {
                "description": "Facebook identity provider", 
                "name": "Facebook", 
                "type": "facebook"
            }, 
            "providerUserId": "1293710416799190", 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
            ]
        }, 
        {
            "id": "Google", 
            "meta": {
                "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Google", 
                "resourceType": "External Identity"
            }, 
            "provider": {
                "description": "Google identity provider", 
                "name": "Google", 
                "type": "google"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
            ]
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 2
}

Search for a user’s external identities (GET)

GET /scim/v2/Users/{id}/externalIdentities?filter={filter}

GET /scim/v2/Me/externalIdentities?filter={filter}

A client may filter for a single user’s matching external identity resources by performing a GET and providing a filter query parameter. Pagination parameters may also be provided. The filter format is described in the Searching section.

The response is formatted as a list response containing zero or more matching external identity resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request using the filter provider[type eq "facebook"]:

GET /scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities?filter=provider[type%20eq%20%22facebook%22] HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 127
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 740
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 18:16:23 GMT

{
    "Resources": [
        {
            "accessToken": "EAAMi0rzvU8sBAPZCkf...", 
            "id": "Facebook", 
            "meta": {
                "lastModified": "2016-07-30T18:13:34.766Z", 
                "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Facebook", 
                "resourceType": "External Identity"
            }, 
            "provider": {
                "description": "Facebook identity provider", 
                "name": "Facebook", 
                "type": "facebook"
            }, 
            "providerUserId": "1293710416799190", 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
            ]
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 1
}

Search for a user’s external identities (POST)

POST /scim/v2/Users/{id}/externalIdentities/.search

POST /scim/v2/Me/externalIdentities/.search

A client may filter for a single user’s matching external identity resources by performing a POST against the special .search endpoint and providing a filter value. Pagination directives may also be provided. The filter format is described in the Searching section.

The response is formatted as a list response containing zero or more matching external identity resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request using the filter provider[type eq "facebook"]:

POST /scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/.search HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

{
    "filter": "provider[type eq \"facebook\"]"
}

Example response:

HTTP/1.1 200 OK
Content-Length: 740
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 18:16:23 GMT

{
    "Resources": [
        {
            "accessToken": "EAAMi0rzvU8sBAPZCkf...",
            "id": "Facebook",
            "meta": {
                "lastModified": "2016-07-30T18:13:34.766Z",
                "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Facebook",
                "resourceType": "External Identity"
            },
            "provider": {
                "description": "Facebook identity provider",
                "name": "Facebook",
                "type": "facebook"
            },
            "providerUserId": "1293710416799190",
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
            ]
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1
}

Retrieve a user’s external identity data for a specific identity provider

GET /scim/v2/Users/{id}/externalIdentities/{providerId}

GET /scim/v2/Me/externalIdentities/{providerId}

A client may request a specific external identity resource by providing the resource’s ID. If the response does not include the providerUserId and accessToken fields, then the client may assume that the user does not have a linked account for this external identity provider.

Example request:

GET /scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Facebook HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 642
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 18:26:25 GMT

{
    "accessToken": "EAAMi0rzvU8sBAPZCkf...", 
    "id": "Facebook", 
    "meta": {
        "lastModified": "2016-07-30T18:13:34.766Z", 
        "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Facebook", 
        "resourceType": "External Identity"
    }, 
    "provider": {
        "description": "Facebook identity provider", 
        "name": "Facebook", 
        "type": "facebook"
    }, 
    "providerUserId": "1293710416799190", 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
    ]
}

A web application may link a local user account to an external identity provider using an interactive multi-step flow in which the user’s browser is redirected to the external identity provider so that the user can grant access to the user’s account details.

POST /scim/v2/Users/{id}/externalIdentities

POST /scim/v2/Me/externalIdentities

The client initiates the process of linking by submitting a POST request to the base external identity provider endpoint. The request should contain the callbackUrl and provider.name fields.

The following table describes the fields of an external identity link initiation request.

Field Type Required? Description
schemas array no The SCIM schema of the external identity link request. Always has the value urn:pingidentity:scim:api:messages:2.0:ExternalIdentity.
callbackUrl string yes The redirect URI that the external identity provider will be used when returning an authorization code response to the client. Most identity providers require that clients register the redirect URI before using.
provider complex An object representing the external identity provider. It should contain a name field with the external identity provider name.

The Data Governance Broker’s response will include a special temporary resource representing a stateful account linking request, with the request state encoded in the resource ID. The response will also include a providerRedirectUrl field containing a request to obtain an OAuth 2 authorization code from the external identity provider.

The following table describes the fields of an external identity link initiation response.

Field Type Provided? Description
schemas array always The SCIM schema of the external identity link response. Always has the value urn:pingidentity:scim:api:messages:2.0:ExternalIdentity.
meta complex always Will always contain a resourceType sub-attribute with the value External Identity. Will always contain a location attribute with the external identity resource’s canonical URI.
id string always The external identity provider ID.
provider complex An object representing the external identity provider. Its fields are described earlier in this document.
providerRedirectUrl string An authentication URI at the external identity provider to which the client should redirect the user’s user-agent. This field is only present after initiating a link.

Example request:

POST /scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 190
Content-Type: application/scim+json
Host: example.com:443

{
    "callbackUrl": "https://example.com:443/client/", 
    "provider": {
        "name": "Facebook"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
    ]
}

Example response:

HTTP/1.1 201 Created
Content-Length: 1054
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 17:58:51 GMT
Location: https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/AbdZOKMpPqWPASOPtywI3fzj2eEhAAAAAAAAAAAniZyLCyd9RjLytRuBXnsJ7ufVY_W6-F61ykMu81Agtoch93EL1Bv2Xr3yLAtypwNDlfEmMc6d0aTzYefQZPPljifvCWBLqK5tmHimFNbAj8FPAhJ4jnM-KOkTgvf9Djo6IwatLpqDz8koIOSHBfKqReBVScKo9SMIJxWmvHBUxA9TQrE5Fk5XCytKLB69qXI

{
    "id": "AbdZOKMpPqWPASOPtywI3fzj2eEhAAAAAAAAAAAniZyLCyd9RjLytRuBXnsJ7ufVY_W6-F61ykMu81Agtoch93EL1Bv2Xr3yLAtypwNDlfEmMc6d0aTzYefQZPPljifvCWBLqK5tmHimFNbAj8FPAhJ4jnM-KOkTgvf9Djo6IwatLpqDz8koIOSHBfKqReBVScKo9SMIJxWmvHBUxA9TQrE5Fk5XCytKLB69qXI", 
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/AbdZOKMpPqWPASOPtywI3fzj2eEhAAAAAAAAAAAniZyLCyd9RjLytRuBXnsJ7ufVY_W6-F61ykMu81Agtoch93EL1Bv2Xr3yLAtypwNDlfEmMc6d0aTzYefQZPPljifvCWBLqK5tmHimFNbAj8FPAhJ4jnM-KOkTgvf9Djo6IwatLpqDz8koIOSHBfKqReBVScKo9SMIJxWmvHBUxA9TQrE5Fk5XCytKLB69qXI", 
        "resourceType": "External Identity"
    }, 
    "provider": {
        "description": "Facebook identity provider", 
        "name": "Facebook", 
        "type": "facebook"
    }, 
    "providerRedirectUrl": "https://www.facebook.com/v2.5/dialog/oauth?response_type=code&client_id=767210638086119&redirect_uri=https://example.com:443/callback/&scope=email+public_profile&state=8b50ebc5-fd69-43e3-b56a-7a23dc5837db", 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
    ]
}

Request authorization code

The client must now temporarily store the URI from the response’s Location header or meta.location attribute. This will be used in the next step.

The providerRedirectUrl field contains an OAuth 2 authorization request URI, generated using data from the Data Governance Broker’s configuration. The client should redirect the user’s browser to this URI. The external identity provider will then authenticate the user and authorize the Data Governance Broker for access to the user’s external identity, returning an OAuth 2 authorization code to the client’s callback URI.

PUT /scim/v2/Users/{id}/externalIdentities/{temporaryId}

PUT /scim/v2/Me/externalIdentities/{temporaryId}

The client should parse the query parameters from the callback URI, expecting to find state and code parameters. The client should then construct another PUT request to the resource URI obtained earlier. The request must include a callbackParameters field; the value of this field is an object with keys and values corresponding to the query parameters appended to the callback URI.

Upon submission of the PUT request, the Data Governance Broker will verify that the state value matches the value that it originally set in the providerRedirectUrl and then use the authorization code to request an access token from the external identity provider. With the access token, the Data Governance Broker will fetch the user’s profile from the external identity provider, updating the user’s local attributes according to the Data Governance Broker configuration. If this process succeeds, the Data Governance Broker will return a success response to the client. The external identity provider may subsequently be used by the user to authenticate to the Data Governance Broker.

The following table describes the fields of an external identity link completion request.

Field Type Required? Description
schemas array no The SCIM schema of the external identity link request. Always has the value urn:pingidentity:scim:api:messages:2.0:ExternalIdentity.
id string yes The temporary resource ID obtained via the previous POST response.
provider complex no An object representing the external identity provider. Its fields are described earlier in this document.
callbackParameters complex yes An object set by the client when completing a linking flow, consisting of any query parameters received from an external identity provider at the client’s callback URL. If the external identity provider is Google, Facebook, or an OpenID Connect provider, this set of parameters should include the state and code parameters. For a SAML external identity provider, this set of parameters should include the SAMLArt and RelayState parameters.

The following table describes the fields of an external identity link completion response.

Field Type Provided? Description
schemas array always The SCIM schema of the external identity resource. Always has the value urn:pingidentity:scim:api:messages:2.0:ExternalIdentity.
meta complex always Will always contain a resourceType sub-attribute with the value External Identity. Will always contain a location attribute with the external identity resource’s canonical URI.
id string always The external identity provider ID.
provider complex An object representing the external identity provider. Its fields are described earlier in this document.
providerUserId string The user ID at the external identity provider.
accessToken string The access token issued by the external identity provider. This may be used to retrieve additional data from the external identity provider.

Example request:

PUT /scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/AbdZOKMpPqWPASOPtywI3fzj2eEhAAAAAAAAAAAniZyLCyd9RjLytRuBXnsJ7ufVY_W6-F61ykMu81Agtoch93EL1Bv2Xr3yLAtypwNDlfEmMc6d0aTzYefQZPPljifvCWBLqK5tmHimFNbAj8FPAhJ4jnM-KOkTgvf9Djo6IwatLpqDz8koIOSHBfKqReBVScKo9SMIJxWmvHBUxA9TQrE5Fk5XCytKLB69qXI HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 1393
Content-Type: application/scim+json
Host: example.com:443

{
    "callbackParameters": {
        "code": "AQDt6RGV1MML2V_jAkeJxDfcOnyvsKgJw5bYkkKgyzrMnJlugGwecDFaYdepsh-QIb1q_1AZtY8NdCOO2WKUk_Ukf9K2Pi33vq4zl8hPz3hdf8sbFtmjSeO-jJIoRHPIfKUkMq4ixbxLhw4F7vUPWtBmGB_kzFv85QRMMmv0xD4IOAvG__Cr0gaXWXyuPaN3LCbHc0rAQmpsIbabORjhzTq_MQ0nXGMO9fa6mK12iGX5msBpqS1rXNUhqF6BPXjPDDRG3_DXBEhugTCv35A0v2g3s94Np7CB2n0g7VWISeH2cpL5jBZ4h-p7Kt3MEGbmSohyYDCbxpevr35W9syn1dKx1cnyTcvtTYtRE63bXeCNIA", 
        "state": "8b50ebc5-fd69-43e3-b56a-7a23dc5837db"
    }, 
    "id": "AbdZOKMpPqWPASOPtywI3fzj2eEhAAAAAAAAAAAniZyLCyd9RjLytRuBXnsJ7ufVY_W6-F61ykMu81Agtoch93EL1Bv2Xr3yLAtypwNDlfEmMc6d0aTzYefQZPPljifvCWBLqK5tmHimFNbAj8FPAhJ4jnM-KOkTgvf9Djo6IwatLpqDz8koIOSHBfKqReBVScKo9SMIJxWmvHBUxA9TQrE5Fk5XCytKLB69qXI", 
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/AbdZOKMpPqWPASOPtywI3fzj2eEhAAAAAAAAAAAniZyLCyd9RjLytRuBXnsJ7ufVY_W6-F61ykMu81Agtoch93EL1Bv2Xr3yLAtypwNDlfEmMc6d0aTzYefQZPPljifvCWBLqK5tmHimFNbAj8FPAhJ4jnM-KOkTgvf9Djo6IwatLpqDz8koIOSHBfKqReBVScKo9SMIJxWmvHBUxA9TQrE5Fk5XCytKLB69qXI", 
        "resourceType": "External Identity"
    }, 
    "provider": {
        "description": "Facebook identity provider", 
        "name": "Facebook", 
        "type": "facebook"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Length: 642
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 18:13:34 GMT

{
    "accessToken": "EAAMi0rzvU8sBAPZCkf...", 
    "id": "Facebook", 
    "meta": {
        "lastModified": "2016-07-30T18:13:34.766Z", 
        "location": "https://example.com:443/scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Facebook", 
        "resourceType": "External Identity"
    }, 
    "provider": {
        "description": "Facebook identity provider", 
        "name": "Facebook", 
        "type": "facebook"
    }, 
    "providerUserId": "1293710416799190", 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:ExternalIdentity"
    ]
}

DELETE /scim/v2/Users/{id}/externalIdentities/{providerId}

DELETE /scim/v2/Me/externalIdentities/{providerId}

A client may unlink an external identity from a user by using the DELETE method and providing a specific external identity provider ID. Once an external identity is unlinked, the external identity provider may no longer be used to authenticate the user.

Example request:

DELETE /scim/v2/Users/030fe5fd-b261-408e-8cd5-fe95b574b4d6/externalIdentities/Facebook HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Connection: keep-alive
Content-Length: 0
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 204 No Content
Date: Sat, 30 Jul 2016 18:33:09 GMT