Configure a custom social media selection form for Liberty

We can configure our own social media selection form instead of configuring the default social media selection form that Liberty provides. We can choose this option if multiple social media providers are configured to protect a request.

The social media selection form allows users to choose between available social login providers to authenticate themselves for a protected resource request. With Liberty, we can specify the location of our own selection page if we do not want to use the default page that Liberty provides.

Any custom selection page needs to receive HTTP request parameters and use those values to construct a valid web page. We can learn about specific parameters that are sent to the custom selection page, the parameter values, and how the parameter values should be used by the custom selection page.

1. Configure the socialLoginWebapp element. The socialLoginWebapp element is provided by the socialLogin-1.0 feature and is a top-level element in the server configuration. For more information about the socialLoginWebapp element, see socialLoginWebapp - Social Login Web Application .

2. Configure the socialMediaSelectionPageUrl attribute of the socialLoginWebapp element. Set the value of the attribute to the URL of the custom selection page.

   Consider the following guidelines for the attribute to the URL:

   • The value can be a relative or absolute URL.

   • If we choose an absolute URL, the scheme needs to be either http or https.

   • The URL needs to contain only valid URI path characters and cannot contain a query string or fragment, as it is defined by RFC 3986.

3. Create your custom selection page. We can implement the custom selection page as we choose, but the custom selection page needs the request parameter data that is sent to it to ensure that the appropriate options are displayed.

   Accept and use the following request parameters:

   request_url

   The original protected resource request URL, including request parameters if any are present. The custom selection page should submit the social media provider the user selects back to this URL. For example, if the custom selection page uses an HTML form to display the social media options, the action attribute of the form should be set to this URL. Additionally, request parameters should be included as hidden inputs within the form.

   request_method

   The HTTP request method of the original protected resource request. The custom selection page should use the same HTTP request method to submit the social media provider the user selects back to the original request URL.

   submit_param_name

   The name that needs to be used for the parameter or header that specifies the social media provider ID that is selected by the user. When the custom selection page submits the social media provider the user selects back to the original request URL, the configuration ID of the social media provider needs to be specified by a parameter or header with this name.For example, consider the following variables:

   • The URL is https://www.example.com/protected/resource.

   • The social media provider ID the user selects is 123456.

   • The submit_param_name value is social_login_hint.

   The custom selection page must submit the selection as either a parameter, for example, https://www.example.com/protected/resource?social_login_hint=123456, or as a request header. The request header name must be social_login_hint, and the header value must be 123456 when you submit back to the original request URL.

   Any parameters that were included in the original request should also be included by the custom selection page when you submit the user selection back to the original request URL.

   configuration

   A JSON object containing information about each of the social media providers configured to authenticate the original request.

   social-media

   The top-level key that maps to a JSON array of social media configurations. Each social media configuration is a JSON object with the following entries:

   • id: The configuration ID of this social media provider. This is the value that must be submitted if the user chooses this social media provider.
   • display-name: The value that should be displayed to the user to represent this social media provider. This value is typically the public name of the social media provider, such as Google or Facebook, although the value can be modified for any social media provider in the server configuration.
   • website (optional): The website that is associated with this social media provider. A website might not be configured for every social media provider, so this value might be omitted.

   Consider the following configuration snippet:

   <socialLoginWebapp socialMediaSelectionPageUrl="/myApp/customSelection" />
   
   <twitterLogin consumerKey="..." consumerSecret="..." />
   <googleLogin clientId="..." clientSecret="..." />
   <oauth2Login id="customOAuthProvider" clientId="..." clientSecret="..." />
   

   Consider a protected resource request that is directed to https://myhost.com/acme?product_id=123&product_name=anvil and uses the GET HTTP request method. When this request is received, the server determines that multiple providers protect the request and that a custom selection page is configured. The request is redirected to the custom selection page similar to the following example:

   HTTP/1.1 302 Found
   Location: https://myhost.com/myApp/customSelection?
       request_url=https%3A%2F%2Fmyhost.com%2Facme%3Fproduct_id%3D123%26product_name%3Danvil
       &request_method=GET
       &submit_param_name=social_login_hint
       &configuration=%7B%22social-media%22%3A%5B%7B%22id%22%3A%2213579%22%2C%22display-name%22%3A%22Twitter%22%2C%22website%22%3A%22https%3A%2F%2Fwww.twitter.com%22%7D%2C%7B%22id%22%3A%2224680%22%2C%22display-name%22%3A%22Google%22%2C%22website%22%3A%22https%3A%2F%2Fwww.google.com%22%7D%2C%7B%22id%22%3A%22-123456%22%2C%22display-name%22%3A%22An%20OAuth%20Provider%22%7D%5D%7D

   Note: The decoded configuration attribute is displayed in the following example:

   {"social-media":
       [
           {"id":"13579","display-name":"Twitter","website":"https:\/\/www.twitter.com"},
           {"id":"24680","display-name":"Google","website":"https:\/\/www.google.com"},
           {"id":"-123456","display-name":"An OAuth Provider"}
       ]
   }

   If the custom selection page uses an HTML form to display the social media options, the form might be implemented as it is in the following example:

   <form action="https://myhost.com/acme" method="GET">
   <button type="submit" name="social_login_hint" value="13579">Twitter</button>
   <button type="submit" name="social_login_hint" value="24680">Google</button>
   <button type="submit" name="social_login_hint" value="-123456">An OAuth Provider</button>
   <input type="hidden" name="product_id" value="123" />
   <input type="hidden" name="product_name" value="anvil" />
   </form>
   

   Note: In the previous example, the request parameters that were included in the original request are specified as hidden inputs within the form to ensure that they are included when the form is submitted. When you implement the custom selection page, ensure that request parameters from the original request are properly accounted for and included in the request that is submitted back to the original request URL when the user chooses a social media provider.