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