Scopes and Claims

This subset of OpenID Connect defines a set of standard Claims. They are returned in the UserInfo Response.

The package comes with a setting called OIDC_USERINFO, basically it refers to a function that will be called with claims (dict) and user (user instance). It returns the claims dict with all the claims populated.

List of all the claims keys grouped by scopes:

profile email phone address
name email phone_number formatted
given_name email_verified phone_number_verified street_address
family_name     locality
middle_name     region
nickname     postal_code
preferred_username     country

How to populate standard claims

Somewhere in your Django

OIDC_USERINFO = 'myproject.oidc_provider_settings.userinfo'

Then inside your file create the function for the OIDC_USERINFO setting:

def userinfo(claims, user):
    # Populate claims dict.
    claims['name'] = '{0} {1}'.format(user.first_name, user.last_name)
    claims['given_name'] = user.first_name
    claims['family_name'] = user.last_name
    claims['email'] =
    claims['address']['street_address'] = '...'

    return claims

Now test an Authorization Request using these scopes openid profile email and see how user attributes are returned.


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 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

OIDC_EXTRA_SCOPE_CLAIMS = 'yourproject.oidc_provider_settings.CustomScopeClaims'

Inside your file add the following class:

from django.utils.translation import ugettext as _
from import ScopeClaims

class CustomScopeClaims(ScopeClaims):

    info_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.
        # self.client - Client requesting this claims.
        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'Another description.'),


If a field is empty or None inside the dictionary you return on the scope_scopename method, it will be cleaned from the response.