Schema Extensions

Note: The API version supported by ActivID Appliance 8.7 is 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.

urn:hid:scim:api:idp:2.0:policy:Authenticator

This entity represents an authenticator policy.

The policy provides configuration information and constraints necessary to create an authenticator for a user through the Authenticator Policy endpoint.

  • It is a SCIM resource where:

    • id – the policy ID (that is, the authentication type code)

    • externalId – not configurable

    • meta – lifecycle information

    • deliveryGateways – to add delivery gateways bindings. It is an array of object with:

      • display – the adapter name

      • value – the adapter ID (mandatory when updating bindings)
  • Common attributes for all authenticator policies:

    Attribute Type

    adapterCode

    string

    allowExpiredReset

    int

    baseAuthenticatorPolicy

    MemberRef (string)

    challengeDisableThreshold

    int

    challengeTimeoutPeriod

    int

    defaultExpiryThreshold

    int

    defaultValidDaysAdd

    int

    defaultValidDaysEdit

    int

    directAuthenticatorPolicy

    MemberRef

    disableThreshold

    int

    disabledTimeReset

    int

    levelOfAssurance

    string

    managerAdapterCode

    string

    name

    string

    notes

    string

    sessionTimeout

    int long

    sessionValidPeriod

    int long

    validChannelCodes

    string[]

The policy also has the mutually exclusive extensions per authenticator type. For example:

  • urn:hid:scim:api:idp:2.0:policy:authenticator:Password

    • passwordpolicy – constraints with which a password must comply:

      Constraint Possible values Description

      onlyNum

      "true" or "false"

      Must contain only numeric characters

      onlyAlpha

      "true" or "false"

      Must contain only alpha characters

      numOrAlpha

      "true" or "false"

      Must contain only numeric or alpha characters

      numAndAlpha

      "true" or "false"

      Must contain only numeric and alpha characters

      maxLength

      Integer as String

      Maximum length

      minLength

      Integer as String

      Minimum length

      notSequence 

      "true" or "false"

      Must not be a sequence

      atLeastOneNum

      "true" or "false"

      Must contain at least one numeric character

      atLeastOneLow 

      "true" or "false"

      Must contain at least one lowercase character

      atLeastOneUp 

      "true" or "false"

      Must contain at least one uppercase character

      atLeastOneSpecial 

      "true" or "false"

      Must contain at least one special character

      notOldPassword 

      "true" or "false"

      Must not be an old password

      notUserAttribute 

      "true" or "false"

      Must not contain a user attribute

      minDiffChars 

      "true" or "false"

      Minimum numbers of different characters in password

      caseInsensitive

      "true" or "false"

      Case insensitive (not recommended)

      notBlackListed 

      "true" or "false"

      Must not contain black listed words

    • usernamepolicy - constraints with which a username must comply:

      Constraint Description

      onlyNum

      Contain only numeric characters

      onlyAlpha

      Contain only alpha characters

      numOrAlpha

      Contain either numeric or alpha characters

      numAndAlpha

      Contain both numeric and alpha characters

      maxLength

      Maximum length

      minLength

      Minimum length

      minDiffChars

      Minimum number of different characters

    • seedingType – "FULL", "PARTIAL" or "BOTH" (string)

    • disableThreshold - number of failed attempts after which the password of the user will be disabled (integer)
    • allowExpiredReset - number of times an expired authenticator can request reset (integer)
  • urn:hid:scim:api:idp:2.0:policy:authenticator:SecurityQuestion

    • promptsRequiredForCreation – number of questions to answer in order to create an authenticator

    • prompts – array of possible questions:

      • prompt:
        - display – the actual question
        - value – the identifier of the prompt

      • policy – constraints with which the answer to this question must comply:

        Constraint Description

        onlyNum

        Contain only numeric characters

        onlyAlpha

        Contain only alpha characters

        numOrAlpha

        Contain either numeric or alpha characters

        numAlpha

        Contain both numeric and alpha characters

        caseInsensitive

        Case-insensitive

        maxLength

        Maximum length

        minLength

        Minimum length

        notUserAttribute

        Not contain username and is not a user attribute

        dateFormat

        Date format
    • seedingType:string (enum)
  • urn:hid:scim:api:idp:2.0:policy:authenticator:Credential

    Attribute Type

    validCredentialPolicies

    string

    challengeType

    string

    disableThreshold

    int

