Security Module

There will be two checks made before granting the user access to the system. The first is the client key check. The client key is a shared key which grants the client access to speak to the gateway. The system will generate a key which will be unique for the client. This key will be passed in the authentication message with the user's credentials. The security module checks the users authentication method, and also checks the session validity, and which permissions the user has for performing actions. The permissions will be following the way that the Drupal module security.

This model is a permission to perform actions (view, edit, delete). This may or may not map to tables and columns.

The security module will be configured to use the following authentication mechanisms:

  • Local Credentials
  • OpenID
  • LDAP (for Windows Domains)
  • Facebook Connect (OAuth)
  • Twitter (OAuth)
  • Google+ (OAuth)
  • Potential others

Once the user is identified, then they will be granted a session token. This session token will be passed back and forward to identify a session. Each time the session token is used, the session is active. If the session token is used inside one minute before the end of the session, then the valid until session end time will be incremented by another user configurable end time. This will be done to avoid flapping the cached data (which would defeat the purpose of the cache).

If there is a valid session, then the security module checks to see if the user is allowed to issue the command or not. The system will be partitioned so that users will be allowed to see only subsets of the data. This partitioning will be done on a brand basis.

Once the session and command is acceptable, then the contents of the call is checked to see if it is valid.

If it is valid then the call succeeds and it is then returned.

The security module is done on a user/role based model. Users can have many roles which control which permissions they have to perform actions.

The security module will incorporate a secret key which will be known to the server and the client. This secret key combined with the API key and other fields will be hashed using SHA-2 and sent over the wire as part of the authentication.

So the authentication part of the message should contain:

  • API Key (a pre-determined UUID)
  • API Secret - Hash of client type identifier salted with secret phrase (api password), which is then hashed and slated using the Nonce. The database stores the hash of the client type identifier salted by the secret phrase (binary in hex representation).
  • Nonce (a random UUID)
  • Authorisation Identifier (a string containing the method of identification - Local, Facebook User ID, or OpenID, etc)
  • Username (string, always present)
  • Password - Hash of password using username as salt, which is then hashed using the Nonce (SHA-256 encrypted using Nonce, or token from third party authentication)

This will then be processed by the server. It will re-create the the API Secret hash. If it matches, then the client is allowed to communicate with the gateway.

Then the user credentials are checked against the users in the system. If a match has been found (and the user credentials also match which clients they are registered for), then an access token is generated:

  • A random UUID is used for the token.

This access token has a limited time of validity and if it is not used will expire within the user-defined time limit. Once the access token has been generated the Nonce is discarded.

If the access token has expired and a user attempts to use the token then the system will return an error saying that the token is no longer valid.

It is hoped that this is secure enough given that the system is open source, and the API Key / API Secret is really the main mechanism to stop abuse of the system.

There should also be some sort of way of disregarding traffic if there's spurious attempts to brute force access to the system.

Having an API Key will also allow the easy tracking of usage of the system for profiling or other purposes.