Merge pull request #147 from mambelli/doc_generators

Added credential generators documentation

doc/frontend/configuration.html

@@ -108,9 +108,14 @@ <h3>Configuration</h3>
           <li><a href="#example">Example Configuration</a></li>
           <li><a href="#management">Frontend Configuration</a></li>
           <li><a href="#attr_singularity">Singularity attributes</a></li>
-          <li><a href="#custom_code">Customizing the glidein Startup</a></li>
+          <li><a href="#custom_code">Customizing the Glidein Startup</a></li>
           <li><a href="#attr_substitution">Attribute substitution</a></li>
           <li><a href="#multiple_proxy">Using multiple proxies</a></li>
+          <li>
+            <a href="#generator_plugin"
+              >Using the credential generator plugin</a
+            >
+          </li>
           <li><a href="#wmscollector">Using multiple wms collectors</a></li>
           <li>
             <a href="#usercollector"
@@ -242,17 +247,23 @@ <h2>Example Configuration</h2>
             <blockquote>
               <a href="#credentials">&lt;credentials&gt;</a><br />
               <blockquote>
-                <a href="#credentials"
-                  >&lt;credential absfname="/etc/osg/tokens/my_token.scitoken"
+                <a href="#credentials">
+                  &lt;credential absfname="/etc/osg/tokens/my_token.scitoken"
                   security_class="frontend" trust_domain="OSG" type="scitoken"
-                  comment="generated by osg-token-renewer" /&gt;</a
+                  comment="generated by osg-token-renewer" /&gt; </a
                 ><br />
-                <a href="#credentials"
-                  >&lt;credential Comment="deprecated, use scitoken if possible"
+                <a href="#credentials">
+                  &lt;credential generator="token_generator"
+                  security_class="frontend" trust_domain="OSG" type="scitoken"
+                  comment="python module w/ credential generator function, see
+                  the credential generator plug-in section" /&gt; </a
+                ><br />
+                <a href="#credentials">
+                  &lt;credential Comment="deprecated, use scitoken if possible"
                   absfname="/tmp/x509up_u" security_class="frontend"
                   trust_domain="OSG" type="grid_proxy" vm_id="123"
                   vm_type="type1" pool_idx_len="5" pool_idx_list="2,4-6,10"
-                  /&gt;</a
+                  /&gt; </a
                 ><br />
               </blockquote>
               <a href="#credentials">&lt;/credentials&gt;</a><br />
@@ -2140,11 +2151,73 @@ <h2>
                 absfname="/home/frontend/.globus/x509_pilot09_cms_prio.proxy"
                 security_class="cmsprio"/&gt;<br />
               </blockquote>
-              &lt;proxies&gt;<br />
+              &lt/credentials&gt;<br />
             </blockquote>
+            &lt;/security&gt;<br />
+          </blockquote>
+        </div>
+      </div>
+
+      <div class="section">
+        <a name="generator_plugin" />
+        <h2>Using the credential generator plug-in</h2>
+
+        <p>
+          Credential generators allow to generate credentials dynamically.
+          Instead of specifying a file, <tt>absfilename</tt>, you can specify a
+          <tt>generator</tt>, the name of a Python module somewhere in the
+          PYTHONPATH, e.g. in <tt>/etc/gwms-frontend/plugin.d/</tt>. Here is an
+          example of the credential configuration:
+        </p>
+        <div class="config">
+          <blockquote>
             &lt;security&gt;<br />
+            <blockquote>
+              &lt;credentials&gt;<br />
+              <blockquote>
+                &lt;credential type="token" trust_domain="OSG"
+                generator="mygenerator" security_class="cmsprio"/&gt;<br />
+              </blockquote>
+              &lt/credentials&gt;<br />
+            </blockquote>
+            &lt;/security&gt;<br />
           </blockquote>
         </div>