Factor Authentication policy
LOGIN urn:hid:scim:api:idp:2.0:policy:authenticator:Password
PUSH urn:hid:scim:api:idp:2.0:policy:authenticator:PUSH
OTP urn:hid:scim:api:idp:2.0:policy:authenticator:OTP
OOB urn:hid:scim:api:idp:2.0:policy:authenticator:OOB
CODE urn:hid:scim:api:idp:2.0:policy:authenticator:OOB
PKI urn:hid:scim:api:idp:2.0:policy:authenticator:PKI
FIDO urn:hid:scim:api:idp:2.0:policy:authenticator:FIDO
LDAP urn:hid:scim:api:idp:2.0:policy:authenticator:LDAP

urn:hid:scim:api:idp:2.0:device:Type

The entity represents a Device Type.

  • It is a SCIM resource where:

    • id – the device type ID (that is, the device type code)

    • meta – lifecycle information
  • Attributes:

    Attribute Description

    name

    Device type name (String)

    notes

    Device type notes (String)

    manufacturer

    Name of the device manufacturer (String)

    maximumDevicesPerUser

    (Optional) The maximum number of this type of device that can be assigned to a user (Integer)

    If set to -1 (the default) or not present, the attribute is not used. Otherwise, the defined value is used.

    The limit is only verified when the user attempts to activate a new device of this type and an error message is displayed if they have already reached the maximum.

    If you set a maximum, it will not affect users who already have more devices than the limit (that is, it will not block authentication nor delete or modify existing devices). However, these users will only be able to activate a new device if they discard existing devices to meet the new limit. For example, if you set the limit to 2 devices, a user with 3 existing devices will need to discard 2 to activate a new device.

    copyFrom

    Code of the device type to clone when creating a new device type

    Only available for POST requests.

    readOnly

    Indicates if the resource is safeguarded. This attribute cannot be modified.

Compatible device types (that is, the ones with the “TDS provisioning V4” adapter) have the following extension:

urn:hid:scim:api:idp:2.0:User:Repository

This entity represents a user repository (LDAP or SCIM federated datasource).

A User Repository object is a SCIM resource with the following parameters:

  • id – id of the user repository (String)

  • name – name of the user repository (String)

  • type - User Repository Type (String):

    • LDAP_MS_AD – Microsoft Active Directory (AD)

    • LDAP – LDAP repository

    • SCIM_FED_AD – federated repository such as Microsoft Azure Active Directory (AAD)

