# TEST OAuth2 for Django

This project aims to provide a simple, plug-and-play method of adding _TEST
Alliance Please Ignore_ OAuth2 authentication to your Django app.

## Installation

You _should_ be able to install the library as follows:

    pip install git+https://cicd.pleaseignore.com/test-it/test_oauth2_django.git

Then, add `test_oauth` to the list of installed apps in your Django app. Also
add a URL entry for the authentication application:

    url(r'^auth/', include('test_oauth.urls', namespace='test_oauth')),

Finally, install the TEST OAuth2 authentication backend:

    AUTHENTICATION_BACKENDS = ('test_oauth.backend.TESTOAuth2Backend',)

## Settings

There are some additional settings you should add to your Django settings file
about your OAuth2 client but they're pretty self-explanatory:

 * `TEST_OAUTH_CLIENT_ID`: The client ID of your TEST OAuth2 app.
 * `TEST_OAUTH_CLIENT_SECRET`: The client secret of your app.
 * `TEST_OAUTH_CLIENT_CALLBACK`: The _exact_ callback URI of your app.

Some other options are more interesting:

 * `TEST_OAUTH_CREATE_GROUPS`: Create Django groups whenever a user logs into
   your app.
 * `TEST_OAUTH_CREATE_CHARACTERS`: Same as above, but creates a Character for
   each of the alts of the person logging in.
 * `TEST_OAUTH_REDIRECT`: The URL to which people are redirected after loggin
   in or out of the app.
 * `TEST_OAUTH_VERIFIERS`: See below.
 * `TEST_OAUTH_RESPECT_ID` (default False): If True, use the TEST Auth ID of a
   user as the identifying column in the Django app, otherwise use the
   username.
 * `TEST_OAUTH_SCOPES` (default `['read_profile']`): Scope of the OAuth
   requests.

### Verifiers

You can use an iterable of `Verifier` objects to confirm that people logging
into your app conform to some requirement. For example, take the following
verifier class:

    class GroupMembershipVerifier(Verifier):
        message = "You are not in the correct groups to log in to this site."

        def valid(self, groups, **kwargs):
            for g in groups:
                if g['id'] == self.group:
                    return True

            return False

You may then use this verifier as follows:

    TEST_OAUTH_VERIFIERS = [
        verifiers.GroupMembershipVerifier(group=10000)
    ]

Which will deny any member not in group 10000. A login is denied if any of the
verifiers return false. So, you may also do something like this:

    TEST_OAUTH_VERIFIERS = [
        verifiers.GroupMembershipVerifier(group=10000),
        verifiers.GroupMembershipVerifier(group=1111),
        verifiers.TESTMembershipVerifier(),
    ]

You can write your own verifiers as well. Just look at the source code for
examples.