Subscribe to PortalGuard's Quarterly Newsletter for News & Updates on the Latest Release! Click to Subscribe

How to Configure and Use PortalGuard's Account Activation Feature


Problem

You want to further secure your Account Creation/Propagation and move away from standard initial password formats.

Solution

Use Account Activation within PortalGuard to create update the process by creating a Long-Lived One-Time Passcode (OTP) to deliver to the end-user for Account Activation.

Quick Navigation

Pre-Requisites

  • Must be using PortalGuard version 5.6.2.3 or Later
  • Target user must exist in the User Repository

Configuration

  1. Navigate to the PortalGuard server and open the PortalGuard Configuration Editor.
  2. Under the User Repositories tab, highlight the User Repository for which you would like to enable Account Activation and click the 'Edit' button.
  3. Navigate to the Features -> User Activation sub-tab and check the box labeled 'Allow Account Activation':
  4. Modify the settings as needed.
      • Important Note: Hover over any blue text to view additional context information about each setting.  Some details are provided here for reference as well:
        • 'OTP Length' - The number of characters in the Long-Lived OTPs generated by PortalGuard. 
          • This character set is configured to be "easy to read", and only contains the following characters to reduce misinterpretation:
            • ABCDEFGHJKLMNPQRTUVWXY346789
        • 'OTP Expiration' - The number of days until an unused OTP expires and can no longer be used to activate an account.
        • 'Include Separator Every X Characters' - This setting will insert a hyphen ('-') into the OTP at set intervals.  This is intended to make the OTP easier to read.
        • 'Require Captcha?' - When enabled, the user will be prompted to correctly answer a CAPTCHA to ensure the request is not coming from a bot or automated process.  This requires CAPTCHA functionality to be enabled in PortalGuard already. 
          • Important Note: If CAPTCHA is required for SSPR via PortalGuard, this setting MUST be enabled. 
        • 'Verify Extra Data First' - By default, the OTP is validated before any custom data fields.  This setting validates custom fields before the OTP, and could be used to dynamically add fields to the UI, or make further customizations. 
        • 'Delete Activation Data on Strike Out' - Enabling this setting will delete activation data for a user if they strike out when attempting to activate.  
          • Important Note: Account Lockout must be enabled within the security policy for this feature to work.  Only invalid OTP entries count as strikes. 
        • 'Reset Password Within X Minutes' - The number of minutes the user has to set their password after activating the account via the Long-Lived OTP.  If the password reset step takes too long, the user will be required to reactivate their account
  5. Save the changes.
  6. Click on the 'Apply to PortalGuard Server' button.
  7. Click the 'Sync' button.

Usage

Usage of the Account Activation feature requires that customers integrate HTTP requests to the PortalGuard API into the current back-end Account Creation/Propagation process. Please note the following:

  • All required fields (see below) must be included in the POST data for each request.
  • GET requests are NOT supported.
  • A separate request must be made for each account.
  • All parameter names and values must be URL-encoded to ensure proper transmission and interpretation by the PG server.
  • The success/failure status code and long-lived OTP must be parsed out of the HTTP Response.

Required Fields

Please note: fields names are CASE-SENSITIVE

  • Auth - This value must always be 15.  It instructs the PG server to run the Batch Import agent.
  • BatchAdminUsername - The logon name of a service or user account that is specified within PortalGuard as a Batch Importer. 
    • This specification is made on the Policies tab of the bootstrap config within the PortalGuard Configuration Editor.  See the Batch Import KB article for more information.
  • BatchAdminPassword - The Password for the Batch Admin user account.
  • _PG_Login_Field_Username_ - This value must always be Username.
  • Username - The username of the target user.
  • ActivationOTP - This can be one of two values:
    • create - Create and save the long-lived OTP and any organization-specific data.  This can be called multiple times - each successive call will overwrite any existing data.
    • delete - Delete the OTP and any other activation data.  This prevents activation of the account.

Optional Fields

