Authenticator Policy REST API

The Policy/Authenticator endpoint allows creating and managing authentication policies and the associated password policy parameters.

HID Authentication Service includes a set of default Authenticator policies.

Note: The API version supported by HID Authentication Service is 10.3.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/configuration/{tenant}/v2/Policy/Authenticator/	Get all authenticator policies
GET	Read	/configuration/{tenant}/v2/Policy/Authenticator/{id}:(String)	Retrieve authenticator policy
POST	Create	/configuration/{tenant}/v2/Policy/Authenticator/	Create new authenticator policy
PUT	Replace	/configuration/{tenant}/v2/Policy/Authenticator/{id}:(String)	Fully replace a known authenticator policy
DELETE	Delete	/configuration/{tenant}/v2/Policy/Authenticator/{id}:(String)	Delete a known authenticator policy

Required Permissions

Function	Required Permissions
GET	Get authentication policy Read reference data
GET ALL	Read reference data
CREATE	Create authentication policy Read reference data Update root group details Modify role permission set privileges Modify user roles Manage OOB Adapter Configuration If something went wrong when updating the user type(s): Get authentication policy Delete authentication policy
REPLACE	Get authentication policy Update authentication policy Read reference data Manage OOB Adapter Configuration
DELETE	Get authentication policy Delete authentication policy Read reference data Update root group details

Get All Authenticator Policies

[GET] /Policy/Authenticator

Copy

Sample Request URI

[GET] /configuration/{tenant}/v2/Policy/Authenticator

Copy

Sample Response

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 48,
   "resources":    [
            {
         "schemas":          [
            "urn:hid:scim:api:idp:2.0:policy:Authenticator",
            "urn:hid:scim:api:idp:2.0:policy:authenticator:Credential"
         ],
         "id": "AT_EMPPKI",
         "meta":          {
            "resourceType": "AuthenticatorPolicy",
            "location": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_EMPPKI",
            "version": "1"
         },
         "allowExpiredReset": "0",
         "challengeDisableThreshold": "-1",
         "defaultExpiryThreshold": "-1",
         "challengeTimeoutPeriod": "-1",
         "defaultValidDaysAdd": "1825",
         "defaultValidDaysEdit": "1",
         "directAuthenticatorPolicy":          {
            "type": "AuthenticatorPolicy",
            "value": "AT_SYSPKI",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_SYSPKI"
         },
         "name": "Employee PKI authentication",
         "notes": "PKI authentication for employee application login",
         "sessionTimeout": "3600000",
         "sessionValidPeriod": "84600000",
         "validChannelCodes":          [
            "CH_IIS",
            "CH_SSP",
            "CH_STAP",
            "CH_TRMSVC",
            "CH_VPN"
         ],
         "onlyIndirect": "true",
         "urn:hid:scim:api:idp:2.0:policy:authenticator:Credential":          {
            "validCredentialPolicies": ["CT_CRTCHK1"],
            "challengeType": "UL",
            "disableThreshold": "8"
         }
      },
            {
         "schemas":          [
            "urn:hid:scim:api:idp:2.0:policy:Authenticator",
            "urn:hid:scim:api:idp:2.0:policy:authenticator:Credential"
         ],
         "id": "AT_CUSTOTP",
          
         ************** TRUNCATED OUPUT **************
   ]
}

Get an Authenticator Policy

[GET] /Policy/Authenticator/{id}

Copy

Sample Request URI

[GET] /configuration/{tenant}/v2/Policy/Authenticator/AT_CUSTPW

Copy

Sample Response

