update documentation

.github/workflows/python-publish.yml

@@ -0,0 +1,40 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      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
-import successfactors_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 = successfactors_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

@@ -3,8 +3,8 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [project]
-name = "successfactors_auth"
+name = "successfactors-auth"
-version = "0.0.5"
+version = "0.0.10"
 authors = [
   { name="Ray Lyon", email="ray@raylyon.net" },
 ]
@@ -16,6 +16,11 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
 ]
+dependencies = [
+  "requests",
+  "lxml",
+  "xmlsec",
+]
 
 [project.urls]
 "Homepage" = "https://github.com/skoobasteeve/successfactors_auth"

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