auth.py - Authentication Classes

Authentication

This module contains Gate One's authentication classes. They map to Gate One's --auth configuration option like so:

--auth=none NullAuthHandler
--auth=kerberos KerberosAuthHandler
--auth=google GoogleAuthHandler
--auth=pam PAMAuthHandler
--auth=api APIAuthHandler

Note

API authentication is handled inside of Gate One

None or Anonymous

By default Gate One will not authenticate users. This means that user sessions will be tied to their browser cookie and users will not be able to resume their sessions from another computer/browser. Most useful for situations where session persistence and logging aren't important.

All users will show up as ANONYMOUS using this authentication type.

Kerberos

Kerberos authentication utilizes GSSAPI for Single Sign-on (SSO) but will fall back to HTTP Basic authentication if GSSAPI auth fails. This authentication type can be integrated into any Kerberos infrastructure including Windows Active Directory.

It is great for both transparent authentication and being able to tie sessions and logs to specific users within your organization (compliance).

Note

The sso.py module itself has extensive documentation on this authentication type.

Google Authentication

If you want persistent user sessions but don't care to run your own authentication infrastructure this authentication type is for you. Assuming, of course, that your Gate One server and clients will have access to the Internet.

Note

This authentication type is perfect if you're using Chromebooks (Chrome OS devices).

API Authentication

API-based authentication is actually handled in gateone.py but we still need something to exist at the /auth URL that will always return the 'unauthenticated' response. This ensures that no one can authenticate themselves by visiting that URL manually.

Docstrings

auth.applicable_policies(application, user, policies)[source]

Given an application and a user object, returns the merged/resolved policies from the given policies RUDict.

Note

Policy settings always start with '*', 'user', or 'group'.

class auth.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 auth.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 auth.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 auth.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

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.

class auth.BaseAuthHandler(application, request, **kwargs)[source]

The base class for all Gate One authentication handlers.

get_current_user()[source]

Tornado standard method--implemented our way.

user_login(user)[source]

Called immediately after a user authenticates successfully. Saves session information in the user's directory. Expects user to be a dict containing a 'upn' value representing the username or userPrincipalName. e.g. 'user@REALM' or just 'someuser'. Any additional values will be attached to the user object/cookie.

user_logout(user, redirect=None)[source]

Called immediately after a user logs out, cleans up the user's session information and optionally, redirects them to redirect (URL).

class auth.NullAuthHandler(application, request, **kwargs)[source]

A handler for when no authentication method is chosen (i.e. --auth=none). With this handler all users will show up as "ANONYMOUS".

get(*args, **kwargs)[source]

Sets the 'gateone_user' cookie with a new random session ID (go_session) and sets go_upn to 'ANONYMOUS'.

user_login(user)[source]

This is an override of BaseAuthHandler since anonymous auth is special. Generates a unique session ID for this user and saves it in a browser cookie. This is to ensure that anonymous users can't access each other's sessions.

class auth.APIAuthHandler(application, request, **kwargs)[source]

A handler that always reports 'unauthenticated' since API-based auth doesn't use auth handlers.

get(*args, **kwargs)[source]

Deletes the 'gateone_user' cookie and handles some other situations for backwards compatibility.

class auth.GoogleAuthHandler(application, request, **kwargs)[source]

Google authentication handler using Tornado's built-in GoogleMixin (fairly boilerplate).

get(*args, **kwargs)[source]

Sets the 'user' cookie with an appropriate upn and session and any other values that might be attached to the user object given to us by Google.

_on_auth(user)[source]

Just a continuation of the get() method (the final step where it actually sets the cookie).

class auth.SSLAuthHandler(application, request, **kwargs)[source]

SSL Certificate-based authentication handler. Can only be used if the ca_certs is set and ssl_auth=required or ssl_auth=optional.

initialize()[source]

Print out helpful error messages if the requisite settings aren't configured.

_convert_certificate(cert)[source]

Converts the certificate format returned by get_ssl_certificate() into a format more suitable for a user dict.

get(*args, **kwargs)[source]

Sets the 'user' cookie with an appropriate upn and session and any other values that might be attached to the user's client SSL certificate.

class auth.KerberosAuthHandler(application, request, **kwargs)[source]

Handles authenticating users via Kerberos/GSSAPI/SSO.

get(*args, **kwargs)[source]

Checks the user's request header for the proper Authorization data. If it checks out the user will be logged in via _on_auth(). If not, the browser will be redirected to login.

class auth.PAMAuthHandler(application, request, **kwargs)[source]

Handles authenticating users via PAM.

get(*args, **kwargs)[source]

Checks the user's request header for the proper Authorization data. If it checks out the user will be logged in via _on_auth(). If not, the browser will be redirected to login.