Orchestrator 用户指南

适用平台：

上次更新日期 2025年11月10日

Orchestrator Credentials Proxy debugging

日志

By default, the Orchestrator Credentials Proxy logs all exceptions and the initial startup and shutdown information.

To check if the credentials proxy is really logging 200 requests, start the Orchestrator Credentials Proxy on the local server, go to Swagger and run the Health (unauthenticated) endpoint: api/v1/Health. The requests should now be logged.

Note: After each change to the appsettings file, you need to restart the credentials proxy.

If you follow these steps and no additional logs besides startup and shutdown are available, that means that no requests are reaching the Orchestrator Credentials Proxy. This is most likely caused by an infrastructure or networking issue the Orchestrator Cloud Robot and the Orchestrator Credentials Proxy machines.

Event viewer

All logs should appear in the Windows Event Viewer for Orchestrator Credentials Proxy versions 2.0.0 and above.

Changing the log file destination

To change the log file path, open the appsettings.production.json file and use the following code. You can replace C:/dev/logs with the desired path:

"NLog": {
    "throwConfigExceptions": true,
    "targets": {
      "logfile": {
        "type": "File",
        "maxArchiveFiles": 180,
        "fileName": "C:/dev/logs/nlog-${shortdate}.log",
        "layout": "${longdate} ${logger} ${message}${onexception:${newline}${exception:maxInnerExceptionLevel=10:format=shortType,message,stacktrace:separator=*:innerExceptionSeparator=&#xD;&#xA;&#x9;}}"
      }
    },
    "rules": [
      {
        "logger": "*",
        "minLevel": "Information",
        "writeTo": "logconsole,logfile,eventLog"
      }
    ]
  }  "NLog": {
    "throwConfigExceptions": true,
    "targets": {
      "logfile": {
        "type": "File",
        "maxArchiveFiles": 180,
        "fileName": "C:/dev/logs/nlog-${shortdate}.log",
        "layout": "${longdate} ${logger} ${message}${onexception:${newline}${exception:maxInnerExceptionLevel=10:format=shortType,message,stacktrace:separator=*:innerExceptionSeparator=&#xD;&#xA;&#x9;}}"
      }
    },
    "rules": [
      {
        "logger": "*",
        "minLevel": "Information",
        "writeTo": "logconsole,logfile,eventLog"
      }
    ]
  }

Additional logs

Note: This procedure should only be used for debugging. When done, revert these changes as it will produce excessive logs.

The default logging levels looks similar to the following:

"Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },

If you want to get more logs, for example to see all requests coming to the proxy, you need to edit the appsettings.Production.json file and add the following:

"Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Information",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  }  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Information",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  }

If the Information is not enough and want more or less, you can use the LogLevels values from .Net. For more information, check the Microsoft documentation. The appsettings.json file should look similar to the following:

"Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Information",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  }  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Information",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  }

Restart the Orchestrator Credentials Proxy after changing the appsettings file.

Test with InMemoryStore

If you are encountering issues debugging and want to check with a different credential store type, you can use the Orchestrator Credentials Proxy InMemorySecureStore type.

Note: Only use this procedure for testing purposes.

To enable the InMemorySecureStore type, open the appsettings.production.json file, go to the AppSettings section, and add the "UseInMemorySecureStore": "true" parameter.

To enable it for Disconnected proxies, include the following in the SecureStoreConfigurations section as well:

{
  "Key": "InMemoryKey1", // can be any value
  "Type": "InMemorySecureStore",
  "Context": {
  }
}{
  "Key": "InMemoryKey1", // can be any value
  "Type": "InMemorySecureStore",
  "Context": {
  }
}

Connected proxy could not connect

When setting up an Orchestrator Credentials Proxy connection and attempting to link it with Orchestrator, you might encounter the following error message:

Request to the Credentials Proxy's unauthenticated health endpoint failed.Request to the Credentials Proxy's unauthenticated health endpoint failed.

During the connection process, Orchestrator performs a simple GET request to the /api/v1/Health proxy endpoint.

The purpose of this request is to verify that the proxy is reachable from the Orchestrator cloud environment. If this request fails, it indicates that Orchestrator cannot access the proxy, and the connection check will not pass.

常见问题

The Orchestrator Credentials Proxy is not started:
- Go to the server where the Orchestrator Credentials Proxy is installed.
- In IIS, verify that the credentials proxy application is running.
- On the same server, open a browser and check that the credentials proxy URL is accessible locally.
The connection does not have a valid HTTPS/SSL certificate. All communication between Orchestrator and OCP must be secure.
- Ensure that your credentials proxy uses a valid HTTPS/SSL certificate.
- (Optional) If a load balancer is configured in front of the Orchestrator Credentials Proxy, confirm that it also uses a secure HTTPS connection.
The Orchestrator Credentials Proxy is blocked behind a firewall, VPN, or similar network restriction. If the credentials proxy is not reachable from Orchestrator, verify your network configuration.
- Make sure that the Orchestrator outbound IPs are properly whitelisted. Check the Orchestrator Outbound IP Addresses page for more information.
  Note: If your organization has multiple tenants, they might be hosted in different regions and use different IP addresses. Double-check for each tenant.
