Schema Extensions
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 authenticator policy extensions:
Attribute Type Description challengeDisableThreshold
int
The maximum number of challenges (that is, "push action or validation request") that can be issued for validation without submission of a valid response from HID Approve.
Once this threshold is reached, the count must be reset before a challenge will be issued.
Default value is 8.
-1 indicates there is no threshold.
challengeTimeoutPeriod
int
Validity (in seconds) of the challenge after which the transaction can no longer be signed (where -1 is no expiration)
defaultExpiryThreshold
int
Maximum number of times an authenticator can be used successfully (where -1 is no limit)
defaultValidDaysAdd
int
Number of days an authenticator of this type is valid after creation (where -1 is never expires)
Note: If you set this parameter to -1, defaultValidDaysEdit must also be set to -1.defaultValidDaysEdit
int
Number of days an authenticator of this type is valid after update (for example, if a password is changed) (where -1 is never expires)
Note: If you set this parameter to -1, defaultValidDaysAdd must also be set to -1.disableThreshold
int
Number of successive failed authentication attempts before the authenticator is disabled
disabledTimeReset
int
Period after which a blocked authenticator will be automatically unblocked (where -1 is never)
levelOfAssurance
string
Used for OpenID ACR criteria, this value is a contract with the calling application
name
string
Authenticator policy name
notes
string
Authenticator policy notes
sessionTimeout
int long
Timeout (in milliseconds) of the session if it is not used
sessionValidPeriod
int long
Duration of the session (in milliseconds) even if used
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)
characterRange
"Nothing" or the required range
Must in the defined range
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
characterRange
"Nothing" or the required range
- 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)
-
For further details about the authenticator policy extensions, see the SCIM API Reference.
-
urn:hid:scim:api:idp:2.0:policy:authenticator:Card
Attribute Type validCredentialPolicies
string
Authentication factors to authentication policy mapping:
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 |
CARD | urn:hid:scim:api:idp:2.0:policy:authenticator:CARD |
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)
defaultCredentialTypeCode
Code of the default credential type when importing devices (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.
allowedCredentialTypes
(Optional) Comma-separated list of codes of the credential types allowed for the device type ([String])
Possible values are:
- any - all credential types are allowed
- Comma-separated list of codes ["CT code 1", "CT code 2"]
If not present, the attribute is not used.
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 have the following extension
- urn:hid:scim:api:idp:2.0:device:type:FIDO
Attribute Description deviceFormFactor
Form factor of the device (String)
Possible value - urn:hid:scim:api:idp:2.0:device:type:FIDO:Generic
challengeLength
Length of the challenge that the device will issue (Integer)
- urn:hid:scim:api:idp:2.0:device:type:Virtual
Attribute Description deviceFormFactor
Form factor of the device (String)
Possible values:
- urn:hid:scim:api:idp:2.0:device:type:Virtual
- urn:hid:scim:api:idp:2.0:device:type:Virtual:JWT
- urn:hid:scim:api:idp:2.0:device:type:Virtual:OOB
- urn:hid:scim:api:idp:2.0:device:type:Virtual:PKI
- urn:hid:scim:api:idp:2.0:device:type:Virtual:PKIMatch
- urn:hid:scim:api:idp:2.0:device:type:Virtual:PIN
- urn:hid:scim:api:idp:2.0:device:type:Virtual:PKIMatch
- urn:hid:scim:api:idp:2.0:device:type:Virtual:SMSOOB
- urn:hid:scim:api:idp:2.0:device:type:Card
- urn:hid:scim:api:idp:2.0:device:type:EMVCard
Attribute Description deviceFormFactor
Form factor of the device (String)
Possible value - urn:hid:scim:api:idp:2.0:device:type:EMVCard
challengeLength
Length of the challenge that the device will issue (Integer)
- urn:hid:scim:api:idp:2.0:device:type:Token
- urn:hid:scim:api:idp:2.0:device:type:CMSCard
Attribute Description deviceFormFactor
Form factor of the device (String)
Possible values - urn:hid:scim:api:idp:2.0:device:type:CMSCard
challengeLength
Length of the challenge that the device will issue (Integer)
supportedAuthenticationMethod
Supported authentication methods (String)
Possible values:
- SYNC
- ASYNC
- BOTH
syncAuthenticationCodeLength
Length of the synchronous OTP the device will generate (Integer)
asyncAuthenticationCodeLength
Length of the asynchronous OTP the device will generate (Integer)
supportsUnlock
Indicates if the device has a lock/unlock function (Boolean)
unlockChallengeLength
Length of an unlock challenge (Integer)
supportsSynch
Types of resynchronization supported by the device (String)
Possible values:
- NO_SUPPORT
- ONLY_AUTOMATIC
- ONLY_MANUAL
- SUPPORT_ALL
synchronisationBase
Base resynchronization type of the device (String)
Possible values:
- NEITHER
- COUNTER
- CLOCK
- BOTH
autoSynchEventCounter
Default offset to use when autosynchronising the device via the event counter (Integer)
Only used if synchronisationBase is either BOTH or COUNTER
autoSynchStartTime
Synchronization time offset start (Integer)
Only used if synchronisationBase is either BOTH or CLOCK
autoSynchEndTime
Synchronization time offset end (Integer)
Only used if synchronisationBase is either BOTH or CLOCK
supportsSignatureVerification
Indicates that devices of this type support transaction data signing (Boolean)
- urn:hid:scim:api:idp:2.0:device:type:Push
For further details about the configuring the push-based solution, see Advanced Configuration for Push Authentication.
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 HID Authentication Service User Types and root nodes DN:
-
groupId – User Type ID in HID Authentication Service (String)
- rootNodeDn – root node DN in the LDAP (String)
userGroupAssignments
(Not mandatory) Array of objects describing a mapping between HID Authentication Service User Groups and root node DN:
-
groupId – User Group ID in HID Authentication Service (String)
- rootNodeDn – root node DN in the LDAP (String)
roleAssignments
(Not mandatory) Array of objects to assign HID Authentication Service Roles to users in LDAP Groups or in LDAP OU:
-
roleId – Role ID in HID Authentication Service 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 HID Authentication Service roles to users in Microsoft Azure Groups or OU:
-
roleId – Role ID in HID Authentication Service 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
-
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)
-
predefined - specifies if the user attribute type is standard (predefined) or custom
This property is read-only.
-
multiValued – defines if the user attribute can contain multiple values (in an array). Possible values are true or false (boolean). Can be used with PUT(replace) and POST(create)
This property can only be true for custom user attribute types (for predefined types or if not specified, the value is false).
Note: If multiValued was set to true , it cannot be reverted to 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:
By default, the message content is: Copy
|
urn:hid:scim:api:idp:2.0:RiskScoreProvider
This entity represents a Risk Score Provider.
Verb usage: GET(read), PUT(replace), POST(create), DELETE(delete)
<Extends SCIM Core Resource> where:
-
id – id of the adapter
-
name – name of the adapter
-
externalId – code of the adapter (in this release, only RMS_CFG_TM for HID RMS is supported)
-
url – the Risk Score Provider URL
-
connectionTimeOut – timeout for establishing connection
-
credentials – credentials to connect to the Risk Score Provider:
-
apiKey
-
user
- password
-
For further information about these parameters, refer to the HID Risk Management Solution Integration Guide.
urn:hid:scim:api:idp:2.0:Application/CardAuth
This entity represents a Card Authentication Application.
Verb usage: GET(read), POST(create), DELETE(delete)
<Extends SCIM Core Resource> where:
-
id – ID of the application (String)
-
name – name of the application (String)
-
notes – notes of the application (optional)
-
type – if the application is not used as a default card application (for example, Contactless), the value must match exactly the card nickname
The authentication type is bound to the:
-
Channel - CH_EXTRAPP
-
User type - UT_EMP
Attributes for compatible applications are:
Attribute | Description |
---|---|
deviceType |
|
credentialType |
|
authenticatorPolicy |
|
urn:hid:scim:api:idp:2.0:Application/Generic
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 applications are:
Attribute | Description |
---|---|
riskScoreProvider |
|
authenticationPolicies |
List of authentication policies allowed for this application:
|
adaptativeAuthenticationRules |
|
RiskScore |
|
urn:hid:scim:api:idp:2.0:Customization
This entity represents a customization (workflow, theme or keystore).
A Customization object is a SCIM resource with the following parameters:
-
id – ID of the customization (String)
-
payload – payload specific for the customization
The JSON payload content is validated using the following schema definitions:
-
IdP Workflows schema validator - workflowSchema.json
-
IdP Themes schema validator - themeSchema.json
For a keystore customization, the payload contains the truststore type and keystore file.
urn:hid:scim:api:idp:2.0:credential:Type
The entity represents a Credential Type.
-
It is a SCIM resource where:
-
id – the credential type ID (that is, the credential type code)
- meta – lifecycle information
-
-
Attributes:
Attribute Description name
Credential type name (String)
notes
Credential type notes (String)
copyFrom
Code of the credential type to clone when creating a new credential type
Only available for POST requests.
readOnly
Indicates if the resource is safeguarded. This attribute cannot be modified.
Compatible device types have the following extensions:
-
urn:hid:scim:api:idp:2.0:credential:type:OOBACode
-
urn:hid:scim:api:idp:2.0:credential:type:OOB
-
urn:hid:scim:api:idp:2.0:credential:type:FIDO
-
urn:hid:scim:api:idp:2.0:credential:type:PKIMATCH
-
urn:hid:scim:api:idp:2.0:credential:type:PKICert
-
urn:hid:scim:api:idp:2.0:credential:type:PushPKI
-
urn:hid:scim:api:idp:2.0:credential:type:PushSMK
-
urn:hid:scim:api:idp:2.0:credential:type:PushOATH
-
urn:hid:scim:api:idp:2.0:credential:type:PushOOB
-
urn:hid:scim:api:idp:2.0:credential:type:SDB
-
urn:hid:scim:api:idp:2.0:credential:type:OATH
-
urn:hid:scim:api:idp:2.0:credential:type:CARD
For further details about the extensions, see the SCIM API Reference.