All other fields sent in the request will be treated as opaque by PortalGuard (it will not try to interpret them).  Any number of "name=value" pairs can be included in the requests and they will be encrypted before being saved to the User Profile in PortalGuard.  The field names must be unique and both the names and values must be URL-encoded in the request. 

All 'Extra Data' sent in this manner must be provided by the end-user during activation for the activation attempt to be considered 'valid' or 'complete'.

Example HTTP Requests

The following examples utilize the freely available cURL utility.

Create - No Extra Data

curl --data "Auth=15&BatchAdminUsername=batcher&BatchAdminPassword=S0m3-S3cr3t&_PG_Login_Field_Username_=Username&Username=newuser&ActivationOTP=create" https://YOUR.PG.SERVER/_layouts/PG/PG.ashx

Create - One Extra Field ("Field1")

curl --data "Auth=15&BatchAdminUsername=batcher&BatchAdminPassword=S0m3-S3cr3t&_PG_Login_Field_Username_=Username&Username=newuser&Field1=some%20val&ActivationOTP=create" https://YOUR.PG.SERVER/_layouts/PG/PG.ashx

Create - Two Extra Fields ("Field1", "Field2")

curl --data "Auth=15&BatchAdminUsername=batcher&BatchAdminPassword=S0m3-S3cr3t&_PG_Login_Field_Username_=Username&Username=newuser&Field1=some%20val&Field2=2nd%20custom%20value&ActivationOTP=create" https://YOUR.PG.SERVER/_layouts/PG/PG.ashx

Delete

curl --data "Auth=15&BatchAdminUsername=batcher&BatchAdminPassword=S0m3-S3cr3t&_PG_Login_Field_Username_=Username&Username=newuser&ActivationOTP=delete"https://YOUR.PG.SERVER/_layouts/PG/PG.ashx

Example Responses

When utilizing the Account Activation feature, PortalGuard responds with XML that contains major error codes, minor error codes, and the long-lived OTP.  Important Note: The examples below have been formatted for legibility.  XML returned by PortalGuard does NOT have embedded new lines.

Major Errors:

  • 16 - The Request Succeeded
  • 17 - The request failed for some reason (see minor errors list in Appendix B of the PortalGuard Admin Guide)

Successful "create"

<?xml version="1.0" encoding="UTF-8"?>
<pg_return component="PG.dll">
    <maj_error>16</maj_error>
    <min_errors count="0"/>
    <otp>JHX6-QBG9-PPTQ-A8FE</otp>
</pg_return>

Failed "create" (user not found in directory)

<?xml version="1.0"encoding="UTF-8"?>
<pg_return component="PG.dll">
    <maj_error>17</maj_error>
    <min_errors count="1">
        <min_error>1300</min_error>
    </min_errors>
</pg_return>

Successful "delete"

<?xml version="1.0" encoding="UTF-8"?>
<pg_return component="PG.dll">
    <maj_error>16</maj_error>
    <min_errors count="0"/>
</pg_return>

Failed "delete" (1210 - user existed, but no activation data present)

<?xml version="1.0" encoding="UTF-8"?>
<pg_return component="PG.dll">
    <maj_error>17</maj_error>
    <min_errors count="1">
        <min_error>1210</min_error>
    </min_errors>
</pg_return>

Bonus: Testing via Fiddler 

When testing the Account Activation process, it can often be difficult to view the process end-to-end.  Fiddler is a freely available utility that can help isolate issues with your HTTP request.  See our Fiddler KB Article for more information on configuring Fiddler to decrypt SSL requests and be utilized for troubleshooting.

  1. Launch Fiddler and navigate to the Composer tab.
  2. Enter your HTTP request in the provided field. 
  3. Ensure the request type dropdown is set to POST
  4. Submit the request and view the response in fiddler to see the success/failure XML and proceed accordingly.

REV. 06/2019 | PortalGuard

  • 104
  • 27-Jun-2019
  • 35 Views