Custom Social Identity Provider

As suggested in the introduction to this chapter, you'll need to take four basic steps to configure a custom social identity provider:

Note

These instructions require the social identity provider to be fully compliant with The OAuth 2.0 Authorization Framework or the OpenID Connect standards.

Prepare IDM

While IDM includes provisions to work with OpenID Connect 1.0 and OAuth 2.0 social identity providers, connections to those providers are not supported, other than those specifically listed in this chapter. If you haven't already, copy /path/to/openidm/samples/example-configurations/self-service/identityProviders.json to your project's conf/ directory.

To set up another social provider, first add a code block to conf/identityProviders.json:

{
    "provider" : "<providerName>",
    "authorizationEndpoint" : "",
    "tokenEndpoint" : "",
    "userInfoEndpoint" : "",
    "wellKnownEndpoint" : "",
    "clientId" : "",
    "clientSecret" : "",
    "uiConfig" : {
         "iconBackground" : "",
         "iconClass" : "",
         "iconFontColor" : "",
         "buttonImage" : "",
         "buttonClass" : "",
         "buttonCustomStyle" : "",
         "buttonCustomStyleHover" : "",
         "buttonDisplayName" : ""
    },
    "scope" : [ ],
    "authenticationIdKey" : "",
    "schema" : {
       "id" : "urn:jsonschema:org:forgerock:openidm:identityProviders:api:<providerName>",
       "viewable" : true,
       "type" : "object",
       "$schema" : "http://json-schema.org/draft-03/schema",
       "properties" : {
          "id" : {
             "title" : "ID",
             "viewable" : true,
             "type" : "string",
             "searchable" : true
          },
          "name" : {
             "title" : "Name",
             "viewable" : true,
             "type" : "string",
             "searchable" : true
          },
          "first_name" : {
             "title" : "First Name",
             "viewable" : true,
             "type" : "string",
             "searchable" : true
          },
          "last_name" : {
             "title" : "Last Name",
             "viewable" : true,
             "type" : "string",
             "searchable" : true
          },
          "email" : {
             "title" : "Email Address",
             "viewable" : true,
             "type" : "string",
             "searchable" : true
          },
          "locale" : {
             "title" : "Locale Code",
             "viewable" : true,
             "type" : "string",
             "searchable" : true
          }
       },
       "order" : [
          "id",
          "name",
          "first_name",
          "last_name",
          "email",
          "locale"
       ],
       "required" : [ ]
    },
    "propertyMap" : [
       {
          "source" : "id",
          "target" : "id"
       },
       {
          "source" : "name",
          "target" : "displayName"
       },
       {
          "source" : "first_name",
          "target" : "givenName"
       },
       {
          "source" : "last_name",
          "target" : "familyName"
       },
       {
          "source" : "email",
          "target" : "email"
       },
       {
          "source" : "email",
          "target" : "username"
       },
       {
          "source" : "locale",
          "target" : "locale"
       }
    ],
    "redirectUri" : "http://openidm.example.com:8080/",
    "configClass" : "org.forgerock.oauth.clients.oidc.OpenIDConnectClientConfiguration",
    "basicAuth" : false,
    "enabled" : true
},

Modify this code block for your selected social provider. Some of these properties may appear under other names. For example, some providers specify an App ID that you'd include as a clientId.

Additional changes may be required, especially depending on how the provider implements the OAuth2 or OpenID Connect standards.

In the propertyMap code block, you should substitute the properties from the selected social identity provider for various values of source. Make sure to trace the property mapping through selfservice.propertymap.json to the Managed User property shown in managed.json. For more information on this multi-step mapping, see "Many Social Identity Providers, One Schema".

As shown in "OpenID Connect Authorization Code Flow", user provisioning information goes through the User Info Endpoint. Some providers, such as LinkedIn and Facebook, may require a list of properties with the endpoint. Consult the documentation for your provider for details.

For more information on the uiConfig code block, see "Social Identity Provider Button and Badge Properties".

Both files, identityProviders.json and identityProvider-custom.json, should include the same information for the new custom identity provider. For property details, see "Custom Social Identity Provider Configuration Details".

Once you've included information from your selected social identity provider, proceed with the configuration process. You'll use the same basic steps described for other specified social providers.

Set Up a Custom Social Identity Provider

Every social identity provider should be able to provide the information you need to specify properties in the code block shown in "Prepare IDM".

In general, you'll need an authorizationEndpoint, a tokenEndpoint and a userInfoEndpoint. To link to the custom provider, you'll also have to copy the clientId and clientSecret that you created with that provider. In some cases, you'll get this information in a slightly different format, such as an App ID and App Secret.

For the propertyMap, check the source properties. You may need to revise these properties to match those available from your custom provider.

For examples, refer to the specific social identity providers documented in this chapter.

Configure a Custom Social Identity Provider

  1. To configure a custom social identity provider, log in to the Admin UI and navigate to Configure > Social ID Providers.

  2. Enable the custom social identity provider. The name you see is based on the name property in the relevant code block in the identityProviders.json file.

  3. If you haven't already done so, include the values provided by your social identity provider for the properties shown. For more information, see the following appendix: "Custom Social Identity Provider Configuration Details".

Configure User Registration to Link to a Custom Provider

Once you've configured a custom social identity provider, you can activate it through User Registration. To do so in the Admin UI, select Configure > User Registration, and under the Social tab, enable the option associated with Social Registration. For more information about user self-service features, see Admin UI.

When you enable social identity providers, you're allowing users to register on IDM through all active social identity providers.

Custom Social Identity Provider Configuration Details

When you set up a custom social identity provider, starting with "Prepare IDM", you'll see configuration details in your conf/identityProviders.json file. The following table includes the information shown in the relevant Admin UI pop-up window.

IDM generates the content of identityProvider-custom.json after you configure and enable the custom social identity provider using the Admin UI. Before you can activate this feature in the Admin UI, copy /path/to/openidm/samples/example-configurations/self-service/identityProviders.json to your project's conf/ directory. You can also manually create this file.

Custom Social Identity Provider Configuration Properties
Property (UI)Property (JSON file)Description
Client IDclientIdThe client identifier for your social identity provider
Client SecretclientSecretUsed with the Client ID
ScopescopeAn array of strings that allows access to user data; varies by provider.
Authorization EndpointauthorizationEndpointEvery social identity provider should have an authorization endpoint to authenticate end users.
Token EndpointtokenEndpointEndpoint that receives a one-time authorization code, and returns an access token.
User Info EndpointuserInfoEndpointEndpoint that transmits scope-related fields.
Not in the Admin UInameName of the social identity provider
Not in the Admin UItypeAuthentication module
Not in the Admin UIauthenticationIdAuthentication identifier, as returned from the User Info Endpoint for each social identity provider
Not in the Admin UIpropertyMapMapping between the social identity provider and IDM

For information on social identity provider buttons and badges, see "Social Identity Provider Button and Badge Properties".

Read a different version of :