DOCSEARCHbyAlgolia
Submit Docs

Authgear Server

repository·main·Indexed 23 days ago

https://github.com/authgear/authgear-server

An open-source, extensible authentication-as-a-service platform providing turnkey solutions for consumer and enterprise authentication, including MFA, SSO, and RBAC. The server supports modern auth methods like passkeys and FIDO2, role-based access control, and extensibility via webhooks and TypeScript hooks. It includes a GraphQL Admin API and customizable UI components via AuthUI.

Tokens
238.3K
Snippets
419
Records
1K
Agent score
84%

What's inside authgear-server

  1. Overview of Authgear

    main

    Authgear is an open-source, extensible, turnkey authentication solution designed as an alternative to Auth0, Clerk, or Firebase Auth. It provides a complete suite of consumer authentication features including passwordless login, passkeys, multi-factor authentication (MFA), and enterprise SSO (OIDC, OAuth 2.0, SAML).

    Developers can use Authgear in two ways:

    1. Authgear Cloud: A managed SaaS offering.
    2. Self-hosting: Deploying the open-source authgear-server on your own infrastructure.

    Key components include:

    • Authgear Server: The core service.
    • Portal: A web interface for managing configurations and users.
    • AuthUI: Customizable UI components for login, registration, and profile settings.
    • Admin API: A GraphQL API for programmatic management of resources and authentication data.

  2. Overview of the Account Management API

    main

    The Account Management API allows you to perform management operations on behalf of an end user. To use these endpoints, you must provide an authenticated session via a cookie or the Authorization HTTP header.

    Supported operation categories include:

    • Manage identifications: List, add, update, or remove email, phone number, username, OAuth provider accounts, biometrics, and passkeys.
    • Manage authentications: List authentications and recovery codes, change passwords, and manage TOTP or OOB-OTP authenticators.
    • Manage user profile: Update standard and custom attributes, and manage profile pictures.
    • Manage sessions: List, revoke, or terminate sessions.
    • Auxiliary operations: Verify or resend OTPs.

  3. Supported Bot Protection Providers

    main

    Authgear supports several third-party bot protection providers, which can be categorized by their interaction model (challenge-based vs. non-challenge-based) and platform support.

    Challenge-based Providers

    These providers present a challenge (like a checkbox or interactive task) to the user to verify they are human.

    • Geetest v4: Challenge-based.
    • Geetest v3: Challenge-based. Note that with v3, the process must be initiated by the server.
    • hCaptcha: Supports Checkbox and Invisible flavors. Supports major mobile platforms via SDKs.
    • reCAPTCHA v2: Supports Checkbox and Invisible flavors. Supports Android, but does not support iOS.
    • Cloudflare Turnstile: Supports Managed, Non-interactive (badge), and Invisible flavors. Does not support mobile platforms natively.
    • Arkose Labs Bot Manager: Can be challenge-based and supports interactive challenges. Supports mobile via webview SDK.
    • Tencent Captcha: Challenge-based.

    Non-challenge-based Providers

    These providers typically work in the background without presenting an explicit challenge.

    • hCaptcha (Passive): A non-challenge flavor of hCaptcha.
    • reCAPTCHA v3: Not challenge-based. Supports Actions. Does not support mobile platforms out-of-the-box.

    Hybrid/Enterprise

    • reCAPTCHA Enterprise: A package containing both reCAPTCHA v2 and v3. The highest pricing tier includes mobile platform support.

  4. Understand the Usage Limits Implementation Plan

    main

    The usage limits implementation plan outlines how Authgear manages and enforces usage quotas (soft and hard limits) through configuration, runtime evaluation, and alerting. The plan is divided into several key areas:

    1. Configuration Model: Introduces a shared usage model using model.UsageName, model.UsageLimitPeriod, and model.UsageLimitAction. Configuration is split between Feature Config (usage.hooks and usage.limits) and App Config (usage.alerts and usage.limits).
    2. Runtime Evaluation: Implements a limiter that uses Redis for multi-period counting (e.g., daily and monthly) and evaluates whether a usage event crosses a threshold to trigger alerts or blocks.
    3. Alerting and Delivery: Supports two main alerting paths:
      • Webhooks: Triggering usage.alert.triggered events to specific hook URLs defined in the feature configuration.
      • Email: Sending usage alert emails based on app-level configuration.
    4. Backward Compatibility: Includes a migration path for legacy usage-limit configurations to ensure existing setups continue to function during the transition.

  5. Overview of Fraud Protection and SMS Pumping

    main
    Authgear provides fraud protection mechanisms specifically designed to mitigate SMS Pumping attacks. SMS pumping occurs when attackers exploit OTP (One-Time Password) flows to trigger massive amounts of SMS messages, leading to high costs for the service provider. The protection system monitors thresholds for SMS volume based on IP addresses, phone countries, and unverified OTP attempts to identify and mitigate these attacks.

  6. How Fraud Protection configuration modifiability works

    main

    The ability to modify Fraud Protection settings in authgear.yaml is controlled by the is_modifiable flag in the feature configuration (authgear.features.yaml).

    • If is_modifiable is false (default): The settings in authgear.yaml are ignored. The system uses hardcoded default values (Enabled: true, Action: record_only, and all 5 warning types populated).
    • If is_modifiable is true: The settings provided in authgear.yaml are applied.

    Attempts to modify the fraud_protection section in authgear.yaml when is_modifiable is false will result in a validation error during configuration updates.

  8. Understand how usage configuration merges across levels

    main

    Usage configurations can be defined at the site, plan, or project level. They follow a specific precedence and merging logic:

    1. Precedence Order (Highest to Lowest):

      • Project-level
      • Plan-level
      • Site-level

    2. Merging Rules:

      • usage.hooks: Entries are appended. Higher-precedence configs add their hooks to the list of lower-precedence hooks.
      • usage.limits.<usage_name>: The entire list for a specific usage name is overridden by higher-precedence configurations. If a project defines limits for sms, it replaces the sms limits defined at the plan or site level.

  9. Inspect Fraud Protection Decision Records

    main

    Every SMS send request (successful or not) produces a decision record. These records can be found in your logs and include details about whether the request was blocked or allowed, which warnings were triggered, and the context of the request (IP, User Agent, Geo-location, etc.).

    {
  "timestamp": "2026-02-05T11:11:11.025Z",
  "decision": "blocked",
  "action": "send_sms",
  "action_detail": {
    "recipient": "+12341234",
    "type": "verification",
  },
  "triggered_warnings": [
    "SMS__UNVERIFIED_OTPS__BY_PHONE_COUNTRY__DAILY_THRESHOLD_EXCEEDED",
    "SMS__UNVERIFIED_OTPS__BY_PHONE_COUNTRY__HOURLY_THRESHOLD_EXCEEDED",
    "SMS__UNVERIFIED_OTPS__BY_IP__DAILY_THRESHOLD_EXCEEDED",
    "SMS__UNVERIFIED_OTPS__BY_IP__HOURLY_THRESHOLD_EXCEEDED",
  ],
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X)",
  "ip_address": "203.0.113.42",
  "http_url": "https://example.authgear-apps.com/",
  "http_referer": "https://example.authgear-apps.com/login",
  "user_id": "97a0c0bb-6662-4905-9d12-e0a3ac3033d9",
  "geo_location_code": "US"
}

  10. Understand standard attributes and their types

    main

    Standard attributes follow OIDC standard claims and are all optional. They are categorized by their data format:

    • Single-line strings: name, given_name, family_name, middle_name, nickname, address.locality, address.region, address.postal_code.
    • Multi-line strings: address.formatted, address.street_address.
    • URLs: profile, picture, website.
    • Specialized types:
      • gender: Predefined values include male and female (others are possible).
      • zoneinfo: Preferred TZ database name (e.g., Asia/Hong_Kong).
      • locale: BCP47 tag (e.g., zh-HK).
      • birthdate: Must follow YYYY-MM-DD format.

  11. Choose between FoldableDiv and Accordion for expandable sections

    main

    When implementing expandable sections for settings or controls, choose a component based on whether the expansion state needs to be managed by a parent component or if it should be self-contained.

    • FoldableDiv: Use this when the expanded state must be controlled by parent state, requires reset logic, or involves cross-field interactions.
    • Accordion: Use this when the expanded state is local to the section and does not require coordination with parent components.
    | Pattern | Component | Import path | Use when |
|---|---|---|---|
| Parent-controlled expand/collapse state | `FoldableDiv` | `../../FoldableDiv` (or relative path to `portal/src/FoldableDiv.tsx`) | The expanded state needs to be controlled by parent state, reset logic, or cross-field interactions |
| Self-contained expand/collapse state | `Accordion` | `../../components/common/Accordion` | The expanded state is local to one section and does not need parent coordination |

  12. Settings Action: link_oauth

    main

    The link_oauth settings action is used to initiate a flow where a user connects a specific OAuth provider to their identity.

    Key Constraints:

    • Pure Link-Only: This action only supports connecting. It does not support disconnecting providers (a separate unlinkOAuth action is used for that).
    • Mandatory Alias: You must provide the oauthProviderAlias for the action to succeed.