README.md 2.4 KB
Newer Older
Sharad Heft's avatar
Sharad Heft committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
# 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+ssh://gogs@git.pleaseignore.com:206/sharad/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')),

17 18 19 20
Finally, install the TEST OAuth2 authentication backend:

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

Sharad Heft's avatar
Sharad Heft committed
21 22 23
## Settings

There are some additional settings you should add to your Django settings file
Sharad Heft's avatar
Sharad Heft committed
24
about your OAuth2 client but they're pretty self-explanatory:
Sharad Heft's avatar
Sharad Heft committed
25 26 27 28

 * `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.
Sharad Heft's avatar
Sharad Heft committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72

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.

### 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.