Extensive docs: confluence

What Is It

It is a Django application without a full Django project. This application enables authenticated communication between HTTP(s)-capable clients and servers. Identification is by means of OAuth token. Tokens are acquired by presentation of credentials, and may be refreshed by repeating the authorization flow.

Supported grant types:

Client Credentials - used for internal service-to-service communication. Tested with a standard 3rd party oauth2_provider Django application from django-oauth-utils package
JWT Bearer - currently used for communication with Salesforce

Supported Versions

Python 2.7 and Django 1.11
Python 3.7 and Django 2.2
PostgreSQL >= 9.6.9

Other versions may likely work too, but are not supported.

Python and Django compatibility is maintained in compat.py and test_compat.py

Installation

Extras

As of version 0.2.0 this project provides two extras, JWT_grant and oauth2provider_command:

JWT_grant - enables JWT grant type support, used e.g. by Salesforce. See RFC
oauth2provider_command - enables oauth2_provider.Application creation by means of an oauth2provider_app Django management command

Vanilla install, without extras, makes you able to:

talk to systems that use client-credentials grant type

Steps

Add installation URI in requirements. Choose URI schema that works best for your case. They differ in syntax, to keep pip and pip-compile happy:

no hashing and no extras: git+https://git@github.com/Livit/Labster.OAuth2Client.git@0.2.3
extras needed but no hashing required: git+ssh://git@github.com/Livit/Labster.OAuth2Client.git@0.2.3#egg=oauth2-client[JWT_grant,oauth2provider_command]
extras needed and pip-compile --generate-hashes required: https://github.com/Livit/Labster.OAuth2Client/archive/v0.2.3.zip#egg=oauth2-client[JWT_grant,oauth2provider_command]

Add "oauth2_client" to your INSTALLED_APPS settings. If you installed also oauth2provider_command extras, you have to add also oauth2_provider

    INSTALLED_APPS = [
        ...
        'oauth2_provider',  # only for `providerApp` extras
        'oauth2_client',
    ]

Run python manage.py migrate to create oauth2_client models.
On the receiver side, create Application model and fill with proper data, e.g.:

    {
        name="Client name",
        redirect_uris="http://localhost",  # for local development
        client_type=Application.CLIENT_CONFIDENTIAL,
        authorization_grant_type=Application.GRANT_CLIENT_CREDENTIALS,
    }

On the client side, create oauth2_client.Application model instance, and populate it. You can get help by calling python manage.py oauth2client_app -h.
Instantiate the client via library calls, and use it for all api calls.

Tests and Development

Tests use PostgreSQL. The setup is automated with docker-compose, that is installed locally with make docker_setup command.
Project requirements live inside requirements/tox_requirements{27|37}.txt.
Test settings live inside test_settings.py.

Development Requirements

python3.7 or higher. Python2.7 is supported but discouraged.
virtualenv
docker

Automated Tox Run

tox runs tests for both python2 and python3
in system-wide python: pip install tox
cd PROJECT_ROOT - root of this project
mkdir -p reports/diff_coverage
make docker_setup # set up a venv for docker-compose
make start && sleep 5 # start a dockerized PostgreSQL instance
tox

Running Tests in IDE (Tested With Pycharm)

make setup # create a venv inside a .venv dir and installs dependencies, this is hardcoded to use python3
make docker_setup # set up a venv for docker-compose
make start && sleep 5 # start a dockerized PostgreSQL instance
python test_manage.py migrate # apply migrations
point your IDE at .venv as the python installation to be used
tests should work in the IDE

Running Tests in Django-style

As it is a Django app without a Django project, custom manage.py created: test_manage.py. It is a cut-down framework to provide sufficient Django context for testing and uses a test settings file, test_settings.py.
To run tests as if it was a Django project:

make setup # create a venv inside a .venv dir and installs dependencies, this is hardcoded to use python3
make docker_setup # set up a venv for docker-compose
make start && sleep 5 # start a dockerized PostgreSQL instance
source .venv/bin/activate
python test_manage.py test tests

Migrations

To create migrations run python test_manage.py makemigrations
To apply migrations run python test_manage.py migrate

Codestyle

Tox runs pycodestyle, but not pylint, because pylint checks for Django dependencies, which are not part of this project.

Nuances

PostgreSQL

Dockerized PostgreSQL Setup

make docker_setup
make start

Quick Standalone PostgreSQL Setup

To install psycopg2 you need install special packages on Ubuntu and on Mac: http://initd.org/psycopg/docs/install.html

If on mac you will see ld: library not found for -lssl, then brew upgrade openssl and export CPPFLAGS="-I/usr/local/opt/openssl/include", export LDFLAGS="-L/usr/local/opt/openssl/lib".

You can set export PGDATA='full-path-to/Labster.oauth2_client/psql_data'
init_db
pg_ctl -D /Users/kry/repos/labster/Labster.oauth2_client/psql_data -l logfile start
createdb "test_oauth2_client"
check : psql -U your_shell_user test_oauth2_client
Then fill data in settings file, just change your user name.
stop pg_ctl when tests ends.

Troubleshooting

Using Tox

Do not run tox from virtualenv
If tox does not get your code, delete ./.tox folder and sometimes .egg-info folder.

Coverage

If coverage is installed globally, it can take wrong version inside virtualenv, so better uninstall it.

Livit/Labster.OAuth2Client