{
   "schemas":    [
      "urn:hid:scim:api:idp:2.0:policy:Authenticator",
      "urn:hid:scim:api:idp:2.0:policy:authenticator:Password"
   ],
   "id": "AT_CUSTPW",
   "meta":    {
      "resourceType": "AuthenticatorPolicy",
      "location": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_CUSTPW",
      "version": "1"
   },
   "allowExpiredReset": "3",
   "challengeDisableThreshold": "-1",
   "defaultExpiryThreshold": "-1",
   "challengeTimeoutPeriod": "-1",
   "defaultValidDaysAdd": "1825",
   "defaultValidDaysEdit": "1825",
   "name": "Customer Static Password",
   "notes": "Static password login for customer authentication",
   "sessionTimeout": "3600000",
   "sessionValidPeriod": "86400000",
   "validChannelCodes":    [
      "CH_BBP",
      "CH_CALL",
      "CH_CSTPORT",
      "CH_IIS",
      "CH_SSP",
      "CH_STAP",
      "CH_VPN"
   ],
   "onlyIndirect": "false",
   "allowedForUserTypes": ["UT_CUST"],
   "urn:hid:scim:api:idp:2.0:policy:authenticator:Password":    {
      "passwordpolicy":       {
         "numOrAlpha": "true",
         "maxLength": "20",
         "minLength": "6",
         "notBlackListed": "true",
         "notUserAttribute": "true",
         "minDiffChars": "3"
      },
      "usernamepolicy":       {
         "numOrAlpha": "true",
         "maxLength": "50",
         "minLength": "4",
         "minDiffChars": "3"
      },
      "seedingType": "PARTIAL",
      "disableThreshold": "8",
      "numberOfSeeds": "4"
   }
}

Create an Authenticator Policy

[POST] /Policy/Authenticator

Accept: application/scim+json

Important: You cannot create an Authenticator Policy from scratch. You must use the copyFrom parameter to specify another Authenticator Policy ID from which to copy the configuration.

Only the following parameters can be set (other ones will use the value from the copyFrom resource):

id
name
notes
From urn:hid:scim:api:idp:2.0:policy:authenticator:Password:
- all parameters in passwordpolicy
- seedingType - can be “FULL”, “PARTIAL” or “BOTH”
- disableThreshold - number of failed attempts after which the password of the user will be disabled
- numberOfSeeds

Copy

Sample Request URI

[POST] /configuration/{tenant}/v2/Policy/Authenticator

Copy

Sample request where a new Authenticator Policy is created based on AT_CUSTPW (see the previous Get an Authenticator Policy sample response for reference).

Name and notes are modified as well as notOldPassword which is now true.

{
   "copyFrom":"AT_CUSTPW",
   "id": "AT_CUSTPW1",
   "name": "Customer Static Password 1",
   "notes": "Static password login for customer authentication 1",
   "urn:hid:scim:api:idp:2.0:policy:authenticator:Password":    {
      "passwordpolicy":       {
         "notOldPassword": "true"
      }
   }
}

Copy

Sample Response

{
   "schemas":    [
      "urn:hid:scim:api:idp:2.0:policy:Authenticator",
      "urn:hid:scim:api:idp:2.0:policy:authenticator:Password"
   ],
   "id": "AT_CUSTPW1",
   "meta":    {
      "resourceType": "AuthenticatorPolicy",
      "location": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_CUSTPW1",
      "version": "1"
   },
   "allowExpiredReset": "3",
   "challengeDisableThreshold": "-1",
   "defaultExpiryThreshold": "-1",
   "challengeTimeoutPeriod": "-1",
   "defaultValidDaysAdd": "1825",
   "defaultValidDaysEdit": "1825",
   "name": "Customer Static Password 1",
   "notes": "Static password login for customer authentication 1",
   "sessionTimeout": "3600000",
   "sessionValidPeriod": "86400000",
   "validChannelCodes":    [
      "CH_BBP",
      "CH_CALL",
      "CH_CSTPORT",
      "CH_IIS",
      "CH_SSP",
      "CH_STAP",
      "CH_VPN"
   ],
   "onlyIndirect": "false",
   "allowedForUserTypes": ["UT_CUST"],
   "urn:hid:scim:api:idp:2.0:policy:authenticator:Password":    {
      "passwordpolicy":       {
         "numOrAlpha": "true",
         "maxLength": "20",
         "minLength": "6",
         "notBlackListed": "true",
         "notOldPassword": "true",
         "notUserAttribute": "true",
         "minDiffChars": "3"
      },
      "usernamepolicy":       {
         "numOrAlpha": "true",
         "maxLength": "50",
         "minLength": "4",
         "minDiffChars": "3"
      },
      "seedingType": "PARTIAL",
      "disableThreshold": "8",
      "numberOfSeeds": "4"
   }
}

Note: If you set defaultValidDaysAdd to -1, defaultValidDaysEdit must also be set to -1, and vice versa.

