pyxecm 3.8.2__tar.gz → 3.8.3__tar.gz

{pyxecm-3.8.2 → pyxecm-3.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyxecm
-Version: 3.8.2
+Version: 3.8.3
 Summary: A Python library to interact with Opentext Content Management Rest API
 Project-URL: Homepage, https://github.com/opentext/pyxecm
 Author-email: Kai Gatzweiler <kgatzweiler@opentext.com>, "Dr. Marc Diefenbruch" <mdiefenb@opentext.com>

{pyxecm-3.8.2 → pyxecm-3.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyxecm"
-version = "3.8.2"
+version = "3.8.3"
 description = 'A Python library to interact with Opentext Content Management Rest API'
 keywords = [
   'opentext',

{pyxecm-3.8.2 → pyxecm-3.8.3}/src/pyxecm_customizer/guidewire.py

@@ -1541,9 +1541,7 @@ class Guidewire:
         policies = response.get("data", [])
         if filter_field and filter_value is not None and isinstance(policies, list):
             response["data"] = [
-                policy
-                for policy in policies
-                if policy.get("attributes", {}).get(filter_field) == filter_value
+                policy for policy in policies if policy.get("attributes", {}).get(filter_field) == filter_value
             ]
             response["count"] = len(response["data"])
 

{pyxecm-3.8.2 → pyxecm-3.8.3}/src/pyxecm_customizer/sap.py

@@ -119,6 +119,8 @@ from lxml import etree
 from pydantic import BaseModel, ValidationError
 
 from .sap_models import (
+    SAPAuthCheckState,
+    SAPAuthCheckStatusModel,
     SAPBusinessPartnerQueryModel,
     SAPBusinessPartnerResponseModel,
     SAPCompanyCodeQueryModel,
@@ -302,7 +304,8 @@ ODATA_V4_SERVICE_ROOT_PATTERN = re.compile(r"^(.*?/sap/opu/odata4/(?:[^/]+/){5}\
 
 
 # Registry of the OData services this module uses. Extend this if
-# new SAP APIs are supported by the SAP class:
+# new SAP APIs are supported by the SAP class. The OAuth scope IDs are
+# generated by SAP and can differ between SAP systems - see get_oauth_scope():
 SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
     "API_MAINTENANCEORDER": SAPODataServiceModel(
         name="API_MAINTENANCEORDER",
@@ -310,6 +313,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         # deprecated version 0001 - both are identical for the fields we use:
         path="/sap/opu/odata/sap/API_MAINTENANCEORDER;v=0002",
         odata_version=2,
+        oauth_scope="ZAPI_MAINTENANCEORDER_0002",
         entity_sets=["MaintenanceOrder", "MaintenanceOrderOperation"],
         description="Plant Maintenance - Maintenance Order (Create, Read, Update)",
     ),
@@ -318,6 +322,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_MAINTNOTIFICATION",
         path="/sap/opu/odata/sap/API_MAINTNOTIFICATION",
         odata_version=2,
+        oauth_scope="ZAPI_MAINTNOTIFICATION_0001",
         entity_sets=["MaintenanceNotification", "MaintenanceNotificationItem"],
         description="Plant Maintenance - Maintenance Notification (Create, Read, Update)",
     ),
@@ -325,6 +330,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_SALES_ORDER_SRV",
         path="/sap/opu/odata/sap/API_SALES_ORDER_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_SALES_ORDER_SRV_0001",
         entity_sets=["A_SalesOrder", "A_SalesOrderItem"],
         description="Sales - Sales Order (Create, Read, Update, Delete)",
     ),
@@ -332,6 +338,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_SALES_CONTRACT_SRV",
         path="/sap/opu/odata/sap/API_SALES_CONTRACT_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_SALES_CONTRACT_SRV_0001",
         entity_sets=["A_SalesContract", "A_SalesContractItem"],
         description="Sales - Sales Contract (Create, Read, Update, Delete)",
     ),
@@ -341,6 +348,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PURCHASECONTRACT_PROCESS_SRV",
         path="/sap/opu/odata/sap/API_PURCHASECONTRACT_PROCESS_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_PURCHASECONTRACT_PROCESS_SRV_0001",
         entity_sets=["A_PurchaseContract", "A_PurchaseContractItem"],
         description="Purchasing - Purchase Contract (Create, Read, Update)",
     ),
@@ -350,6 +358,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PURCHASEREQUISITION_2",
         path="/sap/opu/odata4/sap/api_purchaserequisition_2/srvd_a2x/sap/purchaserequisition/0001",
         odata_version=4,
+        oauth_scope="OV4:API_PURCHASEREQUISITION_2",
         entity_sets=["PurchaseReqn", "PurchaseReqnItem", "PurchaseReqnAcctAssgmt"],
         description="Purchasing - Purchase Requisition (Create, Read, Update)",
     ),
