How it works?

1. If the user tries to perform a log in and it's not currently logged in, a 401 exception is raised by the login function of the plugin.py file. Under this circumstances, is the function challenge called. This function will only redirect the user to the OAuth2 Server log in page when a login attempt is performed. The challenge function ignores the 401 exceptions raised because the user doesn't have grants to perform an operation.
2. Once that the user completes the log in, he or she is redirected to the page /oauth2/callback of the CKAN instance. In this case, the identify function of the repozewho.py file captures the request and tries to get the OAuth2 token. If the operation can be performed without exceptions, the authenticate function will be executed with the value returned by the identify function. Otherwise, a message error will be shown.
3. The authenticate function should return the user identifier. To do so, the function asks for the basic user information to the OAuth2 server with the token returned by the identify function. Once that the user identifier is got, the user model is asked for that user. If the user does not exist, it's created. Otherwise, the user is updated. Finally the function returns the user identifier.
4. Then, the remember function is called to set the cookies that allow the system to identify the user without performing another login attempt.
5. The identify function of the plugin.py file read the property repoze.who.identity from the request environ. This variable is automatically set using the cookies stored by the authenticate process explained above. If the user is logged, this variable contains the user identifier. In this case, the variable toolkit.c.user is set to the user identifier. Otherwise, the variable is set to None.