OpenID Provider Setup

Skip to end of metadata
Go to start of metadata

 

Description

This guide describes how to configure your site as an OP (OpenID Connect Provider). Gigya's OIDC OP requires Gigya RaaS being active for your site.

Gigya supports Auth Code, Implicit, and Hybrid flows using the supported response types id_token, token, and code. For additional information on the differences in response types see the OpenID.net OIDC specification.

 

OP Flow Overview

 

 

Setup Guide

The steps for setting up OP services:

Activate Federation Services

Federation services is a premium feature and must be activated for your account. If your site package does not yet include Federation, please submit a request using the Support portal of the Gigya Dashboard or by sending an email to support@gigya.com.

Setup And Activate Your Proxy Page

The proxy page is responsible for managing the state of user authentication.

  • Handle login through the login page if the user is not logged-in.
  • Handle and validate the user consent flow.
  • Respond with authentication status to the OP authorization endpoint.
  • Handle errors through the error page.

The proxy page includes certain OP parameters and pushes these to the Login page, Consent page, and Error page when required.

The proxy page must include:

  • References to Gigya's SDKs ( gigya.js, gigya.oidc.js ). See code example below.
  • A reference to your Login URL, Consent URL and Error URL URIs.

Example:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Open ID Connect Proxy Page | Sample</title>
<script type="text/javascript" lang="javascript" src="https://cdns.gigya.com/JS/gigya.js?apiKey=[Your_API_Key]"></script>
<script type="text/javascript" lang="javascript" src="https://cdns.gigya.com/JS/gigya.oidc.js?apiKey=[Your_API_Key]">
	{
        loginURL: "OPLoginPage.php",
        consentURL: "OPConsentPage.php",
        errorURL: "OPErrorPage.php"
    }
</script>
</head>
<body>
 
</body>
</html>

Ensure that you have created pages at the defined locations.

Once deployed, activate your OP via the Gigya Dashboard's OpenID Connect Provider page or using the fidm.oidc.op.setConfig API to define your site's Proxy page.

           

 

Implement Login Page

The loginURL handles the actual logging in of the user. This page must include a means of accomplishing this, i.e., contain a call to accounts.showScreenSet or socialize.showLoginUI

This page must include the gigya.js SDK and a call to redirect to the Proxy page with the necessary data. The example below uses Gigya's global onLogin event to trigger the redirect.

Example:

<html>
<head>
    <script type="text/javascript" src="https://cdns.gigya.com/js/gigya.js?apiKey=[Your-API-Key]"></script>
</head>
<body>
    <div id="container"></div>
    <script>
        function redirectToProxy() {
            var url = gigya.utils.URL.addParamsToURL("<Your-Defined-Proxy-Page-URI>",{
                mode: 'afterLogin'
            });
            window.location.href = url;
        }
        gigya.socialize.addEventHandlers({
            onLogin: function() {
                redirectToProxy();
            }
        });
        gigya.accounts.showScreenSet({
                screenSet: 'Default-RegistrationLogin',
                containerID: "container",
                sessionExpiration: '14400' // 4 hours
        });
    </script>
</body>
</html>

 

Implement Consent Page

The Consent flow is used to:

  • Approve authentication by your server.
  • Prompt for end-user consent when requested.

Approve Authentication By Your Server

Your server will need to:

  • Perform request validation and approve the authentication and return the end-user's details to the Proxy page.
  • Sign a consent token.

To construct the consent token, see Consent Endpoint.

Prompt For End-user Consent

You may want to prompt the user for consent.

An appropriate UI should be displayed to the end-user and should include:

  • RP details.
  • Requested scopes (You may allow the end-user to grant/revoke the requested scopes).

To construct the consent token, see Consent Endpoint.

In the event Consent fails, either from the user closing their browser or otherwise canceling the process, or the signatures do not validate, the server should have logic to process these scenarios.

Consent Endpoint

Consent is handled on your server and the process will vary depending upon your requirements and preferred language, e.g., PHP, ASP, Ruby.

The parameters that are forwarded to your consent endpoint are as follows:

  • context
  • clientID
  • scope (requested scopes)
  • prompt (optional)
  • display (optional)
  • UID
  • UIDSignature
  • signatureTimestamp

Once the consent endpoint receives the above information from the Authorize endpoint, it should perform it's logic and return the following as a query string to the Proxy page:

  • mode (afterConsent)
  • consent obj, which must include the following:
    • clientID
    • context
    • scope (approved scopes)
    • UID
    • consent (boolean)
  • signature

The above parameters, excluding the signature, must be passed as JSON. The signature hash is then constructed using that JSON and the Partner's secret and the data is returned to your Proxy page URL encoded.

Example:

https://demo.gigya.com/OIDCProxyPage.php?mode=afterConsent&consent={"scope":"openid email profile","clientID":"yL_zC...27d","context":"st1.N2knE6xODsvxql-utoLzKEC-p-k.5...zEqnboA.I8r9...vchX-zyQo...YHhE-4","UID":"_guid_...oOILtDQ5Hi0=","consent":true}&sig=FnVj2...LZQ"

