TxOAuth2

This Python module helps to implement an OAuth2 Endpoint in Twisted and provides mechanism to protect resources with OAuth2 authentication.

Usage

A sample usage can be found in the example folder.

You will need to create a TokenResource and an OAuth2 endpoint by subclassing the OAuth2 class and insert them somewhere into your server hierarchy. Add both at the same place by using the following code (see the example):

root.putChild(b"oauth2", OAuth2Subclass.initFromTokenResource(tokenResource, subPath=b"token"))

Depending on which OAuth2 grant flows you want to support, you may not need both resources. The Implicit Grant only needs the OAuth2 endpoint, the Authorization Code Grant needs both, and the others only need the TokenResource. See the specification for an indepth explanation of the grant flows. You can enable the flows by adding the GrantType to the list passed as the grantType Parameter to the OAuth2 and TokenResource endpoints. It is best to only enable as few grant types as possible.

The Authorization Code Grant flow is the most commonly used, but it is also the most complicated to implement: The OAuth2 subclass will need to overwrite the onAuthenticate method. This method will be called, when a User is redirected to your server by a Client to authorize access to some scope by the client. Within the method, you should serve or redirect to a page that allows the user to authorize the client. See here to get an idea of how such a page could look like. If the user approves the authorization, you need to call grantAccess or denyAccess if the user denies.

To protect your resources you need to either use the oauth decorator on the render_* methods of your resources or check the result of isAuthorized as demonstrated here.

Finally, you need to register the Clients by storing them in your implementation of the ClientStorage.

This module does not deal with token storage, creation and validation, client storage, persistent storage or user password-management. Depending on the enabled grant types you will need to implement a TokenFactory, TokenStorage, PersistentStorage, ClientStorage and UserPasswordManager. A few implementations of these interfaces can be found in the imp package. You may also use the tests in the tests directory to verify the expected behaviour of your implementation.

Installation

Run pip install txoauth2 or download the wheel from PyPI or Github.

Terminology

• User: A user, also called the resource owner, is the actual owner of a resource. He can grant access to the resource to a client. It is up to you to identify and authenticate a user. You can pass additionalData to grantAccess that identifies an user. This additional data will be passed to the token generator and storage, which allows for the user information to be encoded into the token.
• Client: A client is another application that wants to access a protected resource that is owned by the user. The client has no rights if they have not been explicitly granted by the user. Clients are represented by subclasses of the Client class.
• Token: There are two types of tokens: Access Tokens and Refresh Tokens. Access Tokens allow access to a protected resource. If they expire, the client can use the Refresh Token to generate a new Access Token. A token can only contain alphanumeric and the following characters: -._~+/
• Scope: A scope identifies a range collection of resources that a client can request access to. The meaning of individual scope names are not fixed, it is up to the server maintainer to define the scopes known to the server and their meaning.

Security

The OAuth2 specification requires that the protected resource and the OAuth2 endpoint are served via a secure connection (e.g., https). To allow insecure connections for local testing, pass allowInsecureRequestDebug=True where it is accepted. Do not do this in your real server because everybody will be able to read the tokens and use them to access the protected resources!