Authenticate with an HTTP proxy server

You can use this operation to authenticate with the HTTP proxy server that the primary z/OSMF instance is required to navigate to communicate with a secondary z/OSMF instance.

HTTP method and URI path

POST /zosmf/gateway/logon/proxy

where:

zosmf/gateway identifies the multisystem routing services.
logon/proxy informs the service that the request is to authenticate with an HTTP proxy server.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: application/json

Custom headers

None.

Request content

Your request must include the following JSON object:

{
  "proxyUserId":"proxy-user-ID",
  "proxyPassword":"proxy-password",
  "systemName":"system-name"
}

where:

proxy-user-ID: User ID that allows the user to access the HTTP proxy server at your enterprise. The user ID is required.
proxy-password: Password or pass phrase associated with the proxy user ID. The password is required.
system-name: Unique name assigned to the system definition that specifies the URL for accessing the secondary z/OSMF instance.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

See Required authorizations.

Expected response

On completion, the service returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 indicates success. A status code of 4nn or 5nn indicates that an error has occurred. For more details, see Error handling.

The response also includes a JSON object that indicates whether the request was successful. If the logon request is successful, null values are returned for the result and error attributes, as depicted in Figure 1.

Figure 1. Successful response when authenticating with an HTTP proxy server

{"result":null,"error":null}

If the logon request is unsuccessful, the JSON object contains an error message, as depicted in Figure 2. For a description of each attribute, see Content type used for HTTP response data.

Figure 2. Sample response when the authentication request fails

{
 "primaryAPIVersion":1.0,
 "systemsOutput":null,
 "error":{
   "msgid":"IZUG476E",
   "msgtxt":"The HTTP request to the secondary z/OSMF instance "sys057" 
   failed with error type "InvalidProxyLogin" and response code "407"."
 },
 "numOfSystems":0
}

Example

To authenticate with the HTTP proxy server that is between the primary z/OSMF instance and the z/OSMF instance that is running on system sys057, submit the following request:

Figure 3. Sample request to authenticate with an HTTP proxy server

POST /zosmf/gateway/logon/proxy HTTP/1.1
Host: zosmf1.yourco.com

{"proxyUserId":"claire","proxyPassword":"abc123","systemName":"sys057"}