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_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_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_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

How it would work, thoughts

Notes added by gbastien 2010/01/07

Tell me if I'm wrong, but this is how I see the future token architecture concretely.

With this new token architecture, the token itself would play a much more central part in the connection process and management than it does now.

Right now, the authentication server uses the user as a central point in the connection. A user is an entity, with a username and password, that is meant to represent a single physical person. Yet this notion fails for models without users. For instance a splash-only network has only one user, SPLASH_ONLY_USER and thus does not make a difference between each user (using different mac-address) and cannot profit from abuse control mechanisms, etc. Moreover, for this, the code needs to add special case scenarios when current user is splash-only user.

With Token2.0, the token would play the role the user now plays: represent the physical person connecting to the network, while the user will merely be an authentication scheme.

Here is how the login process would work server-side

  1. OPTIONAL Display the login page
  2. OPTIONAL The user enter his credentials (user / pass, access code, NIP, password of the day)
  3. Upon successful authentication
    1. Get credentials for token purpose (for example, the user_id in a splash-only node, instead of the id of the SPLASH_ONLY_USER would be the mac address)
    2. Delete connections with unused tokens for this user/mac
    3. Does a reusable and valid token already exist for the current user?
      1. YES, use this token
      2. NO, Can the user get a new token?
        1. YES, create a new token and use this one
        2. NO, the user cannot connect, give him a reason and what to do (Abuse control violated, needs to buy new token, etc.) EXIT
    4. Create a new connection for the token
    5. Calculate the values for this connection according to network policies
    6. Return the token to the gateway

Full support for this would require:

  • An easy way to personnalize the welcome page (login interface: user/pass, access code, choice of method, etc) May already be there
  • Additions to admin interface of networks / nodes to manage the type of connections / tokens it allow. We may want to have a mixed network of splash-only nodes, username / password and/or access code nodes, right??
  • Additions to admin interface to manage the tokens themselves. Allow for different authentication modes to have different configuration value (bandwidth, expiration) per network / node?
  • Changing the session object (and references to it) so that the references to the User object now refer to the token.
  • Writing substantial code to support all this!! (implementation will be gradual of course)