Schema Extensions

This section details the expected schemas extensions (HID JSON base objects).

Note: The API version supported by ActivID AS 8.5 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:Attribute

  • name - name of the attribute (String)

  • value - value of the attribute (String)

  • type - TYPE enumeration from set (STRING, DATE, INT, LONG, BOOLEAN)

  • readOnly - Boolean

urn:hid:scim:api:idp:2.0:EntityStatus

  • status - status of the entity (String)

  • active - boolean

  • startDate - start date for the entity (Date)

  • expiryDate - expiry date for the entity (Date)

urn:hid:scim:api:idp:2.0:EntityBase

<Extends SCIM Core Resource> where:

  • type - type of the entity (String)

  • status: status of the entity (EntityStatus)

  • attributes - attributes of the entity (Attribute[])

  • owner - owner of the entity (MemberRef)

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

This entity represents an authenticator binding a user to an authentication policy and credential/device.

  • <Extends EntityBase> where:

    • id - the internal ID for the resource

    • externalid – user alias for authentication [optional]

    • meta – lifecycle information

    • status - status of the entity (EntityStatus)

    • owner – the user that owns the authenticator

Attributes:

Attribute Description

statistics

The authentication statistics. Can contain:

  • maximumNumberOfUsages

  • consecutiveFailed

  • consecutiveSuccess

  • totalFailed

  • totalSuccess

  • lastSuccessfulDate

  • lastUnsuccessfulDate

  • lastSuccessfulChannel

  • lastUnsuccessfulChannel

  • challengeCount

policy

Details of the authenticator policy for the authenticator (immutable)

lastSuccessfulDevice

Details of the last device used in a successful authentication by the user, contains:

  • type - type of the last successfully used device

  • value - ID of the last successfully used device

The authenticator has the following mutually exclusive extensions:

  • urn:hid:scim:api:idp:2.0:Password – password extension

    • username (immutable)

    • password (write-only, never returned)

  • urn:hid:scim:api:idp:2.0:SecurityQuestion – security question extension

    • prompts – array of prompts:

      • prompt:
        • display – the actual question (read-only)
        • value – the ID of the question (read/write)
      • answer – the answer to the question (write-only)
      • policy - the constraints (such as case-sensitive and length) with which the answe must comply

    • promptsRequiredForCreation -

    • seedingType -

  • urn:hid:scim:api:idp:2.0:Action – action extension

    • action – action to proceed on given authenticator. Can be:

      • RESET

      • DELIVER-CHALLENGE

      • DEVICE-CHALLENGE

      • USER-CHALLENGE

      • REGISTER-OOB

      • UNREGISTER-OOB

      • attributes – array of attributes where each attribute is a name/value pair containing:

        Copy 
        {
            "name": "<static value>",
            "value": "<value of attribute such as the code or id>"
        }
        Action Attributes
        DELIVER-CHALLENGE
        • USER.EXTERNALID – user external ID
        • DEVICETYPE – device type
        • DEVICE.EXTERNALID – device serial number
        • DEVICE.ID – the internal device ID (long)
        • CHANNEL – channel code
        DEVICE-CHALLENGE
        • DEVICETYPE – device type
        • DEVICE.EXTERNALID – device serial number
        • DEVICE.ID – the internal device ID (long)
        • CHANNEL – channel code
        USER-CHALLENGE
        • USER.EXTERNALID – user external ID
        • CHANNEL – channel code
        REGISTER-OOB OOB_DEVICETYPE_CODE - code of device type that is compatible with credential type bound to the authentication type
        UNREGISTER-OOB USER.EXTERNALID – user external ID

urn:hid:scim:api:idp:2.0:Credential

This entity represents a credential:

  • <Extends EntityBase> where:

  • attributes: Attributes[] – generic attribute the credentials can hold

urn:hid:scim:api:idp:2.0:Device

This entity represents a device and linked credentials.

  • <Extends EntityBase> where:

    • owner – the user that owns the device

    • type – device type

    • externalid – device serial number [optional]

    • id – the internal device ID to look up the device

    • meta – lifecycle information

    • friendlyName – device friendly name [optional]

  • children : MemberRef[] – these are the linked credentials

  • urn:hid:scim:api:idp:2.0:Action – action extension:

    • action – action to proceed on given device. Can be SYNCH-COUNTER: to resynchronize a device with a new counter value.

    • attributes – array of attributes:

      • COUNTER: new counter value

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