Replace an Authenticator Policy

Important: You cannot modify the default Authenticator policies, but you can clone them using copyFrom to define your own policies.

[PUT] /Policy/Authenticator/{id}

Accept: application/scim+json

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.

Copy

Sample Request URI

[PUT] /configuration/{tenant}/v2/Policy/Authenticator/AT_CUSTPW1

Copy

Sample request where AT_CUSTPW1 (see the previous Create an Authenticator Policy sample response for reference) is modified. The numOrAlpha constraint is disabled and instead the atLeastOneNum, atLeastOneUp and atLeastOneSpecial constraints are enabled.

{
    "id": "AT_CUSTPW1",
    "urn:hid:scim:api:idp:2.0:policy:authenticator:Password": {
        "passwordpolicy": {
            "atLeastOneNum": "true",
            "atLeastOneUp": "true",
            "atLeastOneSpecial": "true",
            "numOrAlpha": "false"
        }
    }
}

Copy

Sample Response

{
   "schemas":    [
      "urn:hid:scim:api:idp:2.0:policy:Authenticator",
      "urn:hid:scim:api:idp:2.0:policy:authenticator:Password"
   ],
   "id": "AT_CUSTPW1",
   "meta":    {
      "resourceType": "AuthenticatorPolicy",
      "location": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_CUSTPW1",
      "version": "1"
   },
   "allowExpiredReset": "3",
   "challengeDisableThreshold": "-1",
   "defaultExpiryThreshold": "-1",
   "challengeTimeoutPeriod": "-1",
   "defaultValidDaysAdd": "1825",
   "defaultValidDaysEdit": "1825",
   "name": "Customer Static Password 1",
   "notes": "Static password login for customer authentication 1",
   "sessionTimeout": "3600000",
   "sessionValidPeriod": "86400000",
   "validChannelCodes":    [
      "CH_BBP",
      "CH_CALL",
      "CH_CSTPORT",
      "CH_IIS",
      "CH_SSP",
      "CH_STAP",
      "CH_VPN"
   ],
   "onlyIndirect": "false",
   "allowedForUserTypes": ["UT_CUST"],
   "urn:hid:scim:api:idp:2.0:policy:authenticator:Password":    {
      "passwordpolicy":       {
         "maxLength": "20",
         "minLength": "6",
         "notBlackListed": "true",
         "atLeastOneNum": "true",
         "atLeastOneUp": "true",
         "atLeastOneSpecial": "true",
         "notOldPassword": "true",
         "notUserAttribute": "true",
         "minDiffChars": "3"
      },
      "usernamepolicy":       {
         "numOrAlpha": "true",
         "maxLength": "50",
         "minLength": "4",
         "minDiffChars": "3"
      },
      "seedingType": "PARTIAL",
      "disableThreshold": "8",
      "numberOfSeeds": "4"
   }
}

Add a Delivery Gateways Binding

You can update the authenticator policy to add a delivery gateway binding using the deliveryGateways property in the request.

Note:

As deliveryGateways is an array, the elements are ordered (the first one on the list will be the first one to be tested when needed).
If you create an authenticator policy by coping another one, the delivery gateways configuration is also copied.

Copy

Sample Request

PUT /configuration/{tenant}/v2/Policy/Authenticator/AT_CUSTPW
{
    "id": "AT_CUSTPW",
    "deliveryGateways": [{
            "value": "68474"
        }, {
            "value": "20977"
        }
    ]
}

Copy

Sample Response

PUT /configuration/{tenant}/v2/Policy/Authenticator/AT_CUSTPW
{
   "schemas":    [
      "urn:hid:scim:api:idp:2.0:policy:Authenticator",
      "urn:hid:scim:api:idp:2.0:policy:authenticator:Password"
   ],
   "id": "AT_CUSTPW",
   "deliveryGateways":    [
            {
         "display": "Azure Android",
         "value": "68474"
      },
            {
         "display": "Azure WNS",
         "value": "20977"
      }
   ],
   <--- truncated output --->
}

Delete an Authenticator Policy

Important: You cannot delete the default Authenticator policies.

All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:

Copy

Delete entity

DELETE https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/{id}

Accept: application/scim+json

Copy

Sample Response

HTTP/1.1 204 No content