Delegated passticket API

docs/appendix/zowe-yaml-configuration.md

@@ -536,8 +536,11 @@ These configurations can be used under the `components.gateway` section:
 - **apiml.security.oidc.identityMapperUser**  
   (Optional) If the userId is different from the default Zowe runtime userId (`ZWESVUSR`), specify the `identityMapperUser` userId to configure API ML access to the external user identity mapper.
 - **apiml.security.oidc.userIdField**  
-  Specifies the name of the field from the OIDC token with the value that is used for user mapping in SAF. Supports also nested objects via a dot-separated list. When the field contains multiple values, all values are used as distributed identifiers for mapping. Each value for mapping is evaluated sequentially and the first successfully mapped user is used. This parameter is used to specify, for example, a custom field with email or LDAP groups for user mapping. This parameter applies to Zowe version 3.4.0 and later versions.  
+  Specifies the name of the field from the OIDC token with the value that is used for user mapping in SAF. Supports also nested objects via a dot-separated list. When the field contains multiple values, all values are used as distributed identifiers for mapping. Each value for mapping is evaluated sequentially and the first successfully mapped user is used. This parameter is used to specify, for example, a custom field with email or LDAP groups for user mapping. This parameter applies to Zowe version 3.4.0 
+  and later versions.
   **Default:** `sub`
+- **apiml.security.delegatePassticket.enabled**
+  Specifies whether the API `POST` for endpoint `/gateway/api/v1/auth/delegate/passticket` is enabled.  The default value is `false`.  For more information, see [Configuring Delegated Passticket Generation](../user-guide/api-mediation/configuration-delegated-passticket.md).
 
 :::note
 

docs/user-guide/api-mediation/configuration-authorization.md

@@ -3,8 +3,9 @@
 :::info Role: system administrator
 :::
 
-In Zowe's API Mediation Layer, system administrators can limit access to services and information in the API Catalog by hiding sensitive data like service instance URLs, configurable via the apiml.catalog.hide.serviceInfo property in zowe.yaml. Additionally, SAF resource checking for user authorization on specific endpoints is facilitated through various providers, such as Endpoint, Native, and Dummy. These configurations, modifiable in the zowe.yaml file, enhance security by controlling service exposure and ensuring proper authorization checks within the Zowe ecosystem.
+In Zowe's API Mediation Layer, system administrators can limit access to services and information in the API Catalog by hiding sensitive data like service instance URLs, configurable via the `apiml.catalog.hide.serviceInfo` property in zowe.yaml. Additionally, SAF resource checking for user authorization on specific endpoints is facilitated through various providers, such as **Endpoint**, **Native**, and **Dummy**. These configurations, which can be modified in the zowe.yaml file, enhance security by controlling service exposure and ensuring proper authorization checks within the Zowe ecosystem.
 
 - [Limiting access to information or services in the API Catalog](./configuration-limiting-access-to-info-or-services-in-api-catalog.md)
 - [Configuring SAF resource checking](./configuration-saf-resource-checking.md)
-- [Configurint Health Endpoint Protection](./configuration-health-endpoint-protection.md)
+- [Configuring Health Endpoint Protection](./configuration-health-endpoint-protection.md)
+- [Configuring delegated PassTicket generation](./configuration-delegated-passticket.md)

docs/user-guide/api-mediation/configuration-delegated-passticket.md

@@ -0,0 +1,130 @@
+# Configuring Delegated PassTicket Generation
+
+:::info Role: system administrator
+:::
+
+As a system administrator, you can enable the endpoint of the API Gateway that allows PassTicket generation for a delegated e-mail.  
+
+:::important Warning
+This API allows the authenticated user to create a PassTicket for another user.This presents a potential risk for privilege escalation or impersonation. To mitigate this risk, you must ensure strict access control via client certificates and ESM permissions.
+:::
+
+To enable and use this feature, complete the following steps:
+
+1. Enable the delegated PassTicket endpoint of the API Gateway.
+
+2. Configure user permissions to generate delegated PassTickets.
+
+3. Call the `/auth/delegate/passticket` API.
+
+## Enabling the delegated PassTicket endpoint of the API Gateway
+
+By default, the delegated PassTicket endpoint is set to `false` (disabled). Enable this parameter in your zowe.yaml configuration file.
+
+1. Open the file `zowe.yaml`.
+2. Locate the `components.apiml.security` section.
+3. Set the `delegatePassticket.enabled` property to `true`.
+
+**Example:**
+```yaml
+components:
+  apiml:
+    security:
+      delegatePassticket:
+        enabled: true
+```
+
+4. Restart API ML to apply the changes.
+
+:::note
+The userID that makes the call to the API must have `READ` access to the class `ZOWE.APIML.DELEGATE.PASSTICKET`. For details, see the following section, _Configuring user permission to generate delegated PassTickets_.
+:::
+
+## Configuring user permissions to generate delegated PassTickets
+
+The delegated PassTicket API requires authentication via a client certificate. The z/OS user ID associated with that certificate must have `READ` access to the `ZOWE.APIML.DELEGATE.PASSTICKET` resource class.
+
+Follow the instructions for your specific External Security Manager (ESM):
+
+<details>
+
+<summary>Click here for command details to configure user access using RACF.</summary>
+
+**For RACF:**  
+In your ESM command line interface or other security environment, perform the following steps:
+
+1. Define the resource class:
+
+    ```racf
+    RDEFINE ZOWE APIML.DELEGATE.PASSTICKET UACC(NONE)
+    ```
+
+2.  Permit the user associated with the client certificate `READ` access:
+    ```racf
+    PERMIT APIML.DELEGATE.PASSTICKET CLASS(ZOWE) ID(<userID>) ACCESS(READ)
+    SETROPTS RACLIST(ZOWE) REFRESH
+    ```
+
+    * **`userID`**  
+    The userID associated with the client certificate calling the API.
+
+3.  (Optional) Verify userr permissions: 
+
+    ```racf
+    RLIST ZOWE APIML.DELEGATE.PASSTICKET AUTHUSER
+    ```
+
+</details>
+
+<details>
+
+<summary>Click here for command details to configure user access using ACF2.</summary>
+
+**For ACF2:**  
+In your ESM command line interface or other security environment, grant the userID `READ` access:
+
+```acf2
+SET RESOURCE(RDA) $KEY(ZOWE) TYPE(RDA) APIML.DELEGATE.PASSTICKET UID(<userID>) SERVICE(READ) ALLOW
+```
+* **`userID`**  
+The userID associated with the client certificate calling the API.
+
+</details>
+
+<details>
+
+<summary>Click here for command details to configure user access using Top Secret.</summary>
+
+**For Top Secret:**  
+In your ESM command line interface or other security environment, perform the following steps:
+
+</details>
+
+## Calling the `/auth/delegate/passticket` API
+
+Once enabled and secured, you can call the API to generate a PassTicket for a user based on their email mapping.
+
+To call the API `POST` `/gateway/api/v1/auth/delegate/passticket`:
+
+**Request Body (JSON)**
+
+```
+{
+    "applId": "APPLID",
+    "emailId": "email@example.com"
+}
+```
+
+* **APPLID**  
+    The applicationID associated with the address space the PassTicket is being generated for.
+
+    **Example:**
+    Use `IZUDFLT` to create a PassTicket for z/OSMF.
+
+* **emailId**  
+    The email ID of the user that is associated with the z/OS userID.
+
+    :::tip
+    For more information about mapping email IDs to mainframe userIDs, see the [ESM configuration prerequisites](../../extend/extend-apiml/api-mediation-oidc-authentication.md#esm-configuration-prerequisites).
+    :::
+