Custom social identity provider
| Social authentication is deprecated and will be removed in a future release of IDM. For more information, refer to Deprecation. |
As suggested in the introduction to this chapter, you’ll need to take four basic steps to configure a custom social identity provider:
|
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:
Example Code Block
{
"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, refer to 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, refer to 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, refer to 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
-
To configure a custom social identity provider, log in to the admin UI and navigate to Configure > Social ID Providers.
-
Enable the custom social identity provider. The name you refer to is based on the
nameproperty in the relevant code block in theidentityProviders.jsonfile. -
If you haven’t already done so, include the values provided by your social identity provider for the properties shown. For more information, refer to 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, refer to IDM user interface.
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 refer to 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.
| Property (UI) | Property (JSON file) | Description |
|---|---|---|
Client ID |
|
The client identifier for your social identity provider |
Client Secret |
|
Used with the Client ID |
Scope |
|
An array of strings that allows access to user data; varies by provider. |
Authorization Endpoint |
|
Every social identity provider should have an authorization endpoint to authenticate end users. |
Token Endpoint |
|
Endpoint that receives a one-time authorization code, and returns an access token. |
User Info Endpoint |
|
Endpoint that transmits scope-related fields. |
Not in the admin UI |
|
Name of the social identity provider |
Not in the admin UI |
|
Authentication module |
Not in the admin UI |
|
Authentication identifier, as returned from the User Info Endpoint for each social identity provider |
Not in the admin UI |
|
Mapping between the social identity provider and IDM |
For information on social identity provider buttons and badges, refer to Social identity provider button and badge properties.