Merge pull request #56 from johngian/docs

Add documentation about installation/configuration
mozilla · Nov 23, 2016 · 46307ec · 46307ec
2 parents 3f4ba3f + 51e894b
commit 46307ec
Show file tree

Hide file tree

Showing 6 changed files with 200 additions and 25 deletions.
diff --git a/README.rst b/README.rst
@@ -18,17 +18,6 @@ Documentation
 
 The full documentation is at https://mozilla-django-oidc.readthedocs.io.
 
-Quickstart
-----------
-
-Install mozilla-django-oidc::
-
-    pip install mozilla-django-oidc
-
-Then use it in a project::
-
-    import mozilla_django_oidc
-
 Running Tests
 --------------
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -11,9 +11,8 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
-   usage
+   settings
    contributing
    authors
    history
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -4,9 +4,75 @@ Installation
 
 At the command line::
 
-    $ easy_install mozilla-django-oidc
+    $ pip install mozilla-django-oidc
 
-Or, if you have virtualenvwrapper installed::
+.. _cookie-based sessions: https://docs.djangoproject.com/en/1.10/topics/http/sessions/#using-cookie-based-sessions
 
-    $ mkvirtualenv mozilla-django-oidc
-    $ pip install mozilla-django-oidc
+.. warning::
+   We highly recommend to avoid using Django's cookie-based sessions because they might open you up to replay attacks.
+
+.. note::
+   You can find more info about `cookie-based sessions`_ in Django's documentation.
+
+Quick start
+===========
+
+After installation, you'll need to configure your site to use ``mozilla-django-oidc``.
+Start by making the following changes to your ``settings.py`` file.
+
+.. code-block:: python
+
+   # Add 'mozilla_django_oidc' to INSTALLED_APPS
+   INSTALLED_APPS = (
+       # ...
+       'django.contrib.auth',
+       'mozilla_django_oidc',  # Load after auth
+       # ...
+   )
+
+   # Add 'mozilla_django_oidc' authentication backend
+   AUTHENTICATION_BACKENDS = (
+       # ...
+       'django.contrib.auth.backends.ModelBackend',
+       'mozilla_django_oidc.auth.OIDCAuthenticationBackend',
+       # ...
+   )
+
+Next, edit your ``urls.py`` and add the following:
+
+.. code-block:: python
+
+   urlpatterns = patterns(
+       # ...
+       url(r'^oidc/', include('mozilla_django_oidc.urls')),
+       # ...
+   )
+
+Then you need to add the login link to your Django templates. For example:
+
+.. code-block:: html+django
+
+   <html>
+     <body>
+       {% if user.is_authenticated %}
+         <p>Current user: {{ user.email }}</p>
+       {% else %}
+         <a href="{% url 'oidc_authentication_init' %}">Login</a>
+       {% endif %}
+     </body>
+   </html>
+
+You also need to configure some OpenID connect related settings too.
+Please add the following to your ``settings.py``:
+
+.. code-block:: python
+
+   OIDC_OP_AUTHORIZATION_ENDPOINT = "<URL of the OIDC OP authorization endpoint>"
+   OIDC_OP_TOKEN_ENDPOINT = "<URL of the OIDC OP token endpoint>"
+   OIDC_OP_USER_ENDPOINT = "<URL of the OIDC OP userinfo endpoint>"
+   OIDC_OP_CLIENT_ID = "<OP issued client id>"
+   OIDC_OP_CLIENT_SECRET = "<OP issued client secret>"
+   SITE_URL = "<FQDN that users access the site from eg. http://127.0.0.1:8000/ >"
+
+Finally let your OpenID connect OP know about your callback URL. In our example this is:
+``http://127.0.0.1:8000/oidc/callback/``.
diff --git a/docs/readme.rst b/docs/readme.rst
diff --git a/docs/settings.rst b/docs/settings.rst
@@ -0,0 +1,129 @@
+========
+Settings
+========
+
+This document describes the Django settings that can be used to customize the configuration
+of ``mozilla-django-oidc``.
+
+.. attribute:: SITE_URL
+
+   :default: No default
+
+   URL that users access your site from. Make sure that you provide the protocol, domain,
+   path and port if needed (e.g. ``<protocol>://<domain>:<port>/<path>``)
+
+   .. note::
+      This does not have to be a publicly accessible URL, so local URLs
+      like ``http://localhost:8000`` or ``http://127.0.0.1`` are acceptable as
+      long as they match what you are using to access your site.
+
+
+.. attribute:: OIDC_OP_AUTHORIZATION_ENDPOINT
+
+   :default: No default
+
+   URL of your OpenID Connect provider authorization endpoint.
+
+.. attribute:: OIDC_OP_TOKEN_ENDPOINT
+
+   :default: No default
+
+   URL of your OpenID Connect provider token endpoint
+
+.. attribute:: OIDC_OP_USER_ENDPOINT
+
+   :default: No default
+
+   URL of your OpenID Connect provider userinfo endpoint
+
+.. attribute:: OIDC_RP_CLIENT_ID
+
+   :default: No default
+
+   OpenID Connect client ID provided by your OP
+
+.. attribute:: OIDC_RP_CLIENT_SECRET
+
+   :default: No default
+
+   OpenID Connect client secret provided by your OP
+
+.. attribute:: OIDC_RP_CLIENT_SECRET_ENCODED
+
+   :default: ``False``
+
+   Controls whether your client secret requires base64 decoding for verification
+
+.. attribute:: OIDC_VERIFY_JWT
+
+   :default: ``True``
+
+   Controls whether the OpenID Connect client verifies the signature of the JWT tokens
+
+.. attribute:: OIDC_USE_NONCE
+
+   :default: ``True``
+
+   Controls whether the OpenID Connect client uses nonce verification
+
+.. attribute:: OIDC_VERIFY_SSL
+
+   :default: ``True``
+
+   Controls whether the OpenID Connect client verifies the SSL certificate of the OP responses
+
+.. attribute:: OIDC_CREATE_USER
+
+   :default: ``True``
+
+   Enables or disables automatic user creation during authentication
+
+.. attribute:: OIDC_STATE_SIZE
+
+   :default: ``32``
+
+   Sets the length of the random string used for OpenID Connect state verification
+
+.. attribute:: OIDC_NONCE_SIZE
+
+   :default: ``32``
+
+   Sets the length of the random string used for OpenID Connect nonce verification
+
+.. attribute:: OIDC_REDIRECT_FIELD_NAME
+
+   :default: ``next``
+
+   Sets the GET parameter that is being used to define the redirect URL after succesful authentication
+
+.. attribute:: OIDC_CALLBACK_CLASS
+
+   :default: ``mozilla_django_oidc.views.OIDCAuthenticationCallbackView``
+
+   Allows you to substitute a custom class-based view to be used as OpenID Connect
+   callback URL.
+
+   .. note::
+
+      When using a custom callback view, it is generally a good idea to subclass the
+      default ``OIDCAuthenticationCallbackView`` and override the methods you want to change.
+
+.. attribute:: LOGIN_REDIRECT_URL
+
+    :default: ``/accounts/profile``
+
+    Path to redirect to on successful login. If you don't specify this, the
+    default Django value will be used.
+
+.. attribute:: LOGIN_REDIRECT_URL_FAILURE
+
+    :default: ``/``
+
+    Path to redirect to on an unsuccessful login attempt.
+
+
+.. attribute:: LOGOUT_REDIRECT_URL
+
+   :default: ``/``
+
+   Path to redirect to on logout.
diff --git a/docs/usage.rst b/docs/usage.rst