Creating the signature should only ever be completed on the server, as it requires your Partner secret, which should never be exposed on the client-side.

 

Example:

/* *************************************************************************************************
* PHP example for constructing a signature using Gigya's PHP SDK
* Important! Ensure that you remove all padding '=' and convert all '+' to '-' and all '/' to '_'
* prior to sending to the Gigya endpoint
************************************************************************************************* */
$scope = preg_replace('/[+]/', ' ', $scope); // Important: scope string must contain white-space spaces, not '+' or '%2b' or sig validation will fail.
$consentObj = json_encode(array(
    "scope" => $scope,
    "clientID" => $clientID,
    "context" => $context,
    "UID" => $UID,
    "consent" => true
));
$consentObjSig= SigUtils::calcSignature($consentObj, $secret); 

$consentObjSig= preg_replace("/=$/", "", $consentObjSig);
$consentObjSig= preg_replace("/=$/", "", $consentObjSig);
$consentObjSig= preg_replace("/[+]/", "-", $consentObjSig);
$consentObjSig= preg_replace("/\//", "_", $consentObjSig);

This query string should be then passed to the Proxy page using a redirect and include the mode parameter set to afterConsent.

 

Example:

<script>
	var consentOBJString = '<?php echo $consentObj ?>';    
	var consentObjSig = '<?php echo $consentObjSig ?>';
	URLStr='yourProxyPage.html?mode=afterConsent&consent=' + consentOBJString + '&sig=' + consentObjSig;
	window.location.href=URLStr;
</script>

 

Implement Error Page

In the event of an error, the browser will redirect to your defined errorURL with a query string including the data regarding the error that occurred.

You should design the UI to handle this data and present it to the user in a friendly manner, if necessary.

Example:

<html>
<head>
<title>OP Error Page | Sample</title>
</head>
<body>
<div class="responseDiv" id="responseDiv" style="width: 50%; height: 50%; overflow: auto; text-align: left; margin: 0px auto;">
</div>
<script>
    thisUri = window.location.href;
    decodedUri = decodeURIComponent(thisUri);
    decodedUri = decodedUri.replace("https://[URI_Of_Your-Error_Page]?", "");
    decodedUri = decodedUri.replace(/,/g, ",<br />&nbsp;&nbsp;&nbsp;&nbsp;");
    decodedUri = decodedUri.replace(/{/g, "{<br />&nbsp;&nbsp;&nbsp;&nbsp;");
    decodedUri = decodedUri.replace(/}/g, "<br />}");
    document.getElementById('responseDiv').innerHTML = decodedUri;
</script>
</body>
</html> 

 

Register a Relying Party (RP)

To enable an RP to connect to the Gigya OP you will need to:

  • Configure the RP within the Gigya OP.
  • Provide the OIDC endpoints and the client's details to the RP.

Configure the RP on Gigya OP

  1. Open the OpenID Connect Provider page on Gigya's Console. 
  2. Click Configure OP Settings and enter the URL of the proxy page you created earlier. 
  3. Click Create RP.
  4. In the Create RP page, enter a description for this RP. 
  5. Under Allowed Scopes, select the scopes you wish to make available to the RP. If the scope is not selected, the RP will not be able to use that scope. Gigya supports the following scopes: 
    • openid - (Required) - Informs the Authorization Server that the Client is making an OpenID Connect request and is mandatory.
    • email - (Optional) - Requests access to the email and email_verified Claims of the user.
    • profile - (Optional) - Requests access to the End-User's available profile Claims, which are: 
      • name - The user's Gigya name.
      • family_name - The user's Gigya lastName.
      • given_name - The user's Gigya firstName.
      • nickname - The user's Gigya nickname.
      • email - The user's Gigya email.
      • picture - The user's Gigya photoURL.
      • gender - The user's gender.
      • birthdate - The user's birthdate.
  6. You may limit the RP to only receive specific response types. Under Supported Response Type, select or deselect the types. 
  7. Under Subject Identifier Type, choose between returning a unique auto-generated ID (pairwise) that is based on the UID, or the user's UID (the Public option). 
  8. The RP must provide the OP with any redirect URIs they will be using. These URIs must be HTTPS and are entered under Redirect URIs in the respective section. Any requests using redirect URIs that have not been pre-configured will fail.
  9. Finally, define an Access Token Lifetime. This is the length of time the granted access_token is valid from the time it was issued and may be from 60 to 604800 seconds (7 days), if left blank, the default is 86400 seconds (24 hours).
  10. Click Create
  11. To make changes to the RP, in the list of RPs, click the Edit button: 

Notes: 

Provide the OIDC Endpoints and Client Details to the RP

To configure OIDC login, the RP will need:

  • The OIDC endpoints
  • Their client details

