update documentation

.github/workflows/python-publish.yml

@@ -11,6 +11,7 @@ name: Upload Python Package
 on:
   release:
     types: [published]
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -33,7 +34,7 @@ jobs:
     - name: Build package
       run: python -m build
     - name: Publish package
-      uses: pypa/gh-action-pypi-publish@v1
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}

README.md

@@ -1,6 +1,16 @@
 # SuccessFactors Auth
 Authenticate with the SAP SuccessFactors API with OAuth2 and Python.
 
+## Dependencies
+
+- xmlsec
+- requests
+
+## System Requirements
+
+- libxml2 >= 2.9.1
+- libxmlsec1 >= 1.2.18
+
 ## How to use
 
 1. Create an OAuth application in SuccessFactors.
@@ -9,8 +19,10 @@ Authenticate with the SAP SuccessFactors API with OAuth2 and Python.
    ``` shell
    pip install successfactors_auth
    ```
+   Depending on your OS, you may need to install additional system packages, see [xmlsec documentation](https://pypi.org/project/xmlsec/).  
+   **Note for macOS users:** There is a bug that prevents you from installing xmlsec with Homebrew, currently tracked in a [Github issue](https://github.com/xmlsec/python-xmlsec/issues/254). There are some workaround you can try, but in the mean time it may be easier to install within a container or VM.
 4. Import `successfactors_auth` into your Python >=3.9 project.
-5. Call the `successfactors_auth.auth()` function in your Python project. You'll need to pass the following parameters:
+5. Call the `successfactors_auth.get_token()` function in your Python project. You'll need to pass the following parameters:
     - `sf_url`: Base API url of your SuccessFactors instance, e.g. "https://api55.sapsf.eu".
     - `sf_company_id`: SuccessFactors company ID.
     - `sf_oauth_client_id`: The Client ID for the OAuth application you created earlier.
@@ -23,22 +35,21 @@ Authenticate with the SAP SuccessFactors API with OAuth2 and Python.
 #!/usr/bin/env python
 
 import requests
-from successfactors_auth import auth as sf_auth
+import successfactors_auth as sf
 
 sf_url = 'https://your.base.url.com'
 sf_company_id = 'your-company-id'
 sf_oauth_client_id = 'your_app_client_id'
 sf_admin_user = 'your_admin_user'
-sf_saml_private_key = 'your_app_private_key.pem'
+sf_saml_private_key = 'app_private_key_file.pem'
 
-token = sf_auth.auth(
+token = sf.get_token(
-    sf_url,
+    sf_company_id=company_id,
-    sf_company_id,
+    sf_oauth_client_id=oauth_client_id,
-    sf_oauth_client_id,
+    sf_admin_user=admin_api_user,
-    sf_admin_user,
+    sf_saml_private_key=oauth_private_key,
-    sf_saml_private_key,
+    sf_url=url
-    sf_saml_template
+)
-    )
 
 headers = {
     "Accept: application/json",
@@ -59,4 +70,4 @@ Once you get authenticated, getting the information you want is a whole new leve
 
 ## Contributing
 
-All contributions welcome! Feel free to file an [issue](https://github.com/skoobasteeve/successfactors_auth/issues) or open a [pull request](https://github.com/skoobasteeve/successfactors_auth/pulls).
+All contributions welcome! Feel free to file an [issue](https://github.com/skoobasteeve/successfactors_auth/issues) or open a [pull request](https://github.com/skoobasteeve/successfactors_auth/pulls).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "successfactors-auth"
-version = "0.0.8"
+version = "0.0.10"
 authors = [
   { name="Ray Lyon", email="ray@raylyon.net" },
 ]

src/successfactors_auth/__init__.py

@@ -0,0 +1 @@
+from .auth import get_token

src/successfactors_auth/auth.py

@@ -42,8 +42,8 @@ from lxml import etree
 from . import templates
 
 
-def get_access_token(sf_url: str, company_id: str, client_id: str,
+def request_token(sf_url: str, company_id: str, client_id: str,
-                     assertion: str) -> str:
+                  assertion: str) -> str:
     """
     Send POST request to SuccessFactors containing the generated
     SAML assertion and other details, then receive a token in response
@@ -113,8 +113,8 @@ def sign_assertion(xml_string: str, private_key: str) -> str:
     return etree.tostring(root)
 
 
-def auth(sf_url: str, sf_company_id: str, sf_oauth_client_id: str,
+def get_token(sf_url: str, sf_company_id: str, sf_oauth_client_id: str,
-         sf_admin_user: str, sf_saml_private_key: str) -> str:
+              sf_admin_user: str, sf_saml_private_key: str) -> str:
     """
     Request an API access token by generating a signed SAML assertion
     and using it to authenticate with SuccessFactors.
@@ -135,9 +135,9 @@ def auth(sf_url: str, sf_company_id: str, sf_oauth_client_id: str,
     signed_assertion_b64 = base64.b64encode(signed_assertion).replace(b'\n', b'')
 
     # Request the API token from SuccessFactors via a POST request
-    access_token = get_access_token(sf_url,
+    access_token = request_token(sf_url,
-                                    sf_company_id,
+                                 sf_company_id,
-                                    sf_oauth_client_id,
+                                 sf_oauth_client_id,
-                                    signed_assertion_b64)
+                                 signed_assertion_b64)
 
     return access_token