accounts.setPolicies REST

Skip to end of metadata
Go to start of metadata

 

Description

This method is used to modify site policies regarding user registration and login.

Gigya also provides a basic policies UI that can be accessed easily through the Policies page in your console. For more information visit our Policies page.

You may modify specific policies using this method. The method accepts a list of optional parameters each defining a specific policy. The parameters that are passed in the request modify the relevant policy while omitted policies remain unchanged.

If you wish to restore policy values back to their defaults, you may assign null values to whole policy sections, or to values inside the sections. If the site is a member of a group, then the group's default is restored. If the group doesn't have a default, Gigya's default is restored.

SSO Specific Policy Configuration

When setting Policies within a Single-Sign-On group situation, note the following: 

  • Settings within the group master are used as defaults for all child sites. 
  • Certain policy configurations can be overridden by the child site.

Overriding Master Configurations

The following lists all parameters that can be overridden by a child site:

  • verifyEmail object of the AccountOptions parameter
  • verifyProviderEmail object of the AccountOptions parameter
  • emailVerification
  • emailNotifications
  • passwordReset
  • requireCaptcha

To restore any of these values to their default (Master configuration) after they have been previously overridden, set them to NULL values.

 

Note: If you plan on integrating Gigya's Accounts API, we highly recommend reading the Registration-as-a-Service Guide. Registration-as-a-Service (RaaS) is a premium platform that requires separate activation. If RaaS is not part of your site package, please contact Gigya by filling in a support form through the Console. You can access the support page by clicking Support on the upper menu after logging into the Gigya Console.

Request URL

Where <Data_Center_ID> is:
  • us1 - For the US data center.
  • eu1 - For the European data center.
  • au1 - For the Australian data center.
  • ru1 - For the Russian data center.

If you are not sure of your site's data center, see Finding Your Site's Data Center.

Parameters

RequiredNameTypeDescription
accountOptionsJSON objectThe account options policy, which includes the following fields:
  • allowUnverifiedLogin - (boolean) This setting is only relevant if verifyEmail="true" and loginIdentifiers="username". Indicates whether to allow users to log in before they have verified their emails. The default value is false.
  • defaultLanguage - (string) The language to use in email templates when the requested language is not available. By default, if this field is not modified, the default language is English (en). Please make sure that the default language has a corresponding email template definition.
  • loginIdentifierConflict - (string, see available options below) Activates account linking for users entering the system with an unregistered social network, which shares an e-mail with a registered account.
    • ignore - No account linking will take place.
    • failOnSiteConflictingIdentity - Account linking is only enabled if the conflicting account is also a Site account (not purely a social network account).
    • failOnAnyConflictingIdentity - Account linking is enabled for any account which uses the same email.
  • loginIdentifiers - (comma separated string) Select the preferred login identifier for your users, the options are email, username, or both ('email, username'). The default value is email. This will affect the requirement of the login / registration process. Optionally you may also add providerEmail (when users register using their social identity, the email provided by the social network will be recognized as a Site login identifier). 
  • preventLoginIDHarvesting - (boolean) Indicates whether to prevent account harvesting. Account harvesting refers to the process of grabbing legitimate user IDs and passwords to gain access to target systems for illegal or malicious purposes. The default value is false. Setting this parameter to true influences the behavior of several API methods and on the user experience, read more under the Protect Against Account Harvesting section of the Policies guide.
  • sendAccountDeletedEmail - (boolean) When set to true , an email will be sent after an account is deleted. Cannot be set to true , without an  Account Deletion Confirmation  email template having been defined either in the accountDeletedEmailTemplates parameter or in the RaaS Email Templates . The default value is false.
  • sendWelcomeEmail - (boolean) When set to true , an email will be sent after completion of registration and email verification (if email verification is required). Cannot be set to true , without a New User Welcome  email template having been defined either in the welcomeEmailTemplates parameter or in the RaaS Email Templates . The default value is false.
  • verifyEmail - (boolean) Indicates whether your users' email addresses require validation or not. The default value is false. Email verification is done by sending a verification email to each of the email addresses. The format of the verification email is specified using the emailVerification policy (see below).

    When this parameter is set to true, users are required to have at least one verified email address in order to log in. Therefore, we highly recommend that you set the email field as required in the profile schema.

  • welcomeEmailTemplates  - Email templates are defined as a JSON object containing a list of email templates, with separate templates for each language. 
  • verifyProviderEmail - (boolean) Indicates whether to require validation of email addresses coming from providers that are known to validate the email addresses. The default value is false, in other words, email addresses coming from providers that are known to validate the email addresses are accepted as validated for login purposes. If this is set to true, email verification is done by sending a verification email to each of the email addresses. The format of the verification email is specified using the emailVerification policy (see below).