Attributes for compatible repositories are:

  • LDAP:
    Attribute Description

    host

    Object describing the host configuration and has the following parameters:

    • address – hostname or IP of the server (String)
    • port – port to connect to the server (String)
    • backupAddress – hostname or IP of the backup server (String)
    • backupPort – port to connect to the backup server (String)
    • baseNodeDn – Base DN (String)
    • ldapsRootCaCertificate – certificate in base64 (only for LDAPs) (String)
    • loginCredentials – object describing credentials to connect to the server and has the following parameters:

      • userDn – User DN (String)

      • userPassword – password (can be set in CREATE and REPLACE but is NOT returned in any response) (String)

    Note: All the above parameters are mandatory for CREATE except backupAddress, backupPort and ldapsRootCaCertificate.

    mappingConfiguration

    (Not mandatory) Object describing the configuration of the LDAP and has the following parameters:

    • userClass – User Class (default value is "Person") (String)

    • ldapGroupClass – LDAP Group Class (default value is "group") (String)

    • userIdAttribute – User ID Attribute (default value is " sAMAccountName")(String)

    • groupMemberAttribute – Group Member Attribute (default value is "memberOf")(String)

    • accountStatusAttribute – Account Status Attribute (default value is "UserAccountControl") (String)

    • guidAttributeName – GUID Attribute Name (default value is "objectguid") (String)

    userTypeAssignments

    (Not mandatory) Array of objects describing a mapping between ActivID Appliance User Types and root nodes DN:

    • groupId – User Type ID in ActivID Appliance (String)

    • rootNodeDn – root node DN in the LDAP (String)

    userGroupAssignments

    (Not mandatory) Array of objects describing a mapping between ActivID Appliance User Groups and root node DN:

    • groupId – User Group ID in ActivID Appliance (String)

    • rootNodeDn – root node DN in the LDAP (String)

    roleAssignments

    (Not mandatory) Array of objects to assign ActivID Appliance Roles to users in LDAP Groups or in LDAP OU:

    • roleId – Role ID in ActivID Appliance to assign to the users in the LDAP Group or LDAP OU (String)

    • mappingType – "OU" or "GROUP" (String)

    • groupDnOrOu – DN of the OU or the Group in the LDAP (String)

    referralStrategy

    (Not mandatory) Can be "followAll", "followNone" (the default value) or "followListed" (String)

    referrals

    (Not mandatory) Array of objects describing a LDAP referral configuration:

    • address – hostname or IP of the server (String)

    • port – port to connect to the server (String)

    • loginCredentials – object describing credentials to connect to the server
  • SCIM Federated: AD
    Attribute Description

    id

    Datasource code

    name

    Name for the datasource

    adminGroupAssignment.value

    Reference to the user group code where users will be created

    provisioningAgentCredential.value

    Reference to the agent id (this is the user id of the user for whom the bearer token is configured in Microsoft Azure)

    federatedAttributes.value

    Reference to an attribute type code that is provisioned by Microsoft Azure. This attribute is protected and cannot be overwritten (only the provisioning agent is able to modify it)

    roleAssignments

    (Not mandatory) Array of objects to assign ActivID Appliance roles to users in Microsoft Azure Groups or OU:

    • roleId – Role ID in ActivID Appliance to assign to the users in the Microsoft Azure Group or OU (String)

    • mappingCriteria – ID of the Microsoft Azure "OU" or "GROUP" (String)

    userAuthenticationEndpoint

    Configuration for the authentication endpoint of the Microsoft Azure AD:

    • issuerUri – hostname or IP of the Microsoft Azure AD or ADFS OAuth 2.0 provider (String)

    • clientId – ID of the client to connect to the directory host
Note:
  • The provisioning agent must be unique to the datasource.

  • Updating the adminGroupAssignment.value will not change the administration group for the users that are already provisioned.

urn:hid:scim:api:idp:2.0:userattribute:Type

This entity represents a User Attribute Type.

Verb usage: GET(read), PUT(replace), POST(create), DELETE(delete)

<Extends SCIM Core Resource> where:

  • id – the internal id to lookup the user attribute type

  • meta – lifecycle information

  • name – name of the user attribute type

  • notes – description of the user attribute type

  • encrypted – defines if the user attribute type is encrypted. Possible values are true or false (boolean). Can be used with PUT(replace) and POST(create)

Example:

Copy
{
    "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
    "id": "CITY",
    "meta":    {
        "resourceType": "UserAttributeType", 
        "location": "https://[base-server-url]/scim/tenant/v2/User/AttributeType/CITY", "version": "1" 
    },
    "name": "City",
    "encrypted": true,
}
Note: In the example above, the user attribute type is encrypted (true). To remove the encryption, set the parameter to false:
Copy
PUT /User/AttributeType/CITY
 
{ "encrypted": false }

