DOCSEARCHbyAlgolia
Submit Docs

AusweisApp Documentation

repository·community·Indexed 20 days ago

https://github.com/governikus/ausweisapp

A client application for identity authentication using smart cards or electronic IDs (eID) on Windows and macOS. It can be used as a desktop application or as an SDK via WebSocket. Documentation includes CLI command references, network and logging configuration, contributor guidelines for the community branch, and detailed troubleshooting for ID card communication, tcToken retrieval, and certificate verification failures.

Tokens
47.2K
Snippets
132
Records
237
Agent score
71%

What's inside AusweisApp

  2. Data security and the backend-driven data model

    community

    For security and compliance reasons (as recommended by the Federal Office for Information Security), the AusweisApp does not provide personal data directly to your client application.

    How it works:

    • The AusweisApp facilitates the secure connection between the eID server and the ID card.
    • The eID server retrieves the data directly from the card.
    • Your backend receives the high-level trust data.

    Why this model is used:

    • Integrity: Since client applications run in user environments, the backend cannot verify the integrity of sensitive data if it comes directly from the client. By receiving data from the eID server, the backend ensures the source is verified.
    • Security: This approach spares your client application from the necessity of handling or encrypting highly sensitive personal data.

    Action required: If your client application requires data input from the ID card, you must retrieve this data from your backend system (e.g., the eID server) following a successful authentication.

  3. Simulator behavior for Terminal Authentication in AusweisApp 2.3.0

    community
    For developers using the integrated simulator, the behavior for Terminal Authentication has changed. The simulator now performs the Terminal Authentication process completely, rather than accepting every input automatically. This ensures a more realistic testing environment for authentication flows.

  4. Advanced Developer Settings

    community

    Once Developer Options are enabled, you can access several advanced modes:

    Test PKI (Self-authentication)

    Allows self-authentication using a test ID card instead of a genuine one.

    • Quick Toggle: Click the magnifying glass on the self-authentication start screen 10 times to enable/disable this mode without entering the main Developer Options menu.

    Internal Card Simulator

    Allows running authentication in Test PKI without any physical ID card or card reader.

    • Constraint: When the simulator is active, no other card reader can be used in stationary versions.
    • Customization: The profile data is static in the current version but can be modified via the SDK using the SET_CARD command.

    Developer Mode (Stationary only)

    Disables specific safety measures to facilitate testing with test services. Note: This cannot be used with genuine provider certificates.

    Disabled safety tests include:

    • Minimum length checks for TLS keys and ephemeral TLS keys.
    • Same-origin policy checks for the TLS certificate description URL and the TcToken URL.
    • Entwinement checks for TLS certificates with the authorization certificate.
    • HTTPS scheme enforcement for RefreshAddress and redirect URLs.

    UI and Mobile Specific Options

    • Show notifications inside the app: Displays notifications within the app (via a bell icon in the top right) instead of using system notifications. Automatically enabled when Developer Mode is active.
    • Support CAN Allowed mode (Mobile only): Enables reading the ID card by entering the CAN (Card Access Number) instead of a PIN.
    • Skip rights page (Mobile only): Skips the authorization certificate page in CAN allowed mode and prompts directly for the CAN.

  7. Understand Ausweisapp Container SDK behavior and automatic mode

    community

    The Ausweisapp SDK utilizes an automatic mode with a default simulator.

    • Automatic Mode: This mode is active by default if no WebSocket client is connected. It will be automatically disabled once a client connects and re-enabled once the client disconnects.
    • Workflow Cancellation: If a client disconnects while an active workflow is in progress, that workflow will be canceled.
    • eID Activation: Standard eID activation via localhost remains functional regardless of these modes.

    Note: The container SDK does not provide a graphical user interface (GUI).

  8. Use the Simulator for virtual card testing

    community

    The Simulator provides a virtual card for testing purposes in a test environment. It is enabled by default in all SDKs. When the simulator is active, the reader message will indicate this by having the parameter name set to Simulator.

    You can use the virtual card in two ways:

    1. Manual insertion: Use the set_card method to insert the simulated card.
    2. Automatic mode: The card can be used automatically in automatic mode.

    The default values of the virtual card are hardcoded but can be customized using the files and keys parameters within the simulator parameter, or via an environment variable when using automatic mode.

  11. Handle PAUSE messages and resume workflows

    community

    The PAUSE message (introduced in API level 3) is sent by the application to signal waiting conditions, such as a bad card position.

    Workflow Recovery: When a PAUSE message is received, the SDK halts. Once the underlying issue (the cause) is resolved, you must send the continue_cmd to acknowledge the condition and resume the workflow.

    Known Causes:

    • BadCardPosition: Denotes an unstable or lost card connection.
    {
  "msg": "PAUSE",
  "cause": "BadCardPosition"
}

  12. Understand the AusweisApp communication model

    community

    The AusweisApp operates as an additional service that facilitates a secure connection between an eID server and an ID card. Communication is structured into two distinct layers:

    1. Connection: The initial setup required to establish a link to the AusweisApp.
    2. Communication: Once connected, your application and the AusweisApp exchange JSON documents bi-directionally using a specific protocol.

    The protocol is divided into:

    • Commands: Sent by your application to control the AusweisApp.
    • Messages: Sent by the AusweisApp to provide additional information regarding commands or to emit events.

    For mobile development (Android and iOS), use the AusweisApp SDK Wrapper which provides a high-level interface.