@@ -357,6 +366,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_MATERIAL_DOCUMENT_SRV",
         path="/sap/opu/odata/sap/API_MATERIAL_DOCUMENT_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_MATERIAL_DOCUMENT_SRV_0001",
         entity_sets=["A_MaterialDocumentHeader", "A_MaterialDocumentItem"],
         description="Inventory Management - Goods Movement / Material Document (Create, Read, Cancel)",
     ),
@@ -365,6 +375,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_MAINTORDERCONFIRMATION",
         path="/sap/opu/odata/sap/API_MAINTORDERCONFIRMATION",
         odata_version=2,
+        oauth_scope="ZAPI_MAINTORDERCONFIRMATION_0001",
         entity_sets=["MaintOrderConfirmation"],
         description="Plant Maintenance - Maintenance Order Confirmation (Create, Read, Cancel)",
     ),
@@ -372,6 +383,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_MAINTENANCEPLAN",
         path="/sap/opu/odata/sap/API_MAINTENANCEPLAN",
         odata_version=2,
+        oauth_scope="ZAPI_MAINTENANCEPLAN_0001",
         entity_sets=["MaintenancePlan", "MaintenancePlanCycle", "MaintenanceItem"],
         description="Plant Maintenance - Maintenance Plan (Create, Read, Update, Scheduling)",
     ),
@@ -381,6 +393,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PLANNEDORDER",
         path="/sap/opu/odata4/sap/api_plannedorder/srvd_a2x/sap/plannedorder/0001",
         odata_version=4,
+        oauth_scope="OV4:API_PLANNEDORDER",
         entity_sets=["PlannedOrderHeader"],
         description="Production Planning - Planned Order (Create, Read, Update, Delete, Schedule)",
     ),
@@ -388,6 +401,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PRODUCTION_ORDER_2_SRV",
         path="/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_PRODUCTION_ORDER_2_SRV_0001",
         entity_sets=["A_ProductionOrder_2", "A_ProductionOrderOperation_2", "A_ProductionOrderStatus_2"],
         description="Production Planning - Production Order (Create, Read, Update, Convert, Status)",
     ),
@@ -396,6 +410,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PLANT_2",
         path="/sap/opu/odata4/sap/api_plant_2/srvd_a2x/sap/plant/0001",
         odata_version=4,
+        oauth_scope="OV4:API_PLANT_2",
         entity_sets=["Plant"],
         description="Master Data - Plant (Read)",
     ),
@@ -403,6 +418,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_STORAGELOCATION_SRV",
         path="/sap/opu/odata/sap/API_STORAGELOCATION_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_STORAGELOCATION_SRV_0001",
         entity_sets=["StorageLocation"],
         description="Master Data - Storage Location (Read)",
     ),
@@ -410,6 +426,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PRODUCT_SRV",
         path="/sap/opu/odata/sap/API_PRODUCT_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_PRODUCT_SRV_0001",
         entity_sets=["A_Product", "A_ProductPlant", "A_ProductDescription"],
         description="Master Data - Product / Material (Read)",
     ),
@@ -417,6 +434,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PRODUCTION_VERSION",
         path="/sap/opu/odata4/sap/api_production_version/srvd_a2x/sap/productionversion/0001",
         odata_version=4,
+        oauth_scope="OV4:API_PRODUCTION_VERSION",
         entity_sets=["ProductionVersion"],
         description="Master Data - Production Version (Read)",
     ),
@@ -424,6 +442,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_WORK_CENTERS",
         path="/sap/opu/odata/sap/API_WORK_CENTERS",
         odata_version=2,