Assigning a null value to any parameter restores it's Gigya default value (see the method description for specific default values).

Note: You may also set this policy using the Policies page in your Gigya Console. 
emailNotificationsJSON object

The email notification policy, which includes the following fields:

  • confirmationEmailTemplates - An email template object listing email templates by language. Only required if sendConfirmationEmail was set to true and no Confirmation Email template was defined in the Admin Console's RaaS Email Templates page.
  • accountDeletedEmailTemplates - An email template object listing email templates by language. Only required if sendAccountDeletedEmail was set to true and no Account Deleted template was defined in the Admin Console's RaaS Email Templates page. 
  • accountDeletedEmailDefaultLanguage  - (string) Defines which language is the default language for sending Account Deleted emails.
  • confirmationEmailDefaultLanguage regex(....), in which case the regex is matched against the regSource. If no regSource matches, then en (English) is used.

    Email templates can not be deleted if the default lang parameter points to it. Furthermore, it is not possible to set the default lang if a template does not currently exist in that language.

emailVerificationJSON objectThe email verification policy, which includes the following fields:
  • autoLogin - (boolean) when set to true, the user will be logged into the site automatically at the conclusion of the email verification process. The default value is false.

    When autoLogin is set to true , you must specify a landing page in the nextURL property of the emailVerification object also (below). The landing page must contain the Gigya Javascript library and will automatically fire the onLogin global event .

  • emailTemplates - An email template object listing email templates by language. Only required if no Verification Email template was defined on the Admin Console's RaaS Email Templates page. 
  • defaultLanguage - (string) The language to use when the requested language is not available. By default, if this field is not modified, the default language is English (en). Please make sure that the default language has a corresponding email template definition.
  • nextURL -  (string) The page to which the user will be redirected after verifying his email. If a page isn't specified, Gigya provides a URL to display to users:  http://accounts.gigya.com/GS/VerifyEmail.aspx .
  • nextURLMapping - The page to which the user will be redirected after verifying his email based on the origin of the registration process. The policy includes the following fields:
    • regSource - A string to match against the regSource value. It may end with * for a prefix match, or begin and end with * for any partial match, or it may not contain any * for an exact match. It may also be in the format of "regex(....)", in which case the regex is matched against the regSource. If no regSource matches, then the value of emailVerification.nextURL is used as the default fallback.
    • nextURL - (string) The page to which the user will be redirected after verifying their email.

This setting may be overridden by site members in a site group configuration. The path to be matched is the full path including the protocol (http/https).

  • verificationEmailExpiration - (integer) How long the verification email is valid, in seconds. The default is 86400 seconds (24 hours).