Format of OIDC Endpoints

  • Authorize Endpoint
    https://fidm.[Data_Center_ID].gigya.com/oidc/op/v1.0/[The-OP-API-Key]/authorize
  • UserInfo Endpoint
    https://fidm.[Data_Center_ID].gigya.com /oidc/op/v1.0/[The-OP-API-Key]/userinfo
  • Token Endpoint
    https://fidm.[Data_Center_ID].gigya.com/oidc/op/v1.0/[The-OP-API-Key]/token
  • Introspect Endpoint
    https://fidm.[Data_Center_ID].gigya.com/oidc/op/v1.0/[The-OP-API-Key]/introspect


Token Introspection

Used to determine the current status of a previously received access_token. Claims returned from the Introspect endpoint for a valid access_token are:

  • active - boolean (if this is false, no other claims are returned)
  • scope
  • client_id
  • token_type
  • exp
  • iat
  • sub
  • aud
  • iss 

 

See OpenID Connect Protocol Coverage for supported parameters for use with Gigya OIDC endpoints.

To review the OP's endpoints: 

  1. In the OpenID Connect Provider page in Gigya's Console, click OP Metadata
  2. Copy and save the Authorize, Token, UserInfo endpoints, and the JSON Web Keys obj, respectively. You will need to give this data to any RP using your site as OP.  

If the OP is using a  CName , the endpoints will contain your CName URL, as opposed to the Gigya URL, e.g., https://cname.siteDomain.com/oidc/op/v1.0/...

 

Client Details

  1. In the OpenID Connect Provider page in Gigya's Console, locate the relevant RP and click Edit. 
     
  2. Copy and save the Client ID. 
  3. Next to Client Secret, click Show. Copy and save the client secret. 

Notes: 

  • The client ID must be included in the query string of all calls made to the OP Authorize and Token endpoints.
  • The client secret is required when using server-to-server calls to the Token endpoint when the RP is using Authorization Code flow.

 

Validating an id_token

For instructions on validating the id_token returned by a Gigya OP see How To Validate A Gigya id_token.

 

Live Demo

Gigya has a working demo RP site set up using demo.gigya.com as the OP. You can try it by following this link to the RP.

You can view the code (using PHP and JavaScript) below.

 

Code Examples

OP Pages

 

Login Page

<html>
<head>
<title>OIDC Login Page | demo.gigya.com</title>
    <script type="text/javascript" src="https://cdns.gigya.com/js/gigya.js?apiKey=<API-key>"></script>
    <style>
        /* ** --snipped-- ** */
    </style>
</head>
<body>
    <div class="" id="logoDiv">
        <img src="images/GigyaLogo_2016-05-04.png" />
    </div>
    <h2>Gigya OIDC OP Login Page</h2>
    <div id="container"></div>
    <script>
        function redirectToProxy() {
            var url = gigya.utils.URL.addParamsToURL("OIDCProxyPage.php",{
                mode: 'afterLogin'
            });
            window.location.href = url;
        }
        gigya.socialize.addEventHandlers({
            onLogin: function() {
                redirectToProxy();
            }
        });
        gigya.accounts.showScreenSet({
                screenSet: '26oct15-RegistrationLogin',
                containerID: "container",
                sessionExpiration: '14400' // 4 hours
        });
    </script>
</body>
</html>

 

 

 

RP Pages

 

Index Page

<!DOCTYPE html>
<html>
    <head>
        <title>demo.gigya.com | OIDC RP Site</title>
        <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
	<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.9.2/jquery-ui.min.js"></script>
        <style type='text/css'>
            /* ** --snipped-- ** */
        </style>
    </head>
    <body>
    <div class="" id="main_wrapper">
            <div class="" id="logoDiv">
                <a href="https://rp-demo-gigya.herokuapp.com/">
                    <img src="images/GigyaLogo_2016-05-04.png" />
                </a>
            </div>
        <h2>Gigya OIDC Demo RP Site</h2>
        <p></p>
        <div class="" id="loginOptions">
            <h3>Select which flow you would like to use</h3>
            <button class="rpBtn" id="idTokenBtn" />ID Token</button>
            <button class="rpBtn" id="codeBtn" />Auth Code</button>
        </div>
        <script>
        $(document).ready(function() {
            //document.getElementById('codeBtn').disabled=true;
            $(document).on("click", "#idTokenBtn", function() {
                window.location="index_idToken.php";
            });
            //$(document).on("click", "#codeBtn", function() {
            //    window.location="index_code.php";
            //});
            $(document).on("click", "#codeBtn", function() {
                window.location="index_code2.php";
            });
        })
        </script>
    </div><!-- /main_wrapper -->
    </body>
</html>

 

 

 

Code Flow Diagram With Gigya as Openid Connect Provider

 

 

 

 

 

 

Additional Information

FIdM OIDC OP REST APIs

OpenID Connect Protocol Coverage

OIDC OP - Customizing Login For Multiple RPs