Skip to content

Commit 46307ec

Browse files
johngianjohngian
authored
Merge pull request #56 from johngian/docs
Add documentation about installation/configuration
2 parents 3f4ba3f + 51e894b commit 46307ec

File tree

6 files changed

+200
-25
lines changed

6 files changed

+200
-25
lines changed

‎README.rst‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,6 @@ Documentation
1818

1919
The full documentation is at https://mozilla-django-oidc.readthedocs.io.
2020

21-
Quickstart
22-
----------
23-
24-
Install mozilla-django-oidc::
25-
26-
pip install mozilla-django-oidc
27-
28-
Then use it in a project::
29-
30-
import mozilla_django_oidc
31-
3221
Running Tests
3322
--------------
3423

‎docs/index.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,8 @@ Contents:
1111
.. toctree::
1212
:maxdepth: 2
1313

14-
readme
1514
installation
16-
usage
15+
settings
1716
contributing
1817
authors
1918
history

‎docs/installation.rst‎

Lines changed: 70 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,75 @@ Installation
44

55
At the command line::
66

7-
$ easy_install mozilla-django-oidc
7+
$ pip install mozilla-django-oidc
88

9-
Or, if you have virtualenvwrapper installed::
9+
.. _cookie-based sessions: https://docs.djangoproject.com/en/1.10/topics/http/sessions/#using-cookie-based-sessions
1010

11-
$ mkvirtualenv mozilla-django-oidc
12-
$ pip install mozilla-django-oidc
11+
.. warning::
12+
We highly recommend to avoid using Django's cookie-based sessions because they might open you up to replay attacks.
13+
14+
.. note::
15+
You can find more info about `cookie-based sessions`_ in Django's documentation.
16+
17+
Quick start
18+
===========
19+
20+
After installation, you'll need to configure your site to use ``mozilla-django-oidc``.
21+
Start by making the following changes to your ``settings.py`` file.
22+
23+
.. code-block:: python
24+
25+
# Add 'mozilla_django_oidc' to INSTALLED_APPS
26+
INSTALLED_APPS = (
27+
# ...
28+
'django.contrib.auth',
29+
'mozilla_django_oidc', # Load after auth
30+
# ...
31+
)
32+
33+
# Add 'mozilla_django_oidc' authentication backend
34+
AUTHENTICATION_BACKENDS = (
35+
# ...
36+
'django.contrib.auth.backends.ModelBackend',
37+
'mozilla_django_oidc.auth.OIDCAuthenticationBackend',
38+
# ...
39+
)
40+
41+
Next, edit your ``urls.py`` and add the following:
42+
43+
.. code-block:: python
44+
45+
urlpatterns = patterns(
46+
# ...
47+
url(r'^oidc/', include('mozilla_django_oidc.urls')),
48+
# ...
49+
)
50+
51+
Then you need to add the login link to your Django templates. For example:
52+
53+
.. code-block:: html+django
54+
55+
<html>
56+
<body>
57+
{% if user.is_authenticated %}
58+
<p>Current user: {{ user.email }}</p>
59+
{% else %}
60+
<a href="{% url 'oidc_authentication_init' %}">Login</a>
61+
{% endif %}
62+
</body>
63+
</html>
64+
65+
You also need to configure some OpenID connect related settings too.
66+
Please add the following to your ``settings.py``:
67+
68+
.. code-block:: python
69+
70+
OIDC_OP_AUTHORIZATION_ENDPOINT = "<URL of the OIDC OP authorization endpoint>"
71+
OIDC_OP_TOKEN_ENDPOINT = "<URL of the OIDC OP token endpoint>"
72+
OIDC_OP_USER_ENDPOINT = "<URL of the OIDC OP userinfo endpoint>"
73+
OIDC_OP_CLIENT_ID = "<OP issued client id>"
74+
OIDC_OP_CLIENT_SECRET = "<OP issued client secret>"
75+
SITE_URL = "<FQDN that users access the site from eg. http://127.0.0.1:8000/ >"
76+
77+
Finally let your OpenID connect OP know about your callback URL. In our example this is:
78+
``http://127.0.0.1:8000/oidc/callback/``.

