Authentication API
With AuthConfig, you can specify the options related to authenticating credentials. The most important option is authSchedules, which sets the authentication modes available to a device.
Config
message AuthConfig {
repeated AuthSchedule authSchedules;
bool useGlobalAPB;
GlobalAPBFailActionType globalAPBFailAction;
bool useGroupMatching;
bool usePrivateAuth;
FaceDetectionLevel faceDetectionLevel;
bool useServerMatching;
bool useFullAccess;
uint32 matchTimeout;
uint32 authTimeout;
repeated Operator operators;
}
- authSchedules
- Authentication modes available for the device.
- useGlobalAPB
- If true, ask the BioStar server whether to allow access to a user after successful authentication.
You need BioStar V2.x for global APB.
- globalAPBFailAction
- Specify what to do when the BioStar server is unreachable when useGlobalAPB is true.
- useGroupMatching
- If true, use group matching for face authentication. Valid only for FaceStation 2 and FaceLite. See AuthGroup
- usePrivateAuth
- If true, allow different authentication modes per each user. You can set the private authentication modes in User.UserSetting.
- faceDetectionLevel
- If it is not FACE_DETECTION_NONE, the device will try to detect a face after a user authenticates successfully. Valid only for BioStation A2.
- useServerMatching
- If true, defer the authentication to the BioStar server. When a user scans a fingerprint or a card, the device will send the information to the BioStar server and wait for the authentication result.
You need BioStar V2.x for server matching.
- useFullAccess
- If true, allow access to all registered users regardless of their access groups.
- matchTimeout
- Timeout in seconds for fingerprint or face matching.
- authTimeout
- Timeout in seconds for the whole authentication process.
- operators
- Up to 10 administrators can be assigned to a device.
message AuthSchedule {
AuthMode mode;
uint32 scheduleID;
}
You can set different authentication modes per different schedule. For example, you can allow AUTH_MODE_CARD_ONLY in working time, and set more secure AUTH_MODE_CARD_BIOMETRIC at night.
- mode
- Authentication mode
- scheduleID
- The ID of the schedule during which the mode is applied. Refer to Schedule.
enum AuthMode {
AUTH_MODE_BIOMETRIC_ONLY = 0;
AUTH_MODE_BIOMETRIC_PIN = 1;
AUTH_MODE_CARD_ONLY = 2;
AUTH_MODE_CARD_BIOMETRIC = 3;
AUTH_MODE_CARD_PIN = 4;
AUTH_MODE_CARD_BIOMETRIC_OR_PIN = 5;
AUTH_MODE_CARD_BIOMETRIC_PIN = 6;
AUTH_MODE_ID_BIOMETRIC = 7;
AUTH_MODE_ID_PIN = 8;
AUTH_MODE_ID_BIOMETRIC_OR_PIN = 9;
AUTH_MODE_ID_BIOMETRIC_PIN = 10;
// The below modes are only for FaceStation F2
AUTH_EXT_MODE_FACE_ONLY = 11;
AUTH_EXT_MODE_FACE_FINGERPRINT = 12;
AUTH_EXT_MODE_FACE_PIN = 13;
AUTH_EXT_MODE_FACE_FINGERPRINT_OR_PIN = 14;
AUTH_EXT_MODE_FACE_FINGERPRINT_PIN = 15;
AUTH_EXT_MODE_FINGERPRINT_ONLY = 16;
AUTH_EXT_MODE_FINGERPRINT_FACE = 17;
AUTH_EXT_MODE_FINGERPRINT_PIN = 18;
AUTH_EXT_MODE_FINGERPRINT_FACE_OR_PIN = 19;
AUTH_EXT_MODE_FINGERPRINT_FACE_PIN = 20;
AUTH_EXT_MODE_CARD_ONLY = 21;
AUTH_EXT_MODE_CARD_FACE = 22;
AUTH_EXT_MODE_CARD_FINGERPRINT = 23;
AUTH_EXT_MODE_CARD_PIN = 24;
AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT = 25;
AUTH_EXT_MODE_CARD_FACE_OR_PIN = 26;
AUTH_EXT_MODE_CARD_FINGERPRINT_OR_PIN = 27;
AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT_OR_PIN = 28;
AUTH_EXT_MODE_CARD_FACE_FINGERPRINT = 29;
AUTH_EXT_MODE_CARD_FACE_PIN = 30;
AUTH_EXT_MODE_CARD_FINGERPRINT_FACE = 31;
AUTH_EXT_MODE_CARD_FINGERPRINT_PIN = 32;
AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT_PIN = 33;
AUTH_EXT_MODE_CARD_FACE_FINGERPRINT_OR_PIN = 34;
AUTH_EXT_MODE_CARD_FINGERPRINT_FACE_OR_PIN = 35;
AUTH_EXT_MODE_ID_FACE = 36;
AUTH_EXT_MODE_ID_FINGERPRINT = 37;
AUTH_EXT_MODE_ID_PIN = 38;
AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT = 39;
AUTH_EXT_MODE_ID_FACE_OR_PIN = 40;
AUTH_EXT_MODE_ID_FINGERPRINT_OR_PIN = 41;
AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT_OR_PIN = 42;
AUTH_EXT_MODE_ID_FACE_FINGERPRINT = 43;
AUTH_EXT_MODE_ID_FACE_PIN = 44;
AUTH_EXT_MODE_ID_FINGERPRINT_FACE = 45;
AUTH_EXT_MODE_ID_FINGERPRINT_PIN = 46;
AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT_PIN = 47;
AUTH_EXT_MODE_ID_FACE_FINGERPRINT_OR_PIN = 48;
AUTH_EXT_MODE_ID_FINGERPRINT_FACE_OR_PIN = 49;
}
Authentication mode
- AUTH_MODE_BIOMETRIC_ONLY
- Fingerprint or Face
- AUTH_MODE_BIOMETRIC_PIN
- (Fingerprint or Face) + PIN
- AUTH_MODE_CARD_ONLY
- Card
- AUTH_MODE_CARD_BIOMETRIC
- Card + (Fingerprint or Face)
- AUTH_MODE_CARD_PIN
- Card + PIN
- AUTH_MODE_CARD_BIOMETRIC_OR_PIN
- Card + (Fingerprint or Face or PIN)
- AUTH_MODE_CARD_BIOMETRIC_PIN
- Card + (Fingerprint or Face) + PIN
- AUTH_MODE_ID_BIOMETRIC
- ID + (Fingerprint or Face)
- AUTH_MODE_ID_PIN
- ID + PIN
- AUTH_MODE_ID_BIOMETRIC_OR_PIN
- ID + (Fingerprint or Face or PIN)
- AUTH_MODE_ID_BIOMETRIC_PIN
- ID + (Fingerprint or Face) + PIN
Some authentication modes are available only for specific devices. For example, AUTH_MODE_ID_XXX modes are available only for the devices with key pads such as BioStation N2 and BioStation 2.
Authentication mode for FaceStation F2
Some models of FaceStation F2 provide both face and fingerprint authentication. To make full use of this multimodal function, a new set of authentication modes, AUTH_EXT_MODE_XXX, are adopted for FaceStation F2. Please note that there is no backward compatibility. You have to use these modes only for FaceStation F2.
- AUTH_EXT_MODE_FACE_ONLY
- Face
- AUTH_EXT_MODE_FACE_FINGERPRINT
- Face + Fingerprint
- AUTH_EXT_MODE_FACE_PIN
- Face + PIN
- AUTH_EXT_MODE_FACE_FINGERPRINT_OR_PIN
- Face + (Fingerprint or PIN)
- AUTH_EXT_MODE_FACE_FINGERPRINT_PIN
- Face + Fingerprint + PIN
- AUTH_EXT_MODE_FINGERPRINT_ONLY
- Fingerprint
- AUTH_EXT_MODE_FINGERPRINT_FACE
- Fingerprint + Face
- AUTH_EXT_MODE_FINGERPRINT_PIN
- Fingerprint + PIN
- AUTH_EXT_MODE_FINGERPRINT_FACE_OR_PIN
- Fingerprint + (Face or PIN)
- AUTH_EXT_MODE_FINGERPRINT_FACE_PIN
- Fingerprint + FACE + PIN
- AUTH_EXT_MODE_CARD_ONLY
- Card
- AUTH_EXT_MODE_CARD_FACE
- Card + Face
- AUTH_EXT_MODE_CARD_FINGERPRINT
- Card + Fingerprint
- AUTH_EXT_MODE_CARD_PIN
- Card + PIN
- AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT
- Card + (Face or Fingerprint)
- AUTH_EXT_MODE_CARD_FACE_OR_PIN
- Card + (Face or PIN)
- AUTH_EXT_MODE_CARD_FINGERPRINT_OR_PIN
- Card + (Fingerprint or PIN)
- AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT_OR_PIN
- Card + (Face or Fingerprint or PIN)
- AUTH_EXT_MODE_CARD_FACE_FINGERPRINT
- Card + Face + Fingerprint
- AUTH_EXT_MODE_CARD_FACE_PIN
- Card + Face + PIN
- AUTH_EXT_MODE_CARD_FINGERPRINT_FACE
- Card + Fingerprint + Face
- AUTH_EXT_MODE_CARD_FINGERPRINT_PIN
- Card + Fingerprint + PIN
- AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT_PIN
- Card + (Face or Fingerprint) + PIN
- AUTH_EXT_MODE_CARD_FACE_FINGERPRINT_OR_PIN
- Card + Face + (Fingerprint or PIN)
- AUTH_EXT_MODE_CARD_FINGERPRINT_FACE_OR_PIN
- Card + Fingerprint + (Face or PIN)
- AUTH_EXT_MODE_ID_FACE
- ID + Face
- AUTH_EXT_MODE_ID_FINGERPRINT
- ID + Fingerprint
- AUTH_EXT_MODE_ID_PIN
- ID + PIN
- AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT
- ID + (Face or Fingerprint)
- AUTH_EXT_MODE_ID_FACE_OR_PIN
- ID + (Face or PIN)
- AUTH_EXT_MODE_ID_FINGERPRINT_OR_PIN
- ID + (Fingerprint or PIN)
- AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT_OR_PIN
- ID + (Face or Fingerprint or PIN)
- AUTH_EXT_MODE_ID_FACE_FINGERPRINT
- ID + Face + Fingerprint
- AUTH_EXT_MODE_ID_FACE_PIN
- ID + Face + PIN
- AUTH_EXT_MODE_ID_FINGERPRINT_FACE
- ID + Fingerprint + Face
- AUTH_EXT_MODE_ID_FINGERPRINT_PIN
- ID + Fingerprint + PIN
- AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT_PIN
- ID + (Face or Fingerprint) + PIN
- AUTH_EXT_MODE_ID_FACE_FINGERPRINT_OR_PIN
- ID + Face + (Fingerprint or PIN)
- AUTH_EXT_MODE_ID_FINGERPRINT_FACE_OR_PIN
- ID + Fingerprint + (Face or PIN)
enum FaceDetectionLevel {
FACE_DETECTION_NONE = 0;
FACE_DETECTION_NORMAL = 1;
FACE_DETECTION_STRICT = 2;
}
- FACE_DETECTION_NONE
- Face detection is not used.
- FACE_DETECTION_NORMAL
- Normal detection level is used.
- FACE_DETECTION_STRICT
- Strict detection level is used.
Note that face detection is not face authentication. This option applies only to BioStation A2. Neither FaceStation 2 nor FaceLite uses this option.
enum GlobalAPBFailActionType {
GLOBAL_APB_FAIL_ACTION_NONE = 0;
GLOBAL_APB_FAIL_ACTION_SOFT = 1;
GLOBAL_APB_FAIL_ACTION_HARD = 2;
}
Global APB needs a BioStar server to determine whether the user is allowed to enter the door. If the device cannot connect to the server, it will decide by itself according to this parameter.
- GLOBAL_APB_FAIL_ACTION_NONE
- Allow access.
- GLOBAL_APB_FAIL_ACTION_SOFT
- Allow access, but write a log record denoting the APB violation.
- GLOBAL_APB_FAIL_ACTION_HARD
- Disallow access and write a log record denoting the APB violation.
enum OperatorLevel {
OPERATOR_LEVEL_NONE = 0;
OPERATOR_LEVEL_ADMIN = 1;
OPERATOR_LEVEL_CONFIG = 2;
OPERATOR_LEVEL_USER = 3;
}
You can assign administrators for managing devices. Each administrator has one of three operator levels, which has different privileges.
- OPERATOR_LEVEL_ADMIN
- Can do all administrative tasks on a device.
- OPERATOR_LEVEL_CONFIG
- Can change the configurations of a device.
- OPERATOR_LEVEL_USER
- Can enroll/delete users on a device.
message Operator {
string userID;
OperatorLevel level;
}
GetConfig
Get the configuration of a device.
Request |
Parameter | Type | Description |
---|---|---|
deviceID | uint32 | The ID of the device |
Response |
Parameter | Type | Description |
---|---|---|
config | AuthConfig | The authentication configuration of the device |
SetConfig
Set the configuration of a device.
Request |
Parameter | Type | Description |
---|---|---|
deviceID | uint32 | The ID of the device |
config | AuthConfig | The authentication configuration to be set to the device |
SetConfigMulti
Set the configurations of multiple devices.
Since FaceStation F2 has its own authentication modes, you can not mix them with other models.
Request |
Parameter | Type | Description |
---|---|---|
deviceIDs | uint32[] | The IDs of the devices |
config | AuthConfig | The authentication configuration to be set to the devices |