Important: This API is deprecated. Use the updated /configuration/authenticator API instead.

This entity represents an authenticator policy. The policy has three mutually exclusive extensions:

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

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

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

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

  • It is a SCIM resource where:

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

    • externalId – not configurable

    • meta – lifecycle information

  • Attributes:

    Attribute Type

    allowExpiredReset

    int

    baseAuthenticatorPolicy

    		 MemberRef

    challengeDisableThreshold

    		 int

    defaultExpiryThreshold

    		 int

    challengeTimeoutPeriod

    		 int

    defaultValidDaysAdd

    		 int

    defaultValidDaysEdit

    		 int

    directAuthenticatorPolicy

    		 MemberRef

    failureDisplay

    		 string

    name

    		 string

    notes

    		 string

    requiredAuthentication

    		 string

    sessionTimeout

    		 long

    sessionValidPeriod

    		 long

    validChannelCodes

    		 string[]

    onlyIndirect

    		 boolean

The policy has the following mutually exclusive extensions:

  • 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

      numAlpha

      "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
      notEnglish "true" or "false" Must not be an English word

      minNum

      "true" or "false"

      Must contain at least one numeric character

      minLow 

      "true" or "false"

      Must contain at least one lowercase character

      minUp 

      "true" or "false"

      Must contain at least one uppercase character

      minSpecial 

      "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)

      blacklist

      "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

      numAlpha

      		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)

  • 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

urn:hid:scim:api:idp:2.0:Organization

This entity represents an organization.

<Extends SCIM Core Resource> where:

  • id – the internal organization ID to lookup the organization

  • externalid – the external organization ID

  • type – organization type (dataset)

  • initialPassword – used to manage the organization

  • organizationDelegation – the organization to which delegation is given

  • organizationBranding – the organization branding for HID Approve™ and the Authentication Portal

urn:hid:scim:api:idp:2.0:OrganizationDelegation

This entity represents an organization delegation of a restricted subset of roles.

<Extends SCIM Core Resource> where:

  • id – the internal organization ID to look up the organization

  • externalid – the external organization ID

  • idProof – the certificate of the organization to which delegation is given

  • delegatedRoles – list of roles that are delegated to the proxy organization

urn:hid:scim:api:idp:2.0:OrganizationBranding

This entity represents an organization branding.

  • hidApproveCustoFiles – array of OrganizationCustomizationFile for HID Approve

  • authPortalCustoFile – an OrganizationCustomizationFile for the Authentication Portal

An OrganizationCustomizationFile has the following parameters:

  • filename – filename of the customization file

  • fileAsBase64 – base64 encoded file

urn:hid:scim:api:idp:2.0:PermissionSet

This entity represents a permission set.

  • <Extends SCIM Core Resource> where:

    • id – the internal ID to lookup the permission set

    • meta – lifecycle information

    • name – name of the permission set

    • resourceType – can be “GROUP” or “ASSET”

  • urn:hid:scim:api:idp:2.0:PermissionSetItem[]– list of permissions:

    • id – ID of the permission

    • parameter – can be used to define roles for relevant permissions.

urn:hid:scim:api:idp:2.0:Provision

This entity represents a device issuance request.

<Extends EntityBase> where:

  • owner – is the user that owns the device provision

  • deviceType – device  type

  • id – the internal device provision ID to look up the device provision

  • status – status of the device provision, can have the following values:

    • IN_ISSUANCE

    • PROCESSED

    • REG_PROCESS

    • UNPROCESSED

  • meta – lifecycle information

urn:hid:scim:api:idp:2.0:PseudonymizationToken

This entity represents pseudonymization tokens in exported audit logs.

<Extends SCIM Core Resource> where:

  • token – the pseudonymization token

  • value – the clear value

  • ownerId – owner ID of this token

  • ownerExtId – owner external ID of this token

urn:hid:scim:api:idp:2.0:Role

This entity represents a list of roles:

  • <Extends SCIM Core Resource> where:

    • id – the internal role ID to lookup the role

    • meta – lifecycle information

    • name – name of the role

    • description – a short summary of the role

    • updatePermissionSet – defines if a configured permission set should be updated when creating a role

  • Attributes:

    • name:string