+        oauth_scope="ZAPI_WORK_CENTERS_0001",
         entity_sets=["A_WorkCenters"],
         description="Master Data - Work Center (Read)",
     ),
@@ -431,6 +450,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_EQUIPMENT",
         path="/sap/opu/odata/sap/API_EQUIPMENT",
         odata_version=2,
+        oauth_scope="ZAPI_EQUIPMENT_0001",
         entity_sets=["Equipment"],
         description="Master Data - Equipment (Read)",
     ),
@@ -438,6 +458,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_FUNCTIONALLOCATION",
         path="/sap/opu/odata/sap/API_FUNCTIONALLOCATION",
         odata_version=2,
+        oauth_scope="ZAPI_FUNCTIONALLOCATION_0001",
         entity_sets=["FunctionalLocation"],
         description="Master Data - Functional Location (Read)",
     ),
@@ -445,6 +466,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_BUSINESS_PARTNER",
         path="/sap/opu/odata/sap/API_BUSINESS_PARTNER",
         odata_version=2,
+        oauth_scope="ZAPI_BUSINESS_PARTNER_0001",
         entity_sets=["A_BusinessPartner", "A_BusinessPartnerRole"],
         description="Master Data - Business Partner (Read)",
     ),
@@ -452,6 +474,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_COMPANYCODE_SRV",
         path="/sap/opu/odata/sap/API_COMPANYCODE_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_COMPANYCODE_SRV_0001",
         entity_sets=["A_CompanyCode"],
         description="Master Data - Company Code (Read)",
     ),
@@ -459,6 +482,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_SALESORGANIZATION_SRV",
         path="/sap/opu/odata/sap/API_SALESORGANIZATION_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_SALESORGANIZATION_SRV_0001",
         entity_sets=["A_SalesOrganization"],
         description="Master Data - Sales Organization (Read)",
     ),
@@ -466,6 +490,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PURCHASINGORGANIZATION",
         path="/sap/opu/odata4/sap/api_purchasingorganization/srvd_a2x/sap/purchasingorganization/0001",
         odata_version=4,
+        oauth_scope="OV4:API_PURCHASINGORGANIZATION",
         entity_sets=["A_PurchasingOrganization"],
         description="Master Data - Purchasing Organization (Read)",
     ),
@@ -473,6 +498,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_COSTCENTER_SRV",
         path="/sap/opu/odata/sap/API_COSTCENTER_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_COSTCENTER_SRV_0001",
         entity_sets=["A_CostCenter"],
         description="Master Data - Cost Center (Read)",
     ),
@@ -480,6 +506,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PROFITCENTER_SRV",
         path="/sap/opu/odata/sap/API_PROFITCENTER_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_PROFITCENTER_SRV_0001",
         entity_sets=["A_ProfitCenter"],
         description="Master Data - Profit Center (Read)",
     ),
@@ -487,6 +514,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_GLACCOUNTINCHARTOFACCOUNTS_SRV",
         path="/sap/opu/odata/sap/API_GLACCOUNTINCHARTOFACCOUNTS_SRV",
         odata_version=2,
+        oauth_scope="ZAPI_GLACCOUNTINCHARTOFACCOUNTS_SRV_0001",
         entity_sets=["A_GLAccountInChartOfAccounts"],
         description="Master Data - G/L Account in Chart of Accounts (Read)",
     ),
@@ -497,6 +525,7 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
         name="API_PURCHASEORDER_2",
         path="/sap/opu/odata4/sap/api_purchaseorder_2/srvd_a2x/sap/purchaseorder/0001",
         odata_version=4,
+        oauth_scope="OV4:API_PURCHASEORDER_2",
         entity_sets=[
             "PurchaseOrder",
             "PurchaseOrderItem",
@@ -507,6 +536,32 @@ SAP_ODATA_SERVICES: dict[str, SAPODataServiceModel] = {
     ),
 }
 
