Sphinx documentation fixes (#219)
* Small wording change + fix in example template code * Added note about UserConsent not being in the admin * Mostly spelling corrections and phrasing changes * Moved template context explation from the settings to the templates page * Changed wording * Changed wording
This commit is contained in:
Reinout van Rees
Wojciech Bartosiak
parent
43d990c04d
commit
bb218dbc56
|
|
@ -1,7 +1,7 @@
|
|||
Welcome to Django OIDC Provider Documentation!
|
||||
==============================================
|
||||
|
||||
This tiny (but powerful!) package can help you providing out of the box all the endpoints, data and logic needed to add OpenID Connect capabilities to your Django projects. And as a side effect a fair implementation of OAuth2.0 too. Covers Authorization Code, Implicit and Hybrid flows.
|
||||
This tiny (but powerful!) package can help you to provide out of the box all the endpoints, data and logic needed to add OpenID Connect capabilities to your Django projects. And as a side effect a fair implementation of OAuth2.0 too. Covers Authorization Code, Implicit and Hybrid flows.
|
||||
|
||||
Also implements the following specifications:
|
||||
|
||||
|
|
@ -15,8 +15,8 @@ Also implements the following specifications:
|
|||
|
||||
Before getting started there are some important things that you should know:
|
||||
|
||||
* Despite that implementation MUST support TLS. You can make request without using SSL. There is no control on that.
|
||||
* Supports only for requesting Claims using Scope values.
|
||||
* Despite that implementation MUST support TLS, you *can* make request without using SSL. There is no control on that.
|
||||
* Supports only requesting Claims using Scope values, so you cannot request individual Claims.
|
||||
* If you enable the Resource Owner Password Credentials Grant, you MUST implement protection against brute force attacks on the token endpoint
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -3,11 +3,11 @@
|
|||
Access Tokens
|
||||
#############
|
||||
|
||||
At the end of the login process, an access token is generated. This access token is the thing that's passed along with every API call (e.g. userinfo endpoint) as proof that the call was made by a specific person from a specific app.
|
||||
At the end of the login process, an access token is generated. This access token is the thing that is passed along with every API call to the openid connect server (e.g. userinfo endpoint) as proof that the call was made by a specific person from a specific app.
|
||||
|
||||
Access tokens generally have a lifetime of only a couple of hours, you can use ``OIDC_TOKEN_EXPIRE`` to set custom expiration that suit your needs.
|
||||
Access tokens generally have a lifetime of only a couple of hours. You can use ``OIDC_TOKEN_EXPIRE`` to set a custom expiration time that suits your needs.
|
||||
|
||||
Obtaining an Access token
|
||||
Obtaining an Access Token
|
||||
=========================
|
||||
|
||||
Go to the admin site and create a confidential client with ``response_type = code`` and ``redirect_uri = http://example.org/``.
|
||||
|
|
@ -20,7 +20,7 @@ In the redirected URL you should have a ``code`` parameter included as query str
|
|||
|
||||
http://example.org/?code=b9cedb346ee04f15ab1d3ac13da92002&state=123123
|
||||
|
||||
We use ``code`` value to obtain ``access_token`` and ``refresh_token``::
|
||||
We use the ``code`` value to obtain ``access_token`` and ``refresh_token``::
|
||||
|
||||
curl -X POST \
|
||||
-H "Cache-Control: no-cache" \
|
||||
|
|
@ -42,7 +42,7 @@ Example response::
|
|||
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
|
||||
}
|
||||
|
||||
Then you can grab the access token and ask user data by doing a GET request to the ``/userinfo`` endpoint::
|
||||
Then you can grab the access token and ask for user data by doing a GET request to the ``/userinfo`` endpoint::
|
||||
|
||||
curl -X GET \
|
||||
-H "Cache-Control: no-cache" \
|
||||
|
|
@ -51,9 +51,9 @@ Then you can grab the access token and ask user data by doing a GET request to t
|
|||
Expiration and Refresh of Access Tokens
|
||||
=======================================
|
||||
|
||||
If you receive a ``401 Unauthorized`` status when issuing access token probably means that has expired.
|
||||
If you receive a ``401 Unauthorized`` status when using the access token, this probably means that your access token has expired.
|
||||
|
||||
The RP application obtains a new access token by sending a POST request to the ``/token`` endpoint with the following request parameters::
|
||||
The RP application can request a new access token by using the refresh token. Send a POST request to the ``/token`` endpoint with the following request parameters::
|
||||
|
||||
curl -X POST \
|
||||
-H "Cache-Control: no-cache" \
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ We love contributions, so please feel free to fix bugs, improve things, provide
|
|||
|
||||
* Fork the project.
|
||||
* Make your feature addition or bug fix.
|
||||
* Add tests for it inside ``oidc_provider/tests``. Then run all and ensure everything is OK (read docs for how to test in all envs).
|
||||
* Add tests for it inside ``oidc_provider/tests``. Then run all tests and ensure everything is OK (see the section below on how to test in all envs).
|
||||
* Send pull request to the specific version branch.
|
||||
|
||||
Running Tests
|
||||
|
|
@ -24,7 +24,7 @@ Use `tox <https://pypi.python.org/pypi/tox>`_ for running tests in each of the e
|
|||
# Run single test file.
|
||||
$ python runtests.py oidc_provider.tests.test_authorize_endpoint
|
||||
|
||||
Also tests run on every commit to the project, we use `travis <https://travis-ci.org/juanifioren/django-oidc-provider/>`_ for this.
|
||||
We also use `travis <https://travis-ci.org/juanifioren/django-oidc-provider/>`_ to automatically test every commit to the project,
|
||||
|
||||
Improve Documentation
|
||||
=====================
|
||||
|
|
@ -34,4 +34,4 @@ We use `Sphinx <http://www.sphinx-doc.org/>`_ for generate this documentation. I
|
|||
* Install Sphinx (``pip install sphinx``) and the auto-build tool (``pip install sphinx-autobuild``).
|
||||
* Move inside the docs folder. ``cd docs/``
|
||||
* Generate and watch docs by running ``sphinx-autobuild . _build/``.
|
||||
* Open ``http://127.0.0.1:8000`` on a browser.
|
||||
* Open ``http://127.0.0.1:8000`` in a browser.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ You can use the example project code to run your OIDC Provider at ``localhost:80
|
|||
Go to the admin site and create a public client with a response_type ``id_token token`` and a redirect_uri ``http://localhost:3000``.
|
||||
|
||||
.. note::
|
||||
Remember to create at least one **RSA Key** for the server. ``python manage.py creatersakey``
|
||||
Remember to create at least one **RSA Key** for the server with ``python manage.py creatersakey``
|
||||
|
||||
**02. Create the client**
|
||||
|
||||
|
|
|
|||
|
|
@ -12,13 +12,13 @@ Requirements
|
|||
Quick Installation
|
||||
==================
|
||||
|
||||
If you want to get started fast see our ``/example_project`` folder.
|
||||
If you want to get started fast see our ``/example_project`` folder in your local installation. Or look at it `on github <https://github.com/juanifioren/django-oidc-provider/tree/v0.5.x/example_project>`_.
|
||||
|
||||
Install the package using pip::
|
||||
|
||||
$ pip install django-oidc-provider
|
||||
|
||||
Add it to your apps::
|
||||
Add it to your apps in your project's django settings::
|
||||
|
||||
INSTALLED_APPS = (
|
||||
'django.contrib.admin',
|
||||
|
|
@ -31,7 +31,7 @@ Add it to your apps::
|
|||
# ...
|
||||
)
|
||||
|
||||
Add the provider urls::
|
||||
Include our urls to your project's ``urls.py``::
|
||||
|
||||
urlpatterns = patterns('',
|
||||
# ...
|
||||
|
|
@ -39,11 +39,11 @@ Add the provider urls::
|
|||
# ...
|
||||
)
|
||||
|
||||
Generate server RSA key and run migrations (if you don't)::
|
||||
Run the migrations and generate a server RSA key::
|
||||
|
||||
$ python manage.py migrate
|
||||
$ python manage.py creatersakey
|
||||
|
||||
Add required variables to your project settings::
|
||||
Add this required variable to your project's django settings::
|
||||
|
||||
LOGIN_URL = '/accounts/login/'
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
OAuth2 Server
|
||||
#############
|
||||
|
||||
Because OIDC is a layer on top of the OAuth 2.0 protocol, this package gives you a simple but effective OAuth2 server that you can use not only for logging in your users on multiple platforms, also to protect some resources you want to expose.
|
||||
Because OIDC is a layer on top of the OAuth 2.0 protocol, this package also gives you a simple but effective OAuth2 server that you can use not only for logging in your users on multiple platforms, but also to protect other resources you want to expose.
|
||||
|
||||
Protecting Views
|
||||
================
|
||||
|
|
|
|||
|
|
@ -3,8 +3,9 @@
|
|||
Relying Parties
|
||||
###############
|
||||
|
||||
Relying Parties (RP) creation it's up to you. This is because is out of the scope in the core implementation of OIDC.
|
||||
So, there are different ways to create your Clients (RP). By displaying a HTML form or maybe if you have internal thrusted Clients you can create them programatically.
|
||||
Relying Parties (RP) creation is up to you. This is because is out of the scope in the core implementation of OIDC.
|
||||
So, there are different ways to create your Clients (RP). By displaying a HTML form or maybe if you have internal trusted Clients you can create them programatically.
|
||||
Out of the box, django-oidc-provider enables you to create them by hand in the django admin.
|
||||
|
||||
OAuth defines two client types, based on their ability to maintain the confidentiality of their client credentials:
|
||||
|
||||
|
|
@ -61,4 +62,4 @@ You can create a Client programmatically with Django shell ``python manage.py sh
|
|||
>>> c = Client(name='Some Client', client_id='123', client_secret='456', response_type='code', redirect_uris=['http://example.com/'])
|
||||
>>> c.save()
|
||||
|
||||
`Read more about client creation from OAuth2 spec <http://tools.ietf.org/html/rfc6749#section-2>`_
|
||||
`Read more about client creation in the OAuth2 spec <http://tools.ietf.org/html/rfc6749#section-2>`_
|
||||
|
|
|
|||
|
|
@ -3,12 +3,12 @@
|
|||
Settings
|
||||
########
|
||||
|
||||
Customize your provider so fit your project needs.
|
||||
Customize django-oidc-provider so that it fits your project's needs.
|
||||
|
||||
OIDC_LOGIN_URL
|
||||
==============
|
||||
|
||||
OPTIONAL. ``str``. Used to log the user in. By default Django's ``LOGIN_URL`` will be used. `Read more in Django docs <https://docs.djangoproject.com/en/1.7/ref/settings/#login-url>`_
|
||||
OPTIONAL. ``str``. Used to log the user in. By default Django's ``LOGIN_URL`` will be used. `Read more in the Django docs <https://docs.djangoproject.com/en/1.11/ref/settings/#login-url>`_
|
||||
|
||||
``str``. Default is ``/accounts/login/`` (Django's ``LOGIN_URL``).
|
||||
|
||||
|
|
@ -17,7 +17,7 @@ SITE_URL
|
|||
|
||||
OPTIONAL. ``str``. The OP server url.
|
||||
|
||||
If not specified will be automatically generated using ``request.scheme`` and ``request.get_host()``.
|
||||
If not specified, it will be automatically generated using ``request.scheme`` and ``request.get_host()``.
|
||||
|
||||
For example ``http://localhost:8000``.
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ Default is::
|
|||
Return ``None`` if you want to continue with the flow.
|
||||
|
||||
The typical situation will be checking some state of the user or maybe redirect him somewhere.
|
||||
With request you have access to all OIDC parameters. Remember that if you redirect the user to another place then you need to take him back to the authorize endpoint (use ``request.get_full_path()`` as the value for a "next" parameter).
|
||||
With ``request`` you have access to all OIDC parameters. Remember that if you redirect the user to another place then you need to take him back to the authorize endpoint (use ``request.get_full_path()`` as the value for a "next" parameter).
|
||||
|
||||
OIDC_AFTER_END_SESSION_HOOK
|
||||
===========================
|
||||
|
|
@ -106,35 +106,35 @@ Default is::
|
|||
OIDC_SESSION_MANAGEMENT_ENABLE
|
||||
==============================
|
||||
|
||||
OPTIONAL. ``bool``. Enables OpenID Connect Session Management 1.0 in your provider. Read :ref:`sessionmanagement` section.
|
||||
OPTIONAL. ``bool``. Enables OpenID Connect Session Management 1.0 in your provider. See the :ref:`sessionmanagement` section.
|
||||
|
||||
Default is ``False``.
|
||||
|
||||
OIDC_UNAUTHENTICATED_SESSION_MANAGEMENT_KEY
|
||||
===========================================
|
||||
|
||||
OPTIONAL. Supply a fixed string to use as browser-state key for unauthenticated clients. Read :ref:`sessionmanagement` section.
|
||||
OPTIONAL. Supply a fixed string to use as browser-state key for unauthenticated clients. See the :ref:`sessionmanagement` section.
|
||||
|
||||
Default is a string generated at startup.
|
||||
|
||||
OIDC_SKIP_CONSENT_EXPIRE
|
||||
========================
|
||||
|
||||
OPTIONAL. ``int``. User consent expiration after been granted.
|
||||
OPTIONAL. ``int``. How soon User Consent expires after being granted.
|
||||
|
||||
Expressed in days. Default is ``30*3``.
|
||||
|
||||
OIDC_TOKEN_EXPIRE
|
||||
=================
|
||||
|
||||
OPTIONAL. ``int``. Token object (access token) expiration after been created.
|
||||
OPTIONAL. ``int``. Token object (access token) expiration after being created.
|
||||
|
||||
Expressed in seconds. Default is ``60*60``.
|
||||
|
||||
OIDC_USERINFO
|
||||
=============
|
||||
|
||||
OPTIONAL. ``str``. A string with the location of your function. Read :ref:`scopesclaims` section.
|
||||
OPTIONAL. ``str``. A string with the location of your function. See the :ref:`scopesclaims` section.
|
||||
|
||||
The function receives a ``claims`` dictionary with all the standard claims and ``user`` instance. Must returns the ``claims`` dict again.
|
||||
|
||||
|
|
@ -155,7 +155,7 @@ Example usage::
|
|||
|
||||
OIDC_GRANT_TYPE_PASSWORD_ENABLE
|
||||
===============================
|
||||
OPTIONAL. A boolean to set whether to allow the Resource Owner Password
|
||||
OPTIONAL. A boolean whether to allow the Resource Owner Password
|
||||
Credentials Grant. https://tools.ietf.org/html/rfc6749#section-4.3
|
||||
|
||||
.. important::
|
||||
|
|
@ -179,21 +179,6 @@ Default is::
|
|||
'error': 'oidc_provider/error.html'
|
||||
}
|
||||
|
||||
The following contexts will be passed to the ``authorize`` and ``error`` templates respectively::
|
||||
See the :ref:`templates` section.
|
||||
|
||||
# For authorize template
|
||||
{
|
||||
'client': 'an instance of Client for the auth request',
|
||||
'hidden_inputs': 'a rendered html with all the hidden inputs needed for AuthorizeEndpoint',
|
||||
'params': 'a dict containing the params in the auth request',
|
||||
'scopes': 'a list of scopes'
|
||||
}
|
||||
|
||||
# For error template
|
||||
{
|
||||
'error': 'string stating the error',
|
||||
'description': 'string stating description of the error'
|
||||
}
|
||||
|
||||
.. note::
|
||||
The templates that are not specified here will use the default ones.
|
||||
The templates that are not specified here will use the default ones.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Templates
|
|||
#########
|
||||
|
||||
Add your own templates files inside a folder named ``templates/oidc_provider/``.
|
||||
You can copy the sample html here and edit them with your own styles.
|
||||
You can copy the sample html files here and customize them with your own style.
|
||||
|
||||
**authorize.html**::
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ You can copy the sample html here and edit them with your own styles.
|
|||
{{ hidden_inputs }}
|
||||
|
||||
<ul>
|
||||
{% for scope in params.scope %}
|
||||
{% for scope in scopes %}
|
||||
<li><strong>{{ scope.name }}</strong><br><i>{{ scope.description }}</i></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
|
@ -36,3 +36,18 @@ You can copy the sample html here and edit them with your own styles.
|
|||
|
||||
You can also customize paths to your custom templates by putting them in ``OIDC_TEMPLATES`` in the settings.
|
||||
|
||||
The following contexts will be passed to the ``authorize`` and ``error`` templates respectively::
|
||||
|
||||
# For authorize template
|
||||
{
|
||||
'client': 'an instance of Client for the auth request',
|
||||
'hidden_inputs': 'a rendered html with all the hidden inputs needed for AuthorizeEndpoint',
|
||||
'params': 'a dict containing the params in the auth request',
|
||||
'scopes': 'a list of scopes'
|
||||
}
|
||||
|
||||
# For error template
|
||||
{
|
||||
'error': 'string stating the error',
|
||||
'description': 'string stating description of the error'
|
||||
}
|
||||
|
|
|
|||
|
|
@ -9,6 +9,9 @@ The package store some information after the user grant access to some client. F
|
|||
>>> UserConsent.objects.filter(user__email='some@email.com')
|
||||
[<UserConsent: Example Client - some@email.com>]
|
||||
|
||||
Note: the ``UserConsent`` model is not included in the admin.
|
||||
|
||||
|
||||
Properties
|
||||
==========
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue