Merge pull request #5397 from TaykYoku/integration_oauth_p01_docs

[8.0] add dirac-login user guide, code docs

Author: fstagni

docs/source/AdministratorGuide/UserManagement/index.rst

@@ -9,10 +9,9 @@ This section provides information you need for the user management.
 What are the components involved in that.
 -----------------------------------------
 
-  * Configuration system
-
-   * Registry
-   * VOMS2CSAgent
+  - Configuration system
+  - Registry
+  - VOMS2CSAgent
 
 
 What is the user in DIRAC context?
@@ -40,12 +39,12 @@ However, having these names the same can avoid confusions at the expense of havi
 Consider the registration process
 ---------------------------------
 
-User management has been provided by the Registry section of the Configuration System. To manage it you can use:
+User management is handled within the Registry section of the Configuration System. To manage it you can use:
 
-* :ref:`dirac commands <admin_registry_cmd>` to managing Registry
-* configuration manager application in the Web portal (need to :ref:`install WebAppDIRAC extension <installwebappdirac>`)
-* modify local cfg file manually (by default it located in /opt/dirac/etc/dirac.cfg)
-* use the :mod:`~DIRAC.ConfigurationSystem.Agent.VOMS2CSAgent` to fetch VOMS VO users
+  - :ref:`dirac commands <admin_registry_cmd>` for managing Registry
+  - configuration manager application in the Web portal (need to :ref:`install WebAppDIRAC extension <installwebappdirac>`)
+  - modify local cfg file manually (by default it is located in /opt/dirac/etc/dirac.cfg)
+  - use the :mod:`~DIRAC.ConfigurationSystem.Agent.VOMS2CSAgent` to fetch VOMS VO users
 
 In a nutshell, how to edit the configuration from the portal. First, it should be noted that to be able to do this,
 you must be an already registered user in a group that has the appropriate permission to edit the configuration("CSAdministrator").

docs/source/UserGuide/GettingStarted/GettingUserIdentity/index.rst

@@ -19,7 +19,7 @@ The user will be prompted for the password used while exporting the certificate
 to be used with the user's private key. Do not forget it !
 
 Registration with DIRAC
--------------------------
+-----------------------
 
 Users are always working in the Grid as members of some User Community. Therefore, every user must be registered
 with the Community DIRAC instance. You should ask the DIRAC administrators to do that, the procedure can
@@ -30,7 +30,7 @@ determines the user rights for various Grid operations. Each DIRAC installation
 group to which the users are attributed when the group is not explicitly specified.
 
 Proxy initialization
------------------------
+--------------------
 
 Users authenticate with DIRAC services, and therefore with the Grid services that DIRAC expose via "proxies",
 which you can regard as a product of personal certificates.
@@ -53,3 +53,33 @@ If another non-default user group is needed, the command becomes::
   $ dirac-proxy-init -g <user_group>
 
 where ``user_group`` is the desired DIRAC group name for which the user is entitled.
+
+.. versionadded:: 8.0
+   added the possibility to generate proxy with new `dirac-login` command, use *--help* switch for more information. E.g.: dirac-login <user_group>
+
+Token authorization
+-------------------
+
+Starting with the 8.0 version of DIRAC, it is possible to authorize users through third party Identity Providers (IdP),
+such as `EGI Checkin <https://www.egi.eu/services/check-in/>`_ or `WLCG IAM <https://indigo-iam.github.io/v/current/>`_.
+You do not need a certificate for this in a terminal, but you must be registered in one of the supported IdP. The registration process is different for each IdP.
+
+Once your account is created, you will be able to register with DIRAC Authorization Server using *--use-diracas* switch of the `dirac-login` command::
+
+  dirac-login <user_group> --use-diracas
+
+You can request to return the access token instead of a proxy using *--token* key::
+
+  dirac-login <user_group> --token
+
+But since not all services currently support tokens, you can get a proxy if you use the *--proxy* key::
+
+  dirac-login <user_group> --proxy --use-diracas
+
+.. note:: if you want to get a proxy after logging in to DIRAC Authorization Server you must first put it in DIRAC, see "Proxy initialization".
+
+If you need to end the work session in this way to remove the received access token and related information, then use the following::
+
+  dirac-logout
+
+This command will revoke your local access token.

src/DIRAC/FrameworkSystem/Client/ProxyManagerClient.py

@@ -653,15 +653,18 @@ def getVOMSAttributes(self, chain):
         """
         return VOMS().getVOMSAttributes(chain)
 
-    def getUploadedProxyLifeTime(self, DN, group):
+    def getUploadedProxyLifeTime(self, DN, group=None):
         """Get the remaining seconds for an uploaded proxy
 
         :param str DN: user DN
         :param str group: group
 
         :return: S_OK(int)/S_ERROR()
         """
-        result = self.getDBContents({"UserDN": [DN], "UserGroup": [group]})
+        parameters = dict(UserDN=[DN])
+        if group:
+            parameters["UserGroup"] = [group]
+        result = self.getDBContents(parameters)
         if not result["OK"]:
             return result
         data = result["Value"]

src/DIRAC/FrameworkSystem/DB/AuthDB.py

@@ -1,9 +1,5 @@
-""" Auth class is a front-end to the Auth Database
+""" AuthDB class is a front-end to the AuthDB MySQL Database (via SQLAlchemy)
 """
-from __future__ import absolute_import
-from __future__ import division
-from __future__ import print_function
-
 import json
 import time
 import pprint
@@ -13,16 +9,13 @@
 from sqlalchemy.orm.exc import MultipleResultsFound, NoResultFound
 from sqlalchemy.ext.declarative import declarative_base
 
-import authlib
 from authlib.jose import KeySet, JsonWebKey
 from authlib.common.security import generate_token
 
 from DIRAC import S_OK, S_ERROR
 from DIRAC.Core.Base.SQLAlchemyDB import SQLAlchemyDB
 from DIRAC.FrameworkSystem.private.authorization.utils.Tokens import OAuth2Token
 
-__RCSID__ = "$Id$"
-
 
 Model = declarative_base()
 

src/DIRAC/FrameworkSystem/private/authorization/AuthServer.py

@@ -1,8 +1,4 @@
 """ This class provides authorization server activity. """
-from __future__ import absolute_import
-from __future__ import division
-from __future__ import print_function
-
 import re
 import six
 import json
@@ -44,34 +40,48 @@
 class AuthServer(_AuthorizationServer):
     """Implementation of the :class:`authlib.oauth2.rfc6749.AuthorizationServer`.
 
+    This framework has been changed and simplified to be used for DIRAC purposes,
+    namely authorization on the third party side and saving the received extended
+    long-term access tokens on the DIRAC side with the possibility of their future
+    use on behalf of the user without his participation.
+
+    The idea is that DIRAC itself is not an identity provider and relies on third-party
+    resources such as EGI Checkin or WLCG IAM.
+
     Initialize::
 
       server = AuthServer()
     """
 
     LOCATION = None
-    REFRESH_TOKEN_EXPIRES_IN = 24 * 3600
 
     def __init__(self):
-        self.db = AuthDB()
+        self.db = AuthDB()  # place to store session information
+        self.log = sLog
         self.idps = IdProviderFactory()
-        self.proxyCli = ProxyManagerClient()
-        self.tokenCli = TokenManagerClient()
+        self.proxyCli = ProxyManagerClient()  # take care about proxies
+        self.tokenCli = TokenManagerClient()  # take care about tokens
+        # The authorization server has its own settings, but they are standardized
         self.metadata = collectMetadata()
         self.metadata.validate()
-        # args for authlib < 1.0.0: (query_client=self.query_client, save_token=None, metadata=self.metadata)
-        # for authlib >= 1.0.0:
+        # Initialize AuthorizationServer
         _AuthorizationServer.__init__(self, scopes_supported=self.metadata["scopes_supported"])
-        # Skip authlib method save_token and send_signal
+        # authlib requires the following methods:
+        # The following `save_token` method is called when requesting a new access token to save it after it is generated.
+        # Let's skip this step, because getting tokens and saving them if necessary has already taken place in `generate_token` method.
         self.save_token = lambda x, y: None
+        # Framework integration can re-implement this method to support signal system.
+        # But in this implementation, this system is not used.
         self.send_signal = lambda *x, **y: None
+        # The main method that will return an access token to the user (this can be a proxy)
         self.generate_token = self.generateProxyOrToken
         # Register configured grants
-        self.register_grant(RefreshTokenGrant)
+        self.register_grant(RefreshTokenGrant)  # Enable refreshing tokens
+        # Enable device code flow
         self.register_grant(DeviceCodeGrant)
         self.register_endpoint(DeviceAuthorizationEndpoint)
-        self.register_endpoint(RevocationEndpoint)
-        self.register_grant(AuthorizationCodeGrant, [CodeChallenge(required=True)])
+        self.register_endpoint(RevocationEndpoint)  # Enable revokation tokens
+        self.register_grant(AuthorizationCodeGrant, [CodeChallenge(required=True)])  # Enable authorization code flow
 
     # pylint: disable=method-hidden
     def query_client(self, client_id):
@@ -86,15 +96,11 @@ def query_client(self, client_id):
         for cli in clients:
             if client_id == clients[cli]["client_id"]:
                 gLogger.debug("Found %s client:\n" % cli, pprint.pformat(clients[cli]))
+                # Authorization successful
                 return Client(clients[cli])
+        # Authorization failed, client not found
         return None
 
-    def addSession(self, session):
-        self.db.addSession(session)
-
-    def getSession(self, session):
-        self.db.getSession(session)
-
     def _getScope(self, scope, param):
         """Get parameter scope
 
@@ -111,29 +117,44 @@ def _getScope(self, scope, param):
     def generateProxyOrToken(
         self, client, grant_type, user=None, scope=None, expires_in=None, include_refresh_token=True
     ):
-        """Generate proxy or tokens after authorization"""
+        """Generate proxy or tokens after authorization
+
+        :param client: instance of the IdP client
+        :param grant_type: authorization grant type (unused)
+        :param str user: user identificator
+        :param str scope: requested scope
+        :param expires_in: when the token should expire (unused)
+        :param bool include_refresh_token: to include refresh token (unused)
+
+        :return: dict or str -- will return tokens as dict or proxy as string
+        """
+        # Read requested scopes
         group = self._getScope(scope, "g")
         lifetime = self._getScope(scope, "lifetime")
+        # Found provider name for group
         provider = getIdPForGroup(group)
 
-        # Search DIRAC username
+        # Search DIRAC username by user ID
         result = getUsernameForDN(wrapIDAsDN(user))
         if not result["OK"]:
             raise OAuth2Error(result["Message"])
         userName = result["Value"]
 
+        # User request a proxy
         if "proxy" in scope_to_list(scope):
             # Try to return user proxy if proxy scope present in the authorization request
             if not isDownloadablePersonalProxy():
                 raise OAuth2Error("You can't get proxy, configuration(downloadablePersonalProxy) not allow to do that.")
-            sLog.debug(
-                "Try to query %s@%s proxy%s" % (user, group, ("with lifetime:%s" % lifetime) if lifetime else "")
+            self.log.debug(
+                "Try to query %s@%s proxy%s" % (user, group, (" with lifetime:%s" % lifetime) if lifetime else "")
             )
+            # Get user DNs
             result = getDNForUsername(userName)
             if not result["OK"]:
                 raise OAuth2Error(result["Message"])
             userDNs = result["Value"]
             err = []
+            # Try every DN to generate a proxy
             for dn in userDNs:
                 sLog.debug("Try to get proxy for %s" % dn)
                 if lifetime:
@@ -147,24 +168,27 @@ def generateProxyOrToken(
                     result = result["Value"].dumpAllToString()
                     if not result["OK"]:
                         raise OAuth2Error(result["Message"])
+                    # Proxy generated
                     return {
                         "proxy": result["Value"].decode() if isinstance(result["Value"], bytes) else result["Value"]
                     }
+            # Proxy cannot be generated or not found
             raise OAuth2Error("; ".join(err))
 
+        # User request a tokens
         else:
             # Ask TokenManager to generate new tokens for user
             result = self.tokenCli.getToken(userName, group)
             if not result["OK"]:
                 raise OAuth2Error(result["Message"])
             token = result["Value"]
-
             # Wrap the refresh token and register it to protect against reuse
             result = self.registerRefreshToken(
                 dict(sub=user, scope=scope, provider=provider, azp=client.get_client_id()), token
             )
             if not result["OK"]:
                 raise OAuth2Error(result["Message"])
+            # Return tokens as dictionary
             return result["Value"]
 
     def __signToken(self, payload):
@@ -223,7 +247,7 @@ def registerRefreshToken(self, payload, token):
         return S_OK(token)
 
     def getIdPAuthorization(self, provider, request):
-        """Submit subsession and return dict with authorization url and session number
+        """Submit subsession to authorize with chosen provider and return dict with authorization url and session number
 
         :param str provider: provider name
         :param object request: main session request
@@ -271,14 +295,14 @@ def parseIdPAuthorizationResponse(self, response, session):
         # Is ID registred?
         result = getUsernameForDN(credDict["DN"])
         if not result["OK"]:
-            comment = "Your ID is not registred in the DIRAC: %s." % credDict["ID"]
+            comment = "ID %s is not registred in DIRAC." % credDict["ID"]
             payload.update(idpObj.getUserProfile().get("Value", {}))
             result = self.__registerNewUser(providerName, payload)
 
             if result["OK"]:
-                comment += " Administrators have been notified about you."
+                comment += "Administrators have been notified about you."
             else:
-                comment += " Please, contact the DIRAC administrators."
+                comment += "Please, contact the DIRAC administrators."
 
             # Notify user about problem
             html = getHTML("unregistered user!", info=comment, theme="warning")
@@ -293,16 +317,20 @@ def parseIdPAuthorizationResponse(self, response, session):
         return S_OK(credDict) if result["OK"] else result
 
     def create_oauth2_request(self, request, method_cls=OAuth2Request, use_json=False):
-        sLog.debug("Create OAuth2 request", "with json" if use_json else "")
+        """Parse request. Rewrite authlib method."""
+        self.log.debug("Create OAuth2 request", "with json" if use_json else "")
         return createOAuth2Request(request, method_cls, use_json)
 
     def create_json_request(self, request):
+        """Parse request. Rewrite authlib method."""
         return self.create_oauth2_request(request, HttpRequest, True)
 
     def validate_requested_scope(self, scope, state=None):
         """See :func:`authlib.oauth2.rfc6749.authorization_server.validate_requested_scope`"""
         # We also consider parametric scope containing ":" charter
-        extended_scope = list_to_scope([re.sub(r":.*$", ":", s) for s in scope_to_list(scope or "")])
+        extended_scope = list_to_scope(
+            [re.sub(r":.*$", ":", s) for s in scope_to_list((scope or "").replace("+", " "))]
+        )
         super(AuthServer, self).validate_requested_scope(extended_scope, state)
 
     def handle_response(self, status_code=None, payload=None, headers=None, newSession=None, delSession=None):