+
+def get_oauth_scope(services: list[str] | None = None) -> str:
+    """Build the scope parameter of the OAuth token request from SAP_ODATA_SERVICES.
+
+    Args:
+        services (list[str] | None, optional):
+            Names of the OData services in SAP_ODATA_SERVICES to get the scopes for.
+            Defaults to None (all services in SAP_ODATA_SERVICES).
+
+    Returns:
+        str:
+            Space-separated scope IDs, e.g. "ZAPI_MAINTENANCEORDER_0002 ZAPI_MAINTNOTIFICATION_0001".
+            Services that are not registered or have no scope are skipped.
+
+    """
+
+    if services is None:
+        services = list(SAP_ODATA_SERVICES)
+
+    return " ".join(
+        SAP_ODATA_SERVICES[service].oauth_scope
+        for service in services
+        if service in SAP_ODATA_SERVICES and SAP_ODATA_SERVICES[service].oauth_scope
+    )
+
+
 # OData V4 transmits Edm.Decimal values (quantities, prices) as JSON numbers by default.
 # With IEEE754Compatible=true they are transmitted as strings, which avoids any loss of
 # precision and matches Python's Decimal (pydantic serializes Decimal as string):
@@ -1998,6 +2053,278 @@ class SAP:
 
     # end method definition
 