+        <p>
+          The generator module must contain a <tt>get_credential()</tt> function
+          with the same signature as the example below. A full example is in the
+          <a
+            href="https://github.com/glideinWMS/glideinwms/blob/master/plugins/scitokens_callout.py"
+          >
+            scitokens_callout.py</a
+          >
+          file in the GlideinWMS code repository.
+        </p>
+        <pre>
+# Example of credential generator function in the mygenerator.py file
+def get_credential(log: logger, group: str, entry: dict, trust_domain: str):
+    """Dynamically generates a credential given the parameters
+
+    Args:
+        log (logSupport): Python logger module passed by the caller
+        group (str): Frontend group
+        entry (dict): Factory entry information dictionary, containing at least:
+            name (str): the entry name, and
+            gatekeeper (str): the gatekeeper string
+        trust_domain (str): Credential trust domain
+        tkn_dir (str, optional): Directory where the tokens are stored. Defaults to "/var/lib/gwms-frontend/tokens.d".
+    Returns:
+        (str, int): tuple with:
+            credential, a string containing the token or whichever credential is returned
+            lifetime, seconds of remaining lifetime
+    Raises:
+        KeyError: missing some information to generate the credential
+        ValueError: could not generate the credential
+    """
+    # Invoke a shell script or internally generate the credential
+    credential = "credential content"
+    return credential, 3600
+        </pre>
       </div>
 
       <div class="section">
@@ -2169,9 +2242,9 @@ <h2 class="western">
         <p>
           The Factory setting and the actual availability of singularity and an
           image will also affect the actual use of Singularity. See the
-          <a href="../factory/configuration.html#singularity"
-            >Factory configuration document</a
-          >
+          <a href="../factory/configuration.html#singularity">
+            Factory configuration document
+          </a>
           for a table of how Singularity is negotiated with the entries using
           GLIDEIN_Singularity_Use and GLIDEIN_SINGULARITY_REQUIRE (the entry
           variable) to decide wether the Glidein can run there and should use
@@ -2267,9 +2340,9 @@ <h2 class="western">
               value="/vo_files,/src_path:/dst_path"/>.
             </blockquote>
             See the
-            <a href="../factory/custom_vars.html#singularity_vars"
-              >custom variables file</a
-            >
+            <a href="../factory/custom_vars.html#singularity_vars">
+              custom variables file
+            </a>
             for more information about the bind mounts.
           </li>
           <li>
@@ -2279,9 +2352,9 @@ <h2 class="western">
         </ul>
 
         The
-        <a href="../factory/custom_vars.html#singularity_vars"
-          >custom variables file</a
-        >
+        <a href="../factory/custom_vars.html#singularity_vars">
+          custom variables file
+        </a>
         contains a reference of all the Singularity attributes used in the
         Frontend, Factory or Glidein.
       </div>
@@ -2315,9 +2388,9 @@ <h2 class="western">
         <a name="xsltplugins" />
         <h3 class="western">XSLT Plugins to extend configuration</h3>
         This is explained in the
-        <a href="../factory/configuration.html#xsltplugins"
-          >Factory configuration documentation.</a
-        >
+        <a href="../factory/configuration.html#xsltplugins">
+          Factory configuration documentation.
+        </a>
         <p></p>
       </div>
 

frontend/glideinFrontendElement.py

@@ -1024,7 +1024,7 @@ def generate_credential(self, elementDescript, glidein_el, group_name, trust_dom
         """
 
         ### The credential generator plugin should define the following function:
-        # def get_credential(log:logger, group:str, dentry:dict{name:str, gatekeeper:str}, trust_domain:str):
+        # def get_credential(log:logger, group:str, entry:dict{name:str, gatekeeper:str}, trust_domain:str):
         # Generates a credential given the parameter
 
         # Args:

plugins/scitokens_callout.py

@@ -29,17 +29,21 @@ def get_credential(logger, group, entry, trust_domain, tkn_dir="/var/lib/gwms-fr
     caching here so that new tokens are only generated when required.
 
     Args:
-        logger (logSupport): Logger module
+        logger (logSupport): Python logger module passed by the caller
         group (str): Frontend group
-        entry (str): Factory entry
+        entry (dict): Factory entry information dictionary, containing at least:
+            name (str): the entry name, and
+            gatekeeper (str): the gatekeeper string
         trust_domain (str): Credential trust domain
         tkn_dir (str, optional): Directory where the tokens are stored. Defaults to "/var/lib/gwms-frontend/tokens.d".
 
-    Raises:
-        err: If the token could not be generated.
-
     Returns:
-        (str, int): The token string and the lifetime of the token.
+        (str, int): tuple with:
+            credential, a string containing the token or whichever credential is returned
+            lifetime, seconds of remaining lifetime
+    Raises:
+        KeyError: missing some information to generate the credential
+        ValueError: could not generate the credential
     """
 
     key_file = "/etc/condor/scitokens.pem"