diff --git a/README.rst b/README.rst index 7f1026e7..0b67436a 100644 --- 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 index 46911a28..a68f5bac 100644 --- 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 index b52e2328..98968f85 100644 --- 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 + + + + {% if user.is_authenticated %} +

Current user: {{ user.email }}

+ {% else %} + Login + {% endif %} + + + +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 = "" + OIDC_OP_TOKEN_ENDPOINT = "" + OIDC_OP_USER_ENDPOINT = "" + OIDC_OP_CLIENT_ID = "" + OIDC_OP_CLIENT_SECRET = "" + SITE_URL = "" + +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 deleted file mode 100644 index 72a33558..00000000 --- a/docs/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/docs/settings.rst b/docs/settings.rst new file mode 100644 index 00000000..51a111ff --- /dev/null +++ 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. ``://:/``) + + .. 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 deleted file mode 100644 index 38aa905a..00000000 --- a/docs/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Usage -======== - -To use mozilla-django-oidc in a project:: - - import mozilla_django_oidc