Assigning a null value restores the default values (see the method description).
gigyaPluginsJSON object
The Gigya plugins policy defines a default behavior, which may be overridden using the Global Conf object. The policy includes the following fields:
  • defaultMobileRegScreenSet - (string) The ID of the screen-set to use following Social Login on mobile devices.
  • defaultRegScreenSet - (string) The ID of the screen-set to pop-up following Social Login (e.g., when a user clicks on a social network button within one of Gigya's Engagement Add-Ons) in case the user is new and needs to complete a registration process. W hen changing the policy's default screenSet, make sure the screenSetID has been defined in the Screen-Sets section of your Gigya Console.  
  • rememberSessionExpiration  - (integer) A session expiration value to use when the user checked the remember me checkbox.
    This parameter accepts the same values as sessionExpiration (below).
  • sessionExpiration - (integer)

    This parameter defines the length of time that Gigya should keep the user's login session valid.

    The expected values are:

    •  0 - Session expires when the browser closes.

    • -1 - Session ends immediately and a cookie is stored on the site visitor's client (browser) which allows the site to change the expiration while the user is logged in. Useful if you always and only set the session expiration via individual API methods. For additional information see how to Control Session Expiration.

    • -2 - Session is valid forever.

    • Any custom integer, defined as the number of seconds to keep the session active, e.g., 3600  (which is equivalent to 1 hour).  In this case, the session will remain valid until it expires or until it is explicitly ended (e.g., by calling accounts.logout).

    You can override global policy settings and the Global conf setting via setting the expiration as a parameter in any of the supported API methods (i.e., notifyLogin). When this parameter is set via an API method, it overrides the value of the identical parameter in Global Conf (the global configuration object).

    If this parameter is not set for the API method, the value from Global Conf is used. If the parameter is not set in Global Conf, the login session uses the default.

    Defaults: 

    • When RaaS is enabled for the API Key, default expiration is 0 (when the browser closes).
    • When using Social Login (RaaS is not enabled), default expiration is -2 (the session is valid forever and only terminates when the user logs out or the cookie is deleted).
passwordComplexityJSON objectThe password complexity policy, which includes the following fields:
  • minCharGroups - (integer) The number of the different character groups that must be included in the password. The character groups are capital letters, lowercase letters, numbers and special characters.
  • minLength - (integer) The minimum number of characters required for the password.
  • regExp - An alternative/additional way to specify password strength is by defining a string pattern that the passwords must match.
Assigning a null value restores the default values (see the method description).

Note: You may also set this policy using t he Policies page in your Gigya Console. 

passwordResetJSON objectThe passwordReset method includes the following fields:
  • emailTemplates  - An email template object listing email templates by language. Required if no Password Reset Email template was defined on the Admin Console's RaaS Email Templates page. 
  • defaultLanguage - (string) The language to use when the requested language is not available. By default, if this field is not modified, the language is English (en). Please make sure that the default language has a corresponding email template definition.
  • requireSecurityCheck - (boolean) If set to true , this indicates additional verification is required before allowing a password reset link to be sent out. If the account doesn't have any email address on file then a security check is always required regardless of this policy. The default value is false.

    If you set requireSecurityCheck:true, then you must add the reserved secretQuestion and secretAnswer fields to your Registration and Registration Completion screens of your site's screen-sets via custom markup. Failure to do this will make it impossible for users to reset their password.

    For more information see Using Security Questions.

  • resetURL - (string) A site URL where the password can be reset using the passwordResetToken  parameter (see accounts.resetPassword).
    If the URL is not set here, accounts.resetPassword will use the Gigya default URL of https://socialize.<Data_Center_ID>.gigya.com/newPassword/.
  • securityFields: [ ["one","two"], ["three","four"], ...] - An array of arrays of existing field names. Each internal array represents a pair of fields that may be used to validate a password recovery request. 
    For example ["zip","phone"], ["zip", "birthday"].

    Whichever fields you set as securityFields need to be previously marked as required in your site's schema and have pre-existing values for the user attempting to recover their password.

     

  • sendConfirmationEmail - (boolean) The default value is false. When set to true, an email will be sent after successful password resets. Cannot be set to true, without a Password Reset Confirmation email template having been defined either in the confirmationEmailTemplates parameter or in the RaaS Email Templates.
  • tokenExpiration - (integer) The amount of time, in seconds, allowed before the password reset token expires. The default is 3600 (1 hour).

Assigning null value restores the default values (see the method description).

Note: You may also set aspects of this policy using the Email Templates page in the Gigya Console

profilePhotoJSON object

This policy defines the size of the profile photo thumbnail. When uploading a profile photo, Gigya will save the file in the thumbnailURL Profile field (the original photo is saved in the photoURL field).

The policy includes the following fields:

  • thumbnailHeight - (integer) The height of the thumbnail profile photo in pixels. The default is 64.
  • thumbnailWidth - (integer) The width of the thumbnail profile photo in pixels. The default is 64.

Assigning null value restores the default values (see the method description).

registrationJSON object

The registration policy, which includes the following fields:

  • enforceCoppa - (boolean) Indicates whether to apply age limit verification. Only users above the age of 13 will be able to register. The default value is false.
  • requireCaptcha - (boolean) Indicates whether to require CAPTCHA validation when your users go through the process of registration to your site. The default value is false
  • requireLoginID  - (boolean) Indicates whether a 'Site' account loginID is required, when a user uses Social Login to register to the site. The default value is false.
    When set true, the user will be prompted to complete a site registration after successfully registering with their social network. 
  • requireSecurityQuestion - (boolean) Indicates  whether a secret question is required. The default value is false

Assigning null value restores the default values (see the method description).

securityJSON objectThe security policy, which includes the following fields:
  • accountLockout - An object that includes the following fields:
    • failedLoginThreshold - (integer) The number of consecutive failed login attempts to a specific account, after which the account will be locked for the amount of time specified in the lockoutTimeSec value (below). The default is 0, which means there is no threshold.
    • lockoutTimeSec - (integer) The duration of the lockout, time in seconds. The default value is 0 (no lockout time is enforced).
    • failedLoginResetSec - (integer) How long after the last failed login attempt the login fail count will automatically reset itself. The value is in seconds and can be 1-1000000. The default value is 0, which means that the fail count never resets automatically.

      This field only applies if the account has not been locked out yet. If the account has reached the failedLoginThreshold then it will remain locked for the time specified in lockoutTimeSec.
       
  • captcha - An object that includes the following field:
    • failedLoginThreshold  - (integer) The number of consecutive failed login attempts to a specific account, after which a CAPTCHA will be required for the next login attempts. The default value is 0, which means there is no threshold.
       
  • ipLockout - An object that includes the following fields:
    • hourlyFailedLoginThreshold - (integer) The number of hourly failed login attempts from the same IP address, after which the IP address will be locked for the lockoutTimeSec value. The default value is 0, meaning that there is no IP lockout threshold.
       
    • lockoutTimeSec - (integer) The duration of the lockout time in seconds. The default is 0, meaning there is no lockout time is enforced.
       
  • passwordChangeInterval - (integer) The number of days after which there is a mandatory password change. The default is 0, which means that there is no need to change the password.
  • passwordHistorySize - (integer) When a user changes their password, they are not allowed to use this number of previous (historic) passwords. The default is 0, and the maximum value is 7.
twoFactorAuthJSON objectTwo-factor authentication (TFA) policy includes the following fields:
  • mode - (Deprecated).
  • providers - An array of objects, each representing a provider. Each object in the array has the following fields:
    • name - The ID assigned to this provider by Gigya, e.g., gigyaPhone.
    • enabled - Indicates whether this method is enabled for the site. The default value is "false".
    • params - An object where extra information may be stored:

       params: {
            "param1" : "value1",
            "param2" : "value2"
       } 
  • deviceExpirationPeriod  (Deprecated).
federation JSON objectThe federation policy, which includes the following field:
  • allowMultipleIdentities - (boolean) Indicates whether federated accounts (currently SAML/OIDC providers) can contain multiple providers. The default value is false. 
    If allowMultipleIdentities is true in an enterprise environment, see Security Implications For Enterprise Environments.
    If allowMultipleIdentities is false there are other implications that are listed below. 
format string Determines the format of the response. The options are:
  • json (default)
  • jsonp - if the format is jsonp then you are required to define a callback method (see parameter below).
callback string This parameter is required only when the format parameter is set to jsonp (see above). In such cases this parameter should define the name of the callback method to be called in the response, along with the jsonp response data.
httpStatusCodes Boolean The default value of this parameter is false, which means that the HTTP status code in Gigya's response is always 200 (OK), even if an error occurs. The error code and message is given within the response data (see below). If this parameter is set to true, the HTTP status code in Gigya's response would reflect an error, if one occurred.

Email Template Objects

Email templates are defined as a JSON object containing a list of email templates, with separate templates for each language, using the following format:

{<language code1> : <HTML of email template>, <language code2> : <HTML of email template>,  ... }

Each template applies to a specific language codeIf a user registered using the accounts.register API method with the lang parameter specified, and a template was defined for that language, the email sent to the user will be in that language. Otherwise, the language used in the email is taken from the locale field of the site identity, if available. If email templates were defined in the Admin Console's RaaS Email Templates page and you set email templates in the API, then they are added to the existing templates or override those with the same language. To remove existing templates, you need to explicitly set them to null.

The templates are specified as HTML templates that support placeholders and META tags. Please refer to the Email Format to learn more. Gigya's default templates are in English.

Note: Email templates can be designed using the Email Templates page in Gigya's Admin Console. 

Authorization Parameters

Each REST API request must contain identification and authorization parameters.

Please refer to the Authorization Parameters section for details. 

Response Data

FieldTypeDescription
 
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
statusReason string A brief explanation of the status code.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or

A field that does not contain data will not appear in the response.

Response Example

{
        "statusCode": 200,
        "errorCode": 0,
        "statusReason": "OK",
        "callId": "ddb3f8e144c84cb5b1bc5f010bddab2b",
        "time": "2015-03-22T11:42:25.943Z"
}

Implications of the Federation Policy

When a user logs in with a SAML provider, ifederation.allowMultipleIdentities is set to "false" (default) there are some implications:

  • The account cannot use socialize.addConnection, so it cannot be linked to any other provider. If socialize.addConnection is called, an "operation not allowed" error is returned (400030).

  • The account cannot be linked to another account, so if socialize.setUID and accounts.linkAccounts are called, an "operation not allowed" error is returned (400030).

  • The account does not set any login identifier, so an email or username, if exists, will not be regarded as a login identifier and will not enable login to the same account in any other way.

  • Even if the registration.requireLoginID option is set to "true", federation.allowMultipleIdentities will override it, so a loginID will not be required for a federated (SAML) login.

  • The account cannot use socialize.removeConnection, so it cannot be unlinked from the SAML provider. If socialize.removeConnection is called, an "operation not allowed" error is returned (400030).

Security Implications For Enterprise Environments

If using SAML to manage corporate users (i.e., via Active Directory), it is important to point out that having allowMultipleIdentities set to true will make it possible for users to connect other 3rd party accounts (i.e., Facebook) to their SAML accounts. This will make it impossible to delete/revoke users access by removing them from the SAML IdP, as these users will still have access to the resource via their alternate/linked accounts.

Password Policies

Setting the Password Reset policy 

To set the Rest Password Policy for your site, please follow these steps.
  1. Login to the Gigya Console .
  2. Go to the Site Settings of the site you wish to set the Password Policy.

  3. Proceed to the Policies tab (located in the Registration-as-a-Service group).

  4. Here you can set the basic parameters for the Password Policy.
    1. Password Strength
      1. Set the Minimum length you require for a new password.
      2. Set the Minimum Character Groups you require for a valid password. A Character Group is each of either Capital LettersLowercase LettersNumbers, and/or Special Characters.
    2. Password Change
      1. Set whether you require a new password after a specific amount of time (in days).
      2. Set whether to allow users to re-use any of the previous passwords.
      3. You can also add any Regular Expression validation.

  5. Save Settings in the bottom right-hand of the page.

passwordComplexity Parameter

The passwordComplexity parameter can be set within the Gigya Console (as shown above in step 4a, Password Strength), or can be edited manually via REST.

Secret Question and Answer

If you have set  requireSecurityCheck to true within the passwordReset object and are going to use secret question/answer pairs, you will need to ensure the appropriate fields are included on all applicable screen-sets, as well as ensure that these fields are mapped appropriately within the schema and set as 'Required'. If any of these steps are not completed, users will not be able to reset their passwords.

You must also set the registration parameter requireSecurityQuestion to true.

If you set requireSecurityCheck to true and do not use secret question/answer pairs, then Gigya defaults to using the securityFields parameter, and you must define which fields that are checked, within the  passwordReset object.

Sending a resetPassword request using the relevant security checks  

When users attempt to reset their password and you have set requireSecurityCheck to true, Gigya first checks to see if you have secret question and answer fields defined. If you do, the API gets that information, if you do not then the API checks the securityFields object to determine which fields to pass as the security questions.

The user is then prompted with a dialog asking for the answers to the applicable questions.

If the user answers the challenges correctly, then the Password Reset is processed, otherwise, the user will receive an error and the Password Reset flow will cease. 

A code example 

<?php

/* CODE EXAMPLE SNIPPET FOR SET POLICIES */
$apiKey='<YOUR API KEY>';
$secretKey='<YOUR SECRET KEY>';
include_once ('/<PATH>/<TO>/GSSDK.php'); // Must include the GSSDK!
$error = '';
$method = 'accounts.setPolicies';
$request = new GSRequest($apiKey,$secretKey,$method);
$rUserUID = '<UID OF CURRENT USER>';

// >>>>>>>>>> Step 2 - Set up variable objects
$paramN01 = 'passwordComplexity';
  $complexityObject = '({"minCharGroups":3, "minLength":6})';
$paramN02 = 'passwordReset';
  $resetObject = '({"defaultLanguage":"en", "sendConfirmationEmail":true, "tokenExpritation":604800, "requireSecurityCheck": true, "securityFields":[["zip","phone"], ["zip", "birthday"]]})';
// >>>>>>>>>> Step 2 - Adding parameters    
$request->setParam("UID", $rUserUID);
$request->setParam($paramN01, $complexityObject);
$request->setParam($paramN02, $resetObject); 
   
// >>>>>>>>>> Step 3 - Sending the request
$response = $request->send();

// >>>>>>>>>> Step 4 - handling the request's response.
if($response->getErrorCode()==0) {    // SUCCESS! response status = OK  
     echo '<br />Successful Operation!';
} else {  // If Error
     $error .= $response->getErrorMessage();
     $error .= '<br />';
     error_log($response->getLog());
     echo $error;
     return;
}

?>