Gigya Job Openings

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 URL.

 

Configure your OP's issuer field of the id_token

To set the iss field of the id_tokens returned from your OP, configure the issuer in the Configure OP Settings section.

Once configured, if you remove the currently defined URL, it will revert to the default Site Name as defined in the Gigya Console for the API key that this OP belongs to.

 

Configure Custom Claims or Scopes

By default, Gigya supports 3 standard OIDC scopes, which are:

  • openid
  • email
  • profile

To add additional custom scopes and/or claims, configure them for your OP here.

Before creating a custom scope, you must define the claims that will be returned within the scope. You can map a custom claim to any available account field from the Custom Claims section of the page.

Once you have defined your claims, you can now define any necessary Custom Scopes and map these scopes to the required custom claims.

It is not possible to overwrite any of the default OIDC scopes. Claim and Scope names may not contain spaces and are case-sensitive.

 

 

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>

 

User And Application Keys

It is possible to construct the signature using a user/application key and a user/application secret. When this is done, it is important to pass the userKey as a query parameter to the Consent endpoint, so your URLStr will look similar to the following:

URLStr = 'yourProxyPage.html?mode=afterConsent&consent=' + consentOBJString + '&sig=' + consentObjSig + '&userKey=' + userKey';

Note that just like a partner secret, a user/application key secret should never be exposed on the client-side.

 

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. 

    The OP can control the scopes the RP can access within the logic of the Consent endpoint. The available scopes that may be used are:

    • 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.

    If an RP is granted access to the Profile scope, they will have access to the information for the user only if it exists.

  5. You may limit the RP to only receive specific response types. Under Supported Response Type, select or deselect the types. 
  6. 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). 
  7. 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.
  8. 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).
  9. Click Create
  10. 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

The license could not be verified: License Certificate has expired!

 

Token Introspection

Used to determine the current status of a previously received access_token. As an RP it may be necessary to check whether an access_token you have is still valid.

You can do this using the OP's introspect endpoint, which will look similar to the following:

https://fidm.us1.gigya.com/oidc/op/v1.0/<THE-APIKEY-OF-THE-OP>/introspect

 

 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 

You construct the request to the introspect endpoint just like you do for the  token endpoint, using a Basic Auth token.

Introspection Code Example

A PHP code example for installing a simple introspection endpoint follows:

<?php
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);
$clientID = "THE-RP-CLIENT-ID";
$clientSecret = "THE-RP-CLIENT-SECRET";
$apiKey = "THE-OP-APIKEY";
$accessToken;
 
if (isset($_POST['accessToken']) && $_POST['accessToken'] !== "") {
    $accessToken = $_POST['accessToken'];
} else {
    $accessToken = 'undefined';
    return;
}
 
// Try introspection
function tryIntrospection($inc_token,$id,$sec,$api) {
    $authHeader="Basic ";
    $client_ID = $id;
    $secret= $sec;
    $hashedAuthString=base64_encode($client_ID . ":" . $secret);
    $authHeader .= $hashedAuthString;
    $ch = curl_init();
    $introData = "token=" . $inc_token;
    $urlintrospection = "https://fidm.us1.gigya.com/oidc/op/v1.0/" . $api . "/introspect";
    curl_setopt($ch,CURLOPT_URL,$urlintrospection);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: ' . $authHeader));
    curl_setopt($ch,CURLOPT_POSTFIELDS,$introData);
    curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
    $curlResult = curl_exec($ch);
    curl_close($ch);
    echo $curlResult;
}
if ($accessToken) {
    tryIntrospection($accessToken,$clientID,$clientSecret,$apiKey);
}
?>

Response Example for a Valid access_token

{
  "active": true,
  "scope": "openid email profile",
  "iat": 1520187782,
  "exp": 1835547782,
  "client_id": "yL_zCw6UxRkwDyAAAAAAAAAA",
  "aud": "yL_zCw6UxRkwDyAAAAAAAAAA",
  "iss": "https://demo.gigya.com/",
  "sub": "c-jEJNXpOY9mXxxxxxxxxGdbvPs6hqxti6kWAQYSVlQ",
  "token_type": "Bearer"
}

Response Example for an Invalid access_token

{
  "active": false
}

 

Coverage

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

Available 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 gigyademo.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.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

Any unique user account can only be connected to a single custom SAML IdP or OIDC OP. Once connected, the user will not be able to use a different SAML/OIDC provider if they exist. However, a user can be associated with both a SAML IdP and an OIDC OP concurrently.

FIdM OIDC OP REST APIs

OpenID Connect Protocol Coverage

OIDC OP - Customizing Login For Multiple RPs