Schema Extensions

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

Note: To use the version-specific parameters/attributes, you must add api-version=N to the query parameter (that is, first digit only, for example, POST /scim/{tenant}/v2/Users?api-version=10).

The API version supported by HID Authentication Service is 10.3.0.

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

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:AuditRecords

This entity represents an audit record in the HID Authentication Service audit log.

  • <Extends EntityBase> with dedicated audit parameter codes where:

    • devialSerialNumber is audited with existing parameter "DSN"

    • device ID is audited with existing parameter "DID"

    • credential code is audited with existing parameter "CCO"

    • organization ID is audited with new parameter "OID"

    • device issuance request ID is audited with new parameter "DIR"

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
  • lastFlagTransactionDate

  • consecutiveFlagTransaction

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: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: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

  • Attributes:

    • name:string

urn:hid:scim:api:idp:2.0:ServiceProviderConfig

This entity allows retrieving the service provider configuration metadata.

<Extends SCIM Core Resource> where:

  • patch:

    • supported - can be true or false

  • bulk:

    • supported - can be true or false

    • maxOperations

    • maxPayloadSize

  • filter:

    • supported - can be true or false

    • maxResults

  • changePassword:

    • supported - can be true or false

  • sort:

    • supported - can be true or false

  • etag:

    • supported - can be true or false

  • authenticationSchemes:

    • name - name of the schema (for example, oauthbearertoken)

    • description - description of the schema (for example, OAuth Bearer Token)

    • specUrl - URL for the schema specification

    • primary - status of the schema, can be true or false

urn:hid:scim:api:idp:2.0:Tasks

This entity represents background tasks.

<Extends SCIM Core Resource> where:

  • id - the internal ID to lookup the task

  • type - type of the task:

    • ATTRIBUTE_ENC

    • ATTRIBUTE_DEC

    • KEY_RENOWAL

    • APPROVE_NOTIFICATION

  • payload - task-specific details

  • status - status of the task:

    • PENDING

    • INPROGRESS

    • DONE

    • FAILED

    • CANCELED

  • creationDate - date on which the task was created

  • lastUpdate - date of the last update for the tasks

  • domain - domain on which the task applies. Can be "all" which creates a task for each domain