+    def check_oauth_token_endpoint(self, timeout: float = REQUEST_TIMEOUT) -> SAPAuthCheckStatusModel:
+        """Check if SAP's OAuth 2.0 token endpoint is activated and reachable.
+
+        This is the first step of the SAML 2.0 bearer assertion flow used for principal
+        propagation (see get_oauth_access_token()) - before any OAuth client, SAML trust
+        or user is involved. An intentionally incomplete token request without client
+        credentials and grant_type is sent. A live endpoint answers it with HTTP 401 (the
+        ICF node requires the client authentication) or a well-formed OAuth error (e.g.
+        "invalid_request"), which is enough to tell apart the typical setup problems:
+        * The ICF node /sap/bc/sec/oauth2/token is not active (transaction SICF).
+        * The SAP system is not reachable at all (DNS, firewall, TLS, timeout).
+        * The base URL points to something else (e.g. a login page of a reverse proxy).
+
+        Args:
+            timeout (float, optional):
+                Timeout for the check request in seconds. Defaults to REQUEST_TIMEOUT.
+
+        Returns:
+            SAPAuthCheckStatusModel:
+                The result of the check. Use status.ok to check the result.
+
+        Example:
+            >>> status = sap.check_oauth_token_endpoint()
+            >>> if not status.ok:
+            ...     print(status.hint)
+
+        """
+
+        name = "OAuth 2.0 token endpoint"
+
+        if not self._base_url:
+            return SAPAuthCheckStatusModel(
+                name=name,
+                state=SAPAuthCheckState.NOT_CONFIGURED,
+                message="The SAP object has been initialized without a base URL.",
+                hint="Set base_url to enable OData / OAuth checks.",
+            )
+
+        token_url = self.oauth_token_url()
+        self.logger.info("Checking SAP OAuth 2.0 token endpoint at -> %s ...", token_url)
+
+        try:
+            response = requests.post(
+                url=token_url,
+                data={},
+                headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+                verify=self._verify_ssl,
+                timeout=timeout,
+            )
+        except requests.exceptions.SSLError as ssl_error:
+            status = SAPAuthCheckStatusModel(
+                name=name,
+                state=SAPAuthCheckState.UNREACHABLE,
+                message=str(ssl_error),
+                hint="TLS handshake failed. Check the certificate of the SAP system or set verify_ssl=False "
+                "for test systems with self-signed certificates.",
+            )
+        except requests.exceptions.RequestException as request_error:
+            status = SAPAuthCheckStatusModel(
+                name=name,
+                state=SAPAuthCheckState.UNREACHABLE,
+                message=str(request_error),
+                hint="Check the base URL (protocol, hostname, HTTPS port), DNS resolution and firewall rules.",
+            )
+        else:
+            try:
+                body = response.json()
+            except ValueError:
+                body = {}
+            if not isinstance(body, dict):
+                body = {}
+
+            if response.status_code == HTTPStatus.NOT_FOUND or (
+                response.status_code == HTTPStatus.FORBIDDEN and "service cannot be reached" in response.text.lower()
+            ):
+                # SAP answers 404 for an unknown path and 403 "Service cannot be reached" for an inactive ICF node:
+                status = SAPAuthCheckStatusModel(
+                    name=name,
+                    state=SAPAuthCheckState.NOT_ACTIVATED,
+                    http_status=response.status_code,
+                    message="HTTP {} - endpoint not found or not active".format(response.status_code),
+                    hint="Activate the ICF node /sap/bc/sec/oauth2/token in transaction SICF.",
+                )
+            elif response.status_code == HTTPStatus.UNAUTHORIZED:
+                # The ICF node authenticates the OAuth client before the OAuth handler runs, so a live
+                # endpoint rejects this request without credentials:
+                status = SAPAuthCheckStatusModel(
+                    name=name,
+                    state=SAPAuthCheckState.OK,
+                    http_status=response.status_code,
+                    message="HTTP 401 - endpoint is active and requires the OAuth client authentication",
+                )
+            elif "error" in body:
+                # Any well-formed OAuth error (e.g. "invalid_request" for the missing grant_type)
+                # proves the endpoint itself is live and speaking OAuth 2.0:
+                status = SAPAuthCheckStatusModel(
+                    name=name,
+                    state=SAPAuthCheckState.OK,
+                    http_status=response.status_code,
+                    message="{} - {}".format(body.get("error"), body.get("error_description", "")),
+                )
+            else:
+                status = SAPAuthCheckStatusModel(
+                    name=name,
+                    state=SAPAuthCheckState.ERROR,
+                    http_status=response.status_code,
+                    message="HTTP {} - unexpected response (not a JSON OAuth error)".format(response.status_code),
+                    hint="Check that the base URL points to the SAP Gateway and not to a login page or reverse proxy.",
+                )
+
+        if status.ok:
+            self.logger.info("SAP OAuth 2.0 token endpoint is active; message -> %s", status.message)
+        else:
+            self.logger.error(
+                "SAP OAuth 2.0 token endpoint is not usable; state -> '%s'; message -> %s; hint -> %s",
+                status.state.value,
+                status.message,
+                status.hint,
+            )
+
+        return status
+
+    # end method definition
+
+    def check_principal_propagation(
+        self,
+        user_id: str,
+        client_id: str,
+        client_secret: str,
+        scope: str | None = None,
+        nameid_format: str = SAML_NAMEID_FORMAT_UNSPECIFIED,
+        recipient: str | None = None,
+    ) -> SAPAuthCheckStatusModel:
+        """Check the full SAML 2.0 bearer assertion / OAuth 2.0 principal propagation round trip.
+
+        Runs exactly what get_oauth_access_token_for_user() does for a real user: mint a
+        SAML 2.0 assertion for user_id (get_saml_assertion()) and exchange it for an SAP
+        access token (get_oauth_access_token()). Use this with a dedicated test user to
+        verify the setup end-to-end - unlike check_oauth_token_endpoint() this needs a working OAuth
+        client (SOAUTH2), a trusted SAML 2.0 identity provider (SAML2) and a valid NameID
+        mapping for user_id. The message of a failed check (SAP's own OAuth error, e.g.
+        "invalid_client", "invalid_grant", "unauthorized_client" or "invalid_scope") is kept
+        as returned - see the hint for what it typically means.
+
+        Args:
+            user_id (str):
+                The user to propagate, e.g. a dedicated technical test user. See
+                get_saml_assertion() for the security implications.
+            client_id (str):
+                The OAuth 2.0 client ID registered in SOAUTH2.
+            client_secret (str):
+                The password of the SU01 system user behind that OAuth client.
+            scope (str | None, optional):
+                Space-separated scope IDs to request, e.g. "API_MAINTENANCEORDER_0002".
+                Defaults to None (the default scopes of the OAuth client).
+            nameid_format (str, optional):
+                The NameID format - must match transaction SAML2. Defaults to
+                "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified".
+            recipient (str | None, optional):
+                The Recipient of the assertion - only needed behind a reverse proxy (see
+                get_saml_assertion()). Defaults to None = oauth_token_url().
+
+        Returns:
+            SAPAuthCheckStatusModel:
+                The result of the check. Use status.ok to check the result.
+
+        Example:
+            >>> status = sap.check_principal_propagation(user_id="jane.smith", client_id="PYXECM_OAUTH", client_secret="...")
+            >>> if not status.ok:
+            ...     print(status.message, "-", status.hint)
+
+        """
+
+        name = "SAML 2.0 / OAuth 2.0 principal propagation"
+
+        if not self._base_url:
+            return SAPAuthCheckStatusModel(
+                name=name,
+                state=SAPAuthCheckState.NOT_CONFIGURED,
+                message="The SAP object has been initialized without a base URL.",
+                hint="Set base_url to enable OData / OAuth checks.",
+            )
+
+        # Same two steps as get_oauth_access_token_for_user() - separately, so a problem of
+        # pyxecm's own identity provider configuration is not mistaken for an SAP-side error:
+        assertion = self.get_saml_assertion(user_id=user_id, nameid_format=nameid_format, recipient=recipient)
+        if not assertion:
+            status = SAPAuthCheckStatusModel(
+                name=name,
+                state=SAPAuthCheckState.NOT_CONFIGURED
+                if self._saml_idp_private_key is None
+                else SAPAuthCheckState.ERROR,
+                message=self.last_error or "unknown error",
+                hint="Check saml_idp_private_key, saml_idp_certificate, saml_issuer and saml_audience of the SAP "
+                "object and the user_id - no request has been sent to SAP.",
+            )
+            self.logger.error(
+                "%s failed; state -> '%s'; message -> %s; hint -> %s",
+                name,
+                status.state.value,
+                status.message,
+                status.hint,
+            )
+            return status
+
+        token = self.get_oauth_access_token(
+            assertion=assertion, client_id=client_id, client_secret=client_secret, scope=scope
+        )
+        if token:
+            status = SAPAuthCheckStatusModel(
+                name=name,
+                state=SAPAuthCheckState.OK,
+                message="Received access token for user -> '{}' (scope -> '{}', expires in -> {}s)".format(
+                    user_id,
+                    token.get("scope", ""),
+                    token.get("expires_in", "?"),
+                ),
+            )
+            self.logger.info("%s succeeded; message -> %s", name, status.message)
+            return status
+
+        error = self.last_error or "unknown error"
+        error_lower = error.lower()
+        # Wrong client credentials fail the logon of the ICF node already - SAP then answers
+        # HTTP 401 without an OAuth error (see get_oauth_access_token() for the format):
+        if "invalid_client" in error_lower or "status -> 401/" in error_lower:
+            state, hint = (
+                SAPAuthCheckState.REJECTED,
+                (
+                    "Check client_id/client_secret - they must match an SU01 system user with grant type "
+                    "'SAML 2.0 Bearer Assertion' configured in transaction SOAUTH2."
+                ),
+            )
+        elif "invalid_grant" in error_lower:
+            state, hint = (
+                SAPAuthCheckState.REJECTED,
+                (
+                    "SAP rejected the SAML assertion. Check the trusted identity provider (signing certificate, "
+                    "issuer, audience) in transaction SAML2 and that user_id resolves to an SAP user (NameID mapping)."
+                ),
+            )
+        elif "unauthorized_client" in error_lower:
+            state, hint = (
+                SAPAuthCheckState.REJECTED,
+                (
+                    "The OAuth client is not authorized for the 'SAML 2.0 Bearer Assertion' grant type - enable it "
+                    "in transaction SOAUTH2."
+                ),
+            )
+        elif "invalid_scope" in error_lower:
+            state, hint = (
+                SAPAuthCheckState.REJECTED,
+                (
+                    "The requested scope is not assigned to the OAuth client. Enable OAuth for the OData service(s) "
+                    "in /IWFND/MAINT_SERVICE and assign the scope(s) to the client in SOAUTH2."
+                ),
+            )
+        else:
+            state, hint = (
+                SAPAuthCheckState.ERROR,
+                "Check the SAP Gateway error log (transaction /IWFND/ERROR_LOG) and the system log (SM21).",
+            )
+
+        status = SAPAuthCheckStatusModel(name=name, state=state, message=error, hint=hint)
+        self.logger.error(
+            "%s failed; state -> '%s'; message -> %s; hint -> %s", name, status.state.value, status.message, status.hint
+        )
+
+        return status
+
+    # end method definition
+
     @staticmethod
     def _quote_key(value: str) -> str:
         """Escape a value for use in an OData key or filter string literal (single quotes are doubled).

{pyxecm-3.8.2 → pyxecm-3.8.3}/src/pyxecm_customizer/sap_models.py

@@ -906,6 +906,10 @@ class SAPODataServiceModel(BaseModel):
             e.g. "/sap/opu/odata/sap/API_MAINTENANCEORDER".
         odata_version (int):
             OData protocol version of the service (2 or 4).
+        oauth_scope (str):
+            OAuth 2.0 scope ID of the service, e.g. "ZAPI_MAINTENANCEORDER_0002". SAP generates
+            it when OAuth is enabled for the service - it can differ between SAP systems.
+            Empty if the service has no scope.
         entity_sets (list[str]):
             Entity sets that must be exposed by the service. Used by check_odata_apis()
             to detect services that are active but do not expose what we need
@@ -918,6 +922,7 @@ class SAPODataServiceModel(BaseModel):
     name: str
     path: str
     odata_version: int = Field(default=2, ge=2, le=4)
+    oauth_scope: str = ""
     entity_sets: list[str] = Field(default_factory=list)
     description: str = ""
 
@@ -980,6 +985,57 @@ class SAPODataServiceStatusModel(BaseModel):
     # end method definition
 
 
+class SAPAuthCheckState(StrEnum):
+    """Possible results of an authentication / principal propagation health check."""
+
+    OK = "ok"  # the checked step succeeded
+    NOT_CONFIGURED = (
+        "not_configured"  # required constructor parameters are missing (e.g. base_url, saml_idp_private_key)
+    )
+    NOT_ACTIVATED = "not_activated"  # the SAP endpoint is not activated/provisioned (ICF node, SOAUTH2, SAML2)
+    REJECTED = "rejected"  # SAP rejected the request (wrong credentials, invalid client, invalid grant, ...)
+    UNREACHABLE = "unreachable"  # network / DNS / TLS / timeout problem
+    ERROR = "error"  # any other error
+
+
+class SAPAuthCheckStatusModel(BaseModel):
+    """Result of a single step of an authentication / principal propagation health check.
+
+    Used by SAP.check_oauth_token_endpoint() and SAP.check_principal_propagation() - see there for the
+    checks they perform.
+
+    Attributes:
+        name (str):
+            Short name of the checked step, e.g. "OAuth 2.0 token endpoint".
+        state (SAPAuthCheckState):
+            The result of the check.
+        http_status (int | None):
+            The HTTP status code of the check request, if one was sent.
+        message (str):
+            The (error) message returned by SAP or the request library.
+        hint (str):
+            A hint how to fix the problem (empty if the check succeeded).
+        ok (bool):
+            True if the check succeeded (computed - also included in model_dump() / model_dump_json()).
+
+    """
+
+    name: str
+    state: SAPAuthCheckState
+    http_status: int | None = None
+    message: str = ""
+    hint: str = ""
+
+    @computed_field
+    @property
+    def ok(self) -> bool:
+        """Return True if the check succeeded."""
+
+        return self.state == SAPAuthCheckState.OK
+
+    # end method definition
+
+
 class SAPODataErrorDetailModel(BaseModel):
     """A single detail message of an SAP OData error response."""
 

{pyxecm-3.8.2 → pyxecm-3.8.3}/src/pyxecm_customizer/settings.py

@@ -500,8 +500,9 @@ class CustomizerSettingsSAP(BaseModel):
         default="",
         description=(
             "Space-separated SAP OAuth 2.0 scope IDs requested for the access tokens, e.g. "
-            "'API_MAINTENANCEORDER_0002 API_MAINTNOTIFICATION_0001'. Empty = the default scopes "
-            "of the OAuth client in SOAUTH2."
+            "'API_MAINTENANCEORDER_0002 API_MAINTNOTIFICATION_0001'. Only required if the scope IDs "
+            "of the SAP system differ from the ones in SAP_ODATA_SERVICES (sap.py). Empty = the "
+            "scopes of all services in SAP_ODATA_SERVICES."
         ),
     )