Unauthenticated endpoint issue due to incorrect server time.
- If the unauthenticated endpoint fails, it is possible that the server time is not correctly set. When the system clock is inaccurate, the server might interpret JWT tokens as invalid.

Steps to investigate

Verify in the IIS that the Orchestrator Credentials Proxy is Running.
Check in the browser that the credentials proxy URL is accessible and loads correctly.
Check in the browser that the credentials proxy URL is secure.
On the credentials proxy machine, increase the logging level to Information for troubleshooting. emember to revert this change after completing the investigation.
Test the health endpoint locally. On the credentials proxy machine, open Swagger or use a tool such as Postman to make a request to:
```
https://{yourCredentialsProxyUrl}/api/v1/Healthhttps://{yourCredentialsProxyUrl}/api/v1/Health
```
A successful response indicates that the proxy is reachable and operational locally.
Test access within the VPN. From another machine within the same VPN (for example, a client’s laptop or a client’s robot machine), check that the credentials proxy URL is accessible. Make a request to the same /api/v1/Health endpoint:
- If it works, the credentials proxy is reachable from inside the VPN.
- If it does not, the client must resolve the internal network or routing issue.
Test public accessibility.
On a machine that is not inside the VPN, check the /api/v1/Health endpoint:
- If it works, the credentials proxy is reachable from outside the VPN.
- If it does not, the client must resolve the internal network or routing issue.
Test the connection from Orchestrator cloud. Create a new credentials proxy linked to the same proxy URL:
- If the creation succeeds,you can delete the connection.
- If it fails, something is still blocking communication between Orchestrator and the credentials proxy.
  
  Note: At this point, the credentials proxy should be publicly accessible, without firewall restrictions or IP whitelisting.
Retrieve the list of Orchestrator tenant IP addresses.
Add the IPs to the allowlist for access to the credentials proxy.
From a machine outside the VPN, test the /api/v1/Health endpoint again. It should not work, since the IP is not added to the allowlist.
In Orchestrator Cloud, try creating a credentials proxy again:
- If all steps have been completed correctly, it should now succeed.
- If it still fails, there may be an issue with firewall or VPN rules preventing communication between Orchestrator and the credentials proxy.
If the issue persists, repeat the above steps carefully and verify each configuration point.
Once the issue is resolved, revert the log level on the credentials proxy machine to its original setting.

Disconnected proxy will not start or log

The disconnected credentials proxy performs a validation step during startup to ensure that it can correctly serve client requests. As part of this process, the proxy validates each configuration defined in AppSettings:SecureStoreConfigurations. The specific validation logic applied depends on the type of credential store configured.

In certain cases, the root cause of the proxy failing to start may occur so early in the startup process that the application does not reach the point of generating or writing any log events.

Possible causes that the app does not start

Several issues can prevent the Credentials Proxy application from starting. Below are common causes and how to identify them.

IIS application pool not started (Windows). If the proxy is hosted in IIS, verify that the application pool associated with it is running. You can check this in the IIS Manager under the Application Pools section.
Invalid configuration in appsettings.Production.json. An invalid or incomplete configuration file may cause the proxy to fail during startup. Check the examples in the Configuration samples section for more details.
Invalid configuration in AppSettings:SecureStoreConfigurations. The SecureStoreConfigurations section defines how the proxy connects to and validates credential stores. If any of these entries are malformed or incomplete, the application will not start.
- Invalid parameters in configuration. Make sure all configuration parameters match the credential store type you are using. Using incorrect parameters or keys can cause startup validation to fail.
- Unable to access the vault. If the configured credential store relies on an external vault (for example, CyberArk, BeyondTrust, or others), startup may fail if the proxy cannot reach or authenticate with it.
Other infrastructure-related issues.

调试

When debugging the credentials proxy, the goal is to eliminate as many variables as possible before testing complex configurations.

Begin by using a minimal configuration with the InMemorySecureStore type. This allows you to confirm that the proxy can start successfully before introducing external dependencies.
- Add the "UseInMemorySecureStore": "true", parameter in AppSettings.
- Add the following in AppSettings:SecureStoreConfigurations:
```
"SecureStoreConfigurations": [
  {
    "Key": "InMemoryKey1",
    "Type": "InMemorySecureStore",
    "Context": {  }
  }
]"SecureStoreConfigurations": [
  {
    "Key": "InMemoryKey1",
    "Type": "InMemorySecureStore",
    "Context": {  }
  }
]
```
- The proxy should no longer have configuration-related issues. If it still fails to start, the cause is most likely infrastructure-related.
Once you confirmed the proxy starts successfully using the in-memory configuration, replace it with your actual credential store setup (for example, CyberArk, BeyondTrust, and others).
- Update the SecureStoreConfigurations section based on your environment and store type.
  
  If the application fails to start, you should find logs either in:
  - The Windows Event Viewer.
  - The configured logs directory of the proxy.
- If the application does not start and no logs are generated, the issue is likely related to infrastructure or permissions in your environment.
  To help with debugging in such cases, you can temporarily disable secure store validation by adding this parameter in AppSettings:
```
"SkipValidateSecureStoreConfigurations": true"SkipValidateSecureStoreConfigurations": true
```
  Note: This parameter should only be used for debugging purposes. The startup validation exists to ensure that your proxy configuration is correct and secure.