add comments for get_auth_properties method

tokendito/okta.py

@@ -84,26 +84,38 @@ def api_error_code_parser(status=None):
 
 
 def get_auth_properties(userid=None, url=None, user_agent="Tokendito"):
-    """Make a call to the webfinger endpoint."""
+    """
+    Make a call to the Okta webfinger endpoint to retrieve authentication properties.
+
+    :param userid: User's ID for which we are requesting an auth endpoint.
+    :param url: Okta organization URL where we are looking up the user.
+    :param user_agent: User-Agent header value for the HTTP request.
+    :returns: Dictionary containing authentication properties.
+    """
 
+    # Create an HTTP client instance with the specified user agent.
     http_client = HTTPClient(user_agent)
 
+    # Prepare the payload for the webfinger endpoint request.
     payload = {"resource": f"okta:acct:{userid}", "rel": "okta:idp"}
     headers = {"accept": "application/jrd+json"}
     url = f"{url}/.well-known/webfinger"
 
     logger.debug(f"Looking up auth endpoint for {userid} in {url}")
+
+    # Make a GET request to the webfinger endpoint.
     response = http_client.get(url, params=payload, headers=headers)
 
+    # Extract properties from the response.
     try:
         ret = response.json()["links"][0]["properties"]
     except (KeyError, ValueError) as e:
         logger.error(f"Failed to parse authentication type in {url}:{str(e)}")
         logger.debug(f"Response: {response.text}")
         sys.exit(1)
 
-    # Try to get metadata, type, and ID if available, but ensure
-    # that a dictionary with the correct keys is returned.
+    # Extract specific authentication properties if available.
+    # Return a dictionary with 'metadata', 'type', and 'id' keys.
     properties = {}
     properties["metadata"] = ret.get("okta:idp:metadata", None)
     properties["type"] = ret.get("okta:idp:type", None)
@@ -113,6 +125,7 @@ def get_auth_properties(userid=None, url=None, user_agent="Tokendito"):
     return properties
 
 
+
 def get_saml_request(auth_properties):
     """
     Get a SAML Request object from the Service Provider, to be submitted to the IdP.