urn:hid:scim:api:idp:2.0:DeliveryGateway:Push

This entity represents a Push Delivery Gateway.

Verb usage: GET(read), PUT(replace), POST(create), DELETE(delete)

<Extends SCIM Core Resource> where:

  • id – identifier of the adapter

  • name – name of the adapter

  • type – code of the delivery provider (AZURE_WNS_PUSH, AZURE_APNS_PUSH and AZURE_GCM_PUSH are supported)
  • notes – description of the delivery gateway

Attributes:

Attribute Description

connectionString

URL connection string used to connect to the Microsoft® Azure® Notification Hub for your deployment

Note: For API versions earlier than 8, this parameter is not returned. For API versions 8 and later, this parameter is only returned for custom delivery adapters.
hub Name of the Microsoft Azure Notification Hub

notificationTimeToLive

(Optional) Number of seconds (TTL or lifespan) during which the push notifications are valid and can be delivered.

By default, the value is 0 which corresponds to the FCM maximum validity of four (4) weeks.

If you set a time limit, repeated delivery attempts are made (as required) until the defined limit is reached.

For further information, go to https://firebase.google.com/docs/cloud-messaging/http-server-ref

supportedOperatingSystems

List of operating systems allowed on this delivery gateway (such as "Android", "iOS", "macOS" or "WINDOWS")

Important: This parameter is mandatory and case-sensitive.
Note: If different applications are running on the same operating system, you can define a specific delivery gateway per application. You should then use a different authentication policy for each application, and map the corresponding delivery gateway to each policy.
appId

Identifier of the push mobile application (can be HID Approve or a custom application) allowed to use this delivery gateway. Can be used if there are multiple delivery gateways for the same OS as adding the appId parameter allows to matching to a specific device type (where the parameter is also defined)

messageTemplates

The title and message for credential and challenge notifications:

  • title – title of the push notification (for AZURE_WNS_PUSH and AZURE_GCM_PUSH)

  • msg – message of the push notification (for AZURE_WNS_PUSH, AZURE_APNS_PUSH and AZURE_GCM_PUSH)

By default, the message content is:

Copy
"credential":       {
    "title": "Activation",
    "msg": "Touch to activate"
},
"challenge":       {
    "title": "New Transaction",
    "msg": "Validate transaction"
}

For further information about these parameters, see Configure the Push Delivery Gateway and Adapters.

urn:hid:scim:api:idp:2.0:Application

This entity represents a Generic Application.

Verb usage: GET(read), PUT(replace), POST(create), DELETE(delete)

<Extends SCIM Core Resource> where:

  • id – ID of the generic application (String)

  • name – name of the generic application (String)

  • notes – notes of the generic application (optional)

  • type – only “Generic” is supported

Attributes for compatible repositories are:

Attribute Description

riskScoreProvider

  • value – ID of the riskScoreProvider (String)

  • failOpenBehavior – proceed to authentication step-up on the HID RMS server connection failure (Boolean)

  • rmsapplicationId – application ID defined during the integration phase (String)

  • rmschannelId – channel ID defined during the integration phase (String)

authenticationPolicies

List of authentication policies allowed for this application:

  • value – ID of the authentication policy (String)

adaptativeAuthenticationRules

  • primaryAuthnBlock – Array of "RiskScore"

  • primaryAuthnReject – Array of "RiskScore"

  • secondaryAuthnBlock - Array of "RiskScore"

  • secondaryAuthnReject – Array of "RiskScore"

  • stepUp:

    • initialPolicies - list of authentication policies:
      - value – ID of the authentication policy (String)

    • conditions – Array of "RiskScore"

    • stepUpPolicies - list of authentication policies:
      - value – ID of the authentication policy (String)

RiskScore

  • type - GlobalRiskScore, UserRiskScore, DeviceRiskScore, SessionRiskScore or ActionRiskScore

  • minValue – Integer min -1 max 1000