AshAuthentication.BankID.Plug (ash_authentication_bankid v0.1.3)

View Source

Plug handlers for BankID HTTP endpoints.

This module provides handlers for the three BankID phases:

  • initiate/2 - Starts a BankID authentication and returns QR data
  • poll/2 - Checks the status of an ongoing authentication
  • sign_in/2 - Completes the authentication and returns a user with JWT token

Follows the pattern from MagicLink.Plug and OAuth2.Plug.

Summary

Functions

initiate(conn, strategy)

Initiate a BankID authentication order.

poll(conn, strategy)

Poll the status of a BankID order.

renew(conn, strategy)

Renew a BankID order by creating a new one.

sign_in(conn, strategy)

Complete BankID authentication and sign in the user.

Functions

initiate(conn, strategy)

@spec initiate(Plug.Conn.t(), AshAuthentication.BankID.t()) :: Plug.Conn.t()

Initiate a BankID authentication order.

This endpoint:

  1. Generates a session ID and stores it in the Phoenix session
  2. Calls the BankID API to start authentication
  3. Creates an order record in the order resource
  4. Returns QR tokens (but NOT the secret!)

Expected response

Returns {:ok, data} with:

  • order_ref - Reference for polling and completion
  • qr_start_token - Public token for QR code generation
  • auto_start_token - Token for same-device flow
  • start_t - Timestamp for QR code generation

poll(conn, strategy)

@spec poll(Plug.Conn.t(), AshAuthentication.BankID.t()) :: Plug.Conn.t()

Poll the status of a BankID order.

This endpoint:

  1. Gets the order from the database
  2. Calls BankID.collect to check status
  3. Updates the order in the database
  4. Returns the current status

This does NOT complete the authentication - it just returns status info.

Parameters

Expects order_ref in the query params.

Response

Returns {:ok, data} with:

  • status - "pending", "complete", or "failed"
  • hint_code - BankID hint code for user messaging

renew(conn, strategy)

@spec renew(Plug.Conn.t(), AshAuthentication.BankID.t()) :: Plug.Conn.t()

Renew a BankID order by creating a new one.

This endpoint:

  1. Validates the current order exists and matches session
  2. Creates a new BankID order with same session_id and ip_address
  3. Cancels the old order via BankID.cancel
  4. Deletes the old order from database
  5. Returns new order data (qr_start_token, auto_start_token, start_t)

Parameters

Expects order_ref in params (the current order to renew).

Response

Returns {:ok, data} with new order_ref, qr_start_token, auto_start_token, start_t

sign_in(conn, strategy)

@spec sign_in(Plug.Conn.t(), AshAuthentication.BankID.t()) :: Plug.Conn.t()

Complete BankID authentication and sign in the user.

This endpoint:

  1. Validates the order is complete
  2. Calls the sign_in action which handles user creation/update
  3. Returns the user with JWT token in metadata

Parameters

Expects order_ref in the params.

Response

Returns {:ok, user} with JWT token in metadata.