‎docs/readme.rst‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/settings.rst‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
========
2+
Settings
3+
========
4+
5+
This document describes the Django settings that can be used to customize the configuration
6+
of ``mozilla-django-oidc``.
7+
8+
.. attribute:: SITE_URL
9+
10+
:default: No default
11+
12+
URL that users access your site from. Make sure that you provide the protocol, domain,
13+
path and port if needed (e.g. ``<protocol>://<domain>:<port>/<path>``)
14+
15+
.. note::
16+
This does not have to be a publicly accessible URL, so local URLs
17+
like ``http://localhost:8000`` or ``http://127.0.0.1`` are acceptable as
18+
long as they match what you are using to access your site.
19+
20+
21+
.. attribute:: OIDC_OP_AUTHORIZATION_ENDPOINT
22+
23+
:default: No default
24+
25+
URL of your OpenID Connect provider authorization endpoint.
26+
27+
.. attribute:: OIDC_OP_TOKEN_ENDPOINT
28+
29+
:default: No default
30+
31+
URL of your OpenID Connect provider token endpoint
32+
33+
.. attribute:: OIDC_OP_USER_ENDPOINT
34+
35+
:default: No default
36+
37+
URL of your OpenID Connect provider userinfo endpoint
38+
39+
.. attribute:: OIDC_RP_CLIENT_ID
40+
41+
:default: No default
42+
43+
OpenID Connect client ID provided by your OP
44+
45+
.. attribute:: OIDC_RP_CLIENT_SECRET
46+
47+
:default: No default
48+
49+
OpenID Connect client secret provided by your OP
50+
51+
.. attribute:: OIDC_RP_CLIENT_SECRET_ENCODED
52+
53+
:default: ``False``
54+
55+
Controls whether your client secret requires base64 decoding for verification
56+
57+
.. attribute:: OIDC_VERIFY_JWT
58+
59+
:default: ``True``
60+
61+
Controls whether the OpenID Connect client verifies the signature of the JWT tokens
62+
63+
.. attribute:: OIDC_USE_NONCE
64+
65+
:default: ``True``
66+
67+
Controls whether the OpenID Connect client uses nonce verification
68+
69+
.. attribute:: OIDC_VERIFY_SSL
70+
71+
:default: ``True``
72+
73+
Controls whether the OpenID Connect client verifies the SSL certificate of the OP responses
74+
75+
.. attribute:: OIDC_CREATE_USER
76+
77+
:default: ``True``
78+
79+
Enables or disables automatic user creation during authentication
80+
81+
.. attribute:: OIDC_STATE_SIZE
82+
83+
:default: ``32``
84+
85+
Sets the length of the random string used for OpenID Connect state verification
86+
87+
.. attribute:: OIDC_NONCE_SIZE
88+
89+
:default: ``32``
90+
91+
Sets the length of the random string used for OpenID Connect nonce verification
92+
93+
.. attribute:: OIDC_REDIRECT_FIELD_NAME
94+
95+
:default: ``next``
96+
97+
Sets the GET parameter that is being used to define the redirect URL after succesful authentication
98+
99+
.. attribute:: OIDC_CALLBACK_CLASS
100+
101+
:default: ``mozilla_django_oidc.views.OIDCAuthenticationCallbackView``
102+
103+
Allows you to substitute a custom class-based view to be used as OpenID Connect
104+
callback URL.
105+
106+
.. note::
107+
108+
When using a custom callback view, it is generally a good idea to subclass the
109+
default ``OIDCAuthenticationCallbackView`` and override the methods you want to change.
110+
111+
.. attribute:: LOGIN_REDIRECT_URL
112+
113+
:default: ``/accounts/profile``
114+
115+
Path to redirect to on successful login. If you don't specify this, the
116+
default Django value will be used.
117+
118+
.. attribute:: LOGIN_REDIRECT_URL_FAILURE
119+
120+
:default: ``/``
121+
122+
Path to redirect to on an unsuccessful login attempt.
123+
124+
125+
.. attribute:: LOGOUT_REDIRECT_URL
126+
127+
:default: ``/``
128+
129+
Path to redirect to on logout.

‎docs/usage.rst‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

0 commit comments

Comments
 (0)