doc/developer/TokenArchitecture

Version 9 (modified by benoitg, 11 years ago)

Update

Contributor(s): Benoit Grégoire, last modified: 2008-06-05

Token, General model

Currently, connection tokens are very weak entities, directly stored in the connection table. Many stakeholders would like to add features to connections (time limit, persistent token, etc.) to support the different WirelessCommunityModels. To do this without shooting ourselves in the foot, we need a data model that can solve the general problem of connection handling and re-use, not just a specific degenerate case of it (such as selling pre-paid time).

What follows is a first draft at doing so.

Data model

token_templates

  • token_template_id
  • token_template_network (Note: Server-wide tokens aren't supported, but the code will look up the tokens of networks you peer with)
  • token_template_creation_date
  • token_max_incoming_bytes Ex: Allows capping bandwidth
  • token_max_outgoing_bytes Ex: Allows capping bandwidth
  • token_max_total_data Ex: Allows capping bandwidth
  • token_max_connection_duration: Ex: Allows limiting the length of a single connection
  • token_max_usage_duration: Ex: Allows selling access by the hour (counting only when in use)
  • token_max_wall_clock_duration: Ex: Allows selling daily, weekly or monthly passes (starting the count as soon as the token is first used)
  • token_max_age: Ex: Allow setting a maximum time before expiration (starting the count as soon as the token is issued)
  • token_is_reusable: Is the created token reusable until it expires? (normally, yes)

tokens_template_valid_nodes (Unfortunately, for hotels selling 24h access to their clients, we have to consider that their network may consist of more than one node. If the token has no entry in this table, it's considered valid everywhere on the Network (and it's peers))

  • token_template_id
  • token_valid_at_node

token_lots

  • token_lot_id
  • token_lot_comment: A free-form comment about the lot
  • token_lot_creation_date

Lots are groups of tokens issued at the same time, prepaid cards for example

token_status

  • token_status

tokens

  • token_id
  • token_template_id
  • token_status:
  • token_lot_id: References token_lots
  • token_creation_date (not the same as connection start time)
  • token_issuer: A user in the system. User responsible for the creation of the token (not necessarily the same as the one using it)
  • token_owner: The user that can USE the token (anyone if empty?).

When a connection is established, the values in the token_templates table are used, along with eventual network policies (maximum monthly data transfer, maximum connection time) or node policies (opening hours) to calculate max_data_transfer and expiration_date in the connection table. This calculation is expensive, but once done, all the auth server has to do is validate max_data_transfer and expiration_date which is practically free.

connection (new or redefined field in existing table)

  • connection_status (DELETED, now look in token_status)
  • token_id Now references the tokens table
  • max_total_bytes (token_max_data_transfer - SUM(data transfer for all connections on this token))
  • max_incoming_bytes Similar to above
  • max_outgoing_bytes Similar to above
  • expiration_date (MIN(NOW+token_max_connection_duration, NOW+token_max_total_duration-SUM(data transfer for all connections on this token), token_expiration_date))
  • logout_reason Explains what caused the connection to be closed