Skip to main content

Eve Negotiable authentication

Project description

eve-negotiable-auth

NOTE: this library is now deprecated. It will stay here, frozen, to support older applications that still use it. Please use hypermea-negotiable-auth


An advanced yet easy to use auth module for APIs built on Eve.

The auth class that ships with Eve, BasicAuth, allows users of your API to authenticate with Basic Authentication. The NegotiableAuth class in this package extends this to allow the user to choose from any authentication scheme your API supports. This allows for easy configuration and handling of multiple auth schemes - including schemes like Digest which require negotiation.

NOTE: This package is near-production ready. Before calling it 1.0 it needs better docs and perhaps a bit more tweaking. It is already in use in a number of production systems - but use at your own risk!

Getting Started

The steps are:

  1. Create a handler functions for each scheme you support
  2. Register those functions with AUTH_PARSER
  3. Extend NegotiableAuth and override process_claims()

Step 1 - Create handler functions

To handle a scheme you must define at least one function, usually two, which the authparser library will call. You can name them however you like - authparser calls them user_record_fn and challenge_fn

  • user_record_fn(token, **kwargs)
  • challenge_fn(**kwargs) [optional - see authparser for details, mandatory for schemes like Digest]

This is best described with an example. Let's say you want to handle Bearer token authorization. When the time comes to validate the token, your user_record_fn will be called. So let's create it. I'll call it handle_bearer:

def handle_bearer(token, **kwargs):
    # do stuff to validate the token
    # ...
    # if it checks out, populate the user record:
    record = {
        'user': 'someone@example.com',
        'role': 'employee'
    }
    # if there is a problem (if NegotiableAuth sees '_issues' then it will deny access):
    record = {
        '_issues': {
            'token': 'The token has expired.'
        }
    }
    
    return record

Step 2 - Register the handler functions

The best place to do this is above the class definition you will create in step 3. I will start by creating a file named my_auth.py

from eve_negotiable_auth import NegotiableAuth, AUTH_PARSER
from --wherever you defined your handler-- import handle_bearer

AUTH_PARSER.add_handler('Bearer', handle_bearer)

Now when the time comes, NegotiableAuth will know if it receives a request whose Authorization header has a Bearer token, it will call your handle_bearer() function.

Step 3 - Extend NegotiableAuth and override process_claims()

The NegotiableAuth class is an abstract base class and cannot be used on its own. You must make your own class that inherits from it. There is only one function to override: process_claims().

Building on the my_auth.py we started in step 2:

from eve_negotiable_auth import NegotiableAuth, AUTH_PARSER
from --wherever you defined your handler-- import handle_bearer

class MyAuth(NegotiableAuth):
    def __init__(self):
        super(MyAuth, self).__init__()
        
    def process_claims(self, claims, allowed_roles, resource, method):
        authorized = 'user' in claims
        role = claims.get('role')

        if resouce = 'salary' and role != 'employer':
            authorized = False
        
        if resource == 'position' and method != 'GET' and role != 'employer':
            authorized = False
        
	    return authorized
     

This is a too-simple example for illustration only. The request will be authorized if user exists in claims, unless the request is for salary then only employers are allowed. If it is a GET request for position, it is allowed for everyone - only employers can POST, PUT, DELETE, etc.

There are many things you can do in your own process_claims(). Please read the Eve docs for more details.

The things you need to know:

  • claims is the record returned from your handler function.
    • If the handler returns falsey, or dict with _issues, it will reject the request before your class's process_claims() is called
    • your process_claims() need only return True or False, depending whether the claims is allowed in or not.
    • As you see, you are in full control of what's in claims and how to determine whether to grant access based on what is in the claims.
  • allowed_roles, resource, and method are passed in from Eve depending on the request and what is in your Eve settings.
  • If you are using Eve's User-Restricted Resource Access, process_claims() is where you will call self.set_request_auth_value()

Wire it into your project

Once you have defined your auth class, add it to your Eve app. When you instantiate the app, pass the class name as the auth param.

app = Eve('app-name', auth=MyAuth)

Beyond the Basics

When NegotiableAuth calls your handler function, it passes the following kwargs to get_user_record()

  • allowed_roles
  • resource
  • method
  • request - the flask request object

When you define that function, have it return an dict with each member a claim (e.g. username, email, role). If the function returns falsey, or a dict that has a member named _issues, then access will be denied. To communicate issues back to the requestor, have _issues be a dict of name/value pairs, for example (this example has just one name/value):

{
    '_issues': {
        'user': 'This user does not exist.'
    }
}

get_challenge_header() - passed through to the scheme's challenge_fn

  • request

...more docs coming soon...

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

eve_negotiable_auth-0.9.6.tar.gz (5.6 kB view details)

Uploaded Source

Built Distribution

eve_negotiable_auth-0.9.6-py3-none-any.whl (6.1 kB view details)

Uploaded Python 3

File details

Details for the file eve_negotiable_auth-0.9.6.tar.gz.

File metadata

  • Download URL: eve_negotiable_auth-0.9.6.tar.gz
  • Upload date:
  • Size: 5.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for eve_negotiable_auth-0.9.6.tar.gz
Algorithm Hash digest
SHA256 f7cd5c977f1a11043d2700bf7f9bed8586e25ce29ea84797591e43262ca80498
MD5 9ffbd1621a054913b096cccd88bd9155
BLAKE2b-256 c31b9768db0e6f103b1aa335e98f55c2917c1f3bac2a85ebe213f9b43b10c85c

See more details on using hashes here.

File details

Details for the file eve_negotiable_auth-0.9.6-py3-none-any.whl.

File metadata

File hashes

Hashes for eve_negotiable_auth-0.9.6-py3-none-any.whl
Algorithm Hash digest
SHA256 5afc139393b9dd6c9f324d7e3d20a4b8c996187bb4b6489eef89f48db67d7878
MD5 f94fe4686ac5c6a0748c89b14ec506b9
BLAKE2b-256 2e0f08d28cf633bfb8f7cc0daf76e411b9652e5c6287532957e75d633fcd8d2f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page