From 72bdeb0b3cb07ba8286827ae66b3553717cc3fb3 Mon Sep 17 00:00:00 2001 From: Ignacio Fiorentino Date: Mon, 19 Sep 2016 18:05:29 -0300 Subject: [PATCH] Update docs. --- docs/index.rst | 2 +- .../sections/{claims.rst => scopesclaims.rst} | 55 +++++++++++++++++-- docs/sections/settings.rst | 43 +-------------- 3 files changed, 53 insertions(+), 47 deletions(-) rename docs/sections/{claims.rst => scopesclaims.rst} (66%) diff --git a/docs/index.rst b/docs/index.rst index afa58b4..e30bd3b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,7 +26,7 @@ Contents: sections/relyingparties sections/serverkeys sections/templates - sections/claims + sections/scopesclaims sections/userconsent sections/oauth2 sections/settings diff --git a/docs/sections/claims.rst b/docs/sections/scopesclaims.rst similarity index 66% rename from docs/sections/claims.rst rename to docs/sections/scopesclaims.rst index d4eb38f..9a3309d 100644 --- a/docs/sections/claims.rst +++ b/docs/sections/scopesclaims.rst @@ -1,7 +1,7 @@ -.. _claims: +.. _scopesclaims: -Standard Claims -############### +Scopes and Claims +################# This subset of OpenID Connect defines a set of standard Claims. They are returned in the UserInfo Response. @@ -41,8 +41,8 @@ List of all the ``claims`` keys grouped by scopes: | updated_at | | | | +--------------------+----------------+-----------------------+------------------------+ -How to populate userinfo response -================================= +How to populate standard claims +=============================== Somewhere in your Django ``settings.py``:: @@ -65,3 +65,48 @@ Now test an Authorization Request using these scopes ``openid profile email`` an .. note:: Please **DO NOT** add extra keys or delete the existing ones in the ``claims`` dict. If you want to add extra claims to some scopes you can use the ``OIDC_EXTRA_SCOPE_CLAIMS`` setting. + +How to add custom scopes and claims +=================================== + +The ``OIDC_EXTRA_SCOPE_CLAIMS`` setting is used to add extra scopes specific for your app. Is just a class that inherit from ``oidc_provider.lib.claims.ScopeClaims``. You can create or modify scopes by adding this methods into it: + +* ``info_scopename`` class property for setting the verbose name and description. +* ``scope_scopename`` method for returning some information related. + +Let's say that you want add your custom ``foo`` scope for your OAuth2/OpenID provider. So when a client (RP) makes an Authorization Request containing ``foo`` in the list of scopes, it will be listed in the consent page (``templates/oidc_provider/authorize.html``) and then some specific claims like ``bar`` will be returned from the ``/userinfo`` response. + +Somewhere in your Django ``settings.py``:: + + OIDC_USERINFO = 'yourproject.oidc_provider_settings.CustomScopeClaims' + +Inside your oidc_provider_settings.py file add the following class:: + + from django.utils.translation import ugettext as _ + from oidc_provider.lib.claims import ScopeClaims + + class CustomScopeClaims(ScopeClaims): + + info_foo = ( + _(u'Foo'), + _(u'Some description for the scope.'), + ) + + def scope_foo(self): + # self.user - Django user instance. + # self.userinfo - Dict returned by OIDC_USERINFO function. + # self.scopes - List of scopes requested. + dic = { + 'bar': 'Something dynamic here', + } + + return dic + + # If you want to change the description of the profile scope, you can redefine it. + info_profile = ( + _(u'Profile'), + _(u'Another description.'), + ) + +.. note:: + If a field is empty or ``None`` inside the dictionary your return on ``scope_scopename`` method, it will be cleaned from the response. diff --git a/docs/sections/settings.rst b/docs/sections/settings.rst index 4679a95..b4afc90 100644 --- a/docs/sections/settings.rst +++ b/docs/sections/settings.rst @@ -48,49 +48,10 @@ OIDC_EXTRA_SCOPE_CLAIMS OPTIONAL. ``str``. A string with the location of your class. Default is ``oidc_provider.lib.claims.ScopeClaims``. -Used to add extra scopes specific for your app. This class MUST inherit ``ScopeClaims``. +Used to add extra scopes specific for your app. OpenID Connect RP's will use scope values to specify what access privileges are being requested for Access Tokens. -OpenID Connect Clients will use scope values to specify what access privileges are being requested for Access Tokens. +Read more about how to implement it in :ref:`scopesclaims` section. -`Here `_ you have the standard scopes defined by the protocol. - -You can create or modify scopes using: - -* ``info_scopename`` class property for setting the verbose name and description. -* ``scope_scopename`` method for returning some information related. - -Check out an example of how to implement it:: - - from django.utils.translation import ugettext as _ - from oidc_provider.lib.claims import ScopeClaims - - class MyAppScopeClaims(ScopeClaims): - - info_books = ( - _(u'Books'), # Verbose name of the scope. - _(u'Access to your books.'), # Description of the scope. - ) - - def scope_books(self): - # Here, for example, you can search books for this user. - # self.user - Django user instance. - # self.userinfo - Instance of your custom OIDC_USERINFO class. - # self.scopes - List of scopes requested. - - dic = { - 'books_readed': books_readed_count, - } - - return dic - - # If you want to change the description of the profile scope, you can redefine it. - info_profile = ( - _(u'Profile'), - _(u'Another description.'), - ) - -.. note:: - If a field is empty or ``None`` inside the dictionary your return on ``scope_scopename`` method, it will be cleaned from the response. OIDC_IDTOKEN_EXPIRE ===================