authorization.py - Authentication Classes¶

Authorization¶

This module contains Gate One's authorization helpers.

Docstrings¶

class gateone.auth.authorization.require(*conditions)[source]¶

A decorator to add authorization requirements to any given function or method using condition classes. Condition classes are classes with check() methods that return True if the condition is met.

Example of using @require with is_user():

@require(is_user('administrator'))
def admin_index(self):
    return 'Hello, Administrator!'

This would only allow the user, 'administrator' access to the index page. In this example the condition is the is_user function which checks that the logged-in user's username (aka UPN) is 'administrator'.

class gateone.auth.authorization.authenticated[source]¶

A condition class to be used with the @require decorator that returns True if the user is authenticated.

Note

Only meant to be used with WebSockets. tornado.web.RequestHandler instances can use @tornado.web.authenticated

class gateone.auth.authorization.is_user(upn)[source]¶

A condition class to be used with the @require decorator that returns True if the given username/UPN matches what's in self._current_user.

class gateone.auth.authorization.policies(app)[source]¶

A condition class to be used with the @require decorator that returns True if all the given conditions are within the limits specified in Gate One's settings (e.g. 50limits.conf). Here's an example:

@require(authenticated(), policies('terminal'))
def new_terminal(self, settings):
    # Actual function would be here
    pass

That would apply all policies that are configured for the 'terminal' application. It works like this:

The TerminalApplication application registers its name and policy-checking function inside of initialize() like so:

self.ws.security.update({'terminal': terminal_policies})

Whenever a function decorated with @require(policies('terminal')) is called the registered policy-checking function (e.g. app_terminal.terminal_policies()) will be called, passing the current instance of policies as the only argument.

It is then up to the policy-checking function to make a determination as to whether or not the user is allowed to execute the decorated function and must return True if allowed. Also note that the policy-checking function will be able to make modifications to the function and its arguments if the security policies warrant it.

Note

If you write your own policy-checking function (like terminal_policies()) it is often a good idea to send a notification to the user indicating why they've been denied. You can do this with the instance.send_message() method.