> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/authentication/passwordless-for-web-apps/login-methods/liveid-biometric-authentication.md). # LiveID (Biometric Authentication) LiveID is a 1Kosmos signature feature that enables workforce users to enroll their face once and authenticate on any supported device - desktop, mobile, or any camera-enabled device. *** ### Overview It is designed to replace traditional password-based login and passwordless methods that rely on biometric authenticator apps or passkeys. During enrollment, LiveID captures a high-quality, forward-facing selfie suitable for biometric verification. The system automatically checks face positioning, visibility, orientation, and pose stability before capturing. No manual interaction is required, the capture is fully automatic. ### Enrolling LiveID Users enroll their LiveID selfie from **My Profile** after logging in with any already-registered authentication method (for example, password + OTP or push notification). 1. Log in to your tenant 2. Navigate to **My Profile > Login Options** 3. Under the **Setup** drop-down, click **LiveID Selfie** 4. On the **Enroll LiveID Selfie** screen, review and accept the consent notice, then click **Capture**. 5. The camera opens and automatically captures your selfie 6. When prompted, enter a **4-digit PIN** and click **Submit** {% hint style="info" %} Note: **PIN is configurable (4/6/8)** {% endhint %} A confirmation message confirms successful enrollment. The PIN is required whenever an additional authentication factor is challenged, based on the configured authentication policy. ### Configuring Adaptive Authentication for LiveID Community Administrators configure LiveID as an authentication method via **Authentication > Adaptive Authentication**. Two options are available under the Decision Actions: | Method | Description | | ------------------------------------- | ---------------------------------------------------------------------------------- | | **LiveID Selfie** | Prompts the user to provide a selfie on a camera-enabled device | | **LiveID Selfie & Push Notification** | Uses facial biometric combined with push notification approval via the 1Kosmos app | ### Logging in with LiveID 1. Open the tenant URL 2. Navigate to the **LiveID Selfie** tab 3. Read the on-screen instructions, the camera opens automatically 4. Present your face; the system captures the selfie automatically once it detects a clear, stable image 5. Enter your **4-digit PIN** when prompted *(PIN length is configurable by the admin to contain 4, 6 or 8 digits)* 6. Upon successful authentication, you are logged into the tenant ### Best Practices * The image resolution should be at least **1080p** (1920×1080 px) * Use a well-lit environment to ensure clear image quality * Maintain a steady, forward-facing pose for at least 600ms * Keep your face within the on-screen circular frame * Avoid tilting your head left, right, or sideways * Avoid wearing headwear or face coverings that block facial features * Small, natural head movements are allowed and will not reset the capture * Follow the real-time guidance messages displayed during capture ### Troubleshoot This section explains what happens during a LiveID facial login, what errors and system events a user's failed attempt can generate, and what helpdesk staff should check or tell the user at each stage. **How LiveID Login Works** A login attempt moves through up to five stages, in order. If a stage fails, the process stops there, and the user sees an error. When a user contacts the helpdesk, the fastest way to diagnose the issue is to pull the most recent E\_LOGIN\_FAILED event for their session and check which stage it came from — the sections below tell you what each one means. {% stepper %} {% step %} #### **Stage 1: Selfie Capture** This stage never generates events, so if a user is stuck here, you're relying entirely on what they tell you or what's on their screen. There's no failure at this stage — only guidance messages while the app waits for a good image, and camera-access errors that block capture entirely. **Positioning guidance (normal, self-resolving)** These messages simply guide the user to reposition. They aren't errors — no action needed unless the user reports being stuck on one indefinitely (in which case, suspect a lighting or camera hardware issue). **Camera access errors (need helpdesk action)** Camera access is blocked. Enable camera permissions for this app, or contact your helpdesk if the issue persists {% endstep %} {% step %} #### **Stage 2: Security and Anti-Spoofing Check** Once the system captures an image, it checks it for signs of a spoofed or fraudulent attempt. A failure here always shows the same UI message, but the underlying event tells you why it was flagged. UI error shown to user: "**Suspicious Activity Detected**" Event generated: E\_LOGIN\_FAILED — check the event's recommendations field for the cause. {% endstep %} {% step %} #### **Stage 3: Liveness Check** If the anti-spoofing check passes, the system verifies the image shows a live person. Many of the causes below are the same conditions the Selfie Capture stage tries to prevent — so a failure here often means the user rushed through or ignored the on-screen guidance. UI error shown to user: "**Liveness check failed**" Event generated: E\_LOGIN\_FAILED — check the event's failureDetail field for the cause. {% endstep %} {% step %} #### **Stage 4: Face Compare** After liveness passes, the system tries to match the face to an enrolled identity. The error and recommended action depend on whether the user logged in with a username or without one. Event generated: E\_LOGIN\_FAILED — check the event's reason field. {% endstep %} {% step %} #### **Stage 5: User PIN Verification (Optional)** If PIN verification is enabled as a backup/secondary step, this is the last stage. Failure here simply means the entered PIN was wrong. UI error shown to user: "**Incorrect PIN**" **Event generated**: E\_LOGIN\_FAILED with reason: "Incorrect PIN" **What to do**: Confirm the user is entering the correct PIN. If they've forgotten it, direct them to your organization's PIN reset process. {% endstep %} {% endstepper %} **Quick Reference: Diagnosing from the Event Log** When a user reports a failed login, pull their E\_LOGIN\_FAILED event and check which data field is populated — it tells you which stage failed: If there's no E\_LOGIN\_FAILED event at all, the user likely never got past Stage 1 (Selfie Capture/camera access) — ask them what was on screen when the attempt stopped. **Stage-by-stage summary** The table below summarizes what each stage does and whether it leaves an event trail to check.
# Stage What it does Generates events?
1 Selfie Capture Guides the user to position their face for the camera No
2 Security & Anti-Spoofing Check Screens the image for signs of spoofing (fake video, virtual camera, etc.) Yes
3 Liveness Check Confirms the image is a real, live person Yes
4 Face Compare Matches the face to an enrolled user Yes
5 User PIN Verification (optional) Validates a backup PIN, if enabled Yes
**Positioning guidance messages** These are the on-screen prompts users see while the app waits for a good image. | Message shown to user | What it means | | -------------------------------- | -------------------------------------------- | | "Loading face detector..." | App is initializing | | "Move closer" | Face is too small/far from camera | | "Move back a little" | Face is too close to camera | | "Center your face in the circle" | Face is outside the focus area | | "Keep your head level" | User is facing the camera but head is tilted | | "Face the camera directly" | User isn't facing the camera | | "Please hold the position" | All conditions met — about to capture | **Camera access errors** If capture never starts, one of these messages is likely on screen — check the cause and share the fix with the user. | Message shown to user | Likely cause | What to tell the user | | ------------------------------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | "Camera permission denied" | Browser/app camera permission was denied | Have them enable camera access in browser/OS privacy settings, then reload | | "No camera found" | Device has no camera, or it's disabled/disconnected | Confirm the device has a working camera; check Device Manager (Windows) or System Settings for a disabled camera | | "Camera is already in use" | Another app (Zoom, Teams, etc.) is holding the camera | Ask the user to close other apps using the camera, then retry | | "Camera access blocked (try non-incognito mode)" | Browser is blocking camera access, often due to incognito/private mode | Ask the user to retry in a normal (non-private) browser window | **Anti-spoofing failure causes** Check the event's recommendations field against this table to identify why the attempt was flagged. | Cause (in event data) | What it means | What to do | | ------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Unknown exception | An unexpected internal error occurred during detection | No specific user action — treat as a system-side issue; escalate if it recurs | | Virtual camera detected | The video source looks like a virtual camera or screen-capture feed rather than a physical camera | Ask the user to check that their physical webcam (not a virtual/software camera) is selected as the video source | | Video injection detected | The video stream looks synthetic or pre-recorded rather than live | Ask the user whether they are replaying a recorded video instead of using a live camera feed | | Video anomalies | The video shows unusual patterns or is unusually static/flat | Suggest the user retry with better lighting and normal camera movement; escalate for manual review if it persists | **Liveness check failure details** Match the event's failureDetail value to this table for the likely cause and recommended action. | failureDetail value | What it means | Recommended action | | --------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | "Face not found" | No face detected in the image | Ask the user to retry, ensuring their face is clearly visible | | "Relative face size is too small" | Face is too far from the camera | Ask the user to move closer | | "Facial out-of-plane rotation angle is extremely large" | Head was tilted too far | Ask the user to keep their head level and face the camera directly | | "Absolute face size is too small" | Camera resolution/face pixel density too low | Ask the user to move closer and ensure good lighting | | "Face is too close to one or more borders" | Face was too near the edge of the frame | Ask the user to center their face in the capture area | | "Face is cropped" | Only part of the face was captured | Ask the user to retry, keeping their full face in frame | | "Face is occluded" | Something is covering part of the face (mask, hand, hair, etc.) | Ask the user to remove anything covering their face and retry | | "Too many faces detected" | More than one face appeared in frame | Ask the user to try authenticating in a less crowded location | | "Image too small to be processed" | Captured image is below 480p resolution | Check the user's camera meets minimum resolution requirements | | "Liveness score below configured success threshold" | Liveness confidence was too low (image queued for Stage 2 manual review) | No immediate user action — inform them the attempt is under review | | "Poor image quality. Retry login." | Image quality was too low (image queued for Stage 2 manual review) | Ask the user to retry in a well-lit location | | "Both liveness and quality score below success threshold" | Both checks failed (image queued for Stage 2 manual review) | Possible spoofing — check whether the user tried to present a recorded video via smartphone | **Face Compare failure scenarios** | Login Flow | Condition | UI Message | Event Reason Failure | What to do | | ---------------- | ---------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Without username | Face isn't enrolled at all | "No account found" / "Face Not Recognized" | "No account found" / "Face Not Recognized" | Confirm the user has completed facial enrollment; if not, direct them to enroll | | Without username | Face matched an image, but that image isn't linked to any user account | "Your selfie has not been enrolled" | "User not found" | Confirm the user's enrollment is fully linked to their account; may need re-enrollment | | With username | Captured face doesn't match the enrolled face for that username | "Face does not match" | "Selfie does not match the selected user" | Confirm the user is entering the correct username; if repeated, check whether their enrolled photo is outdated (e.g., major appearance change) and may need re-enrollment | **Diagnosing from the Event Log** | Event field present | Stage that failed | Go to section | | ------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------- | | recommendations | Security & Anti-Spoofing Check | [Stage 2](#stage-2-security-and-anti-spoofing-check) | | failureDetail | Liveness Check | [Stage 3](#stage-3-liveness-check) | | reason ("No account found," "User not found," or "Selfie does not match the selected user") | Face Compare | [Stage 4](#stage-4-face-compare) | | reason ("Incorrect PIN") | User PIN Verification | [Stage 5](#stage-5-user-pin-verification-optional) | #### Enrollment Failure Reasons With the new **E\_LIVEID\_ENROLL\_FAILED** event, triggered on a LiveID Selfie enrollment failure, the table below breaks down each failure reason and the details it captures. | Failure Reason | Details Captured | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Liveness failed (when liveness score is part of registration scope) | Liveness score, quality score, reason for low liveness/quality score | | Suspicious activity detected | Overall confidence score, camera name, reason for high-risk confidence (e.g. virtual camera, synthetic video, flagged camera name) | | Incorrect PIN (when a PIN already exists) | Failure reason: PIN mismatch | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.1kosmos.com/authentication/passwordless-for-web-apps/login-methods/liveid-biometric-authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.