Configure HTTPS for the PBRS API

Configure HTTPS for the PBRS REST API by installing a server certificate, binding it to a Windows HTTPS port, configuring PBRS, and testing access from your application.

This procedure configures HTTPS directly on the PBRS server. An IIS website is not required.

Before you begin

You need:

• An installed PBRS API service.
• Administrator access to the PBRS server.
• A server certificate suitable for HTTPS server authentication.
• The certificate's corresponding private key.
• A hostname covered by the certificate.
• An available TCP port.
• Permission to configure Windows certificate bindings and firewall access.
• A client machine from which to test the connection.

Complete Install and Configure the PBRS API if the API service is not installed.

The examples use:

Replace the hostname and port with your configuration.

Port 9001 is an example, not a required or default HTTPS port. The Windows binding, PBRS port, firewall configuration, and application URL must agree.

1. Prepare the hostname and certificate

Choose the hostname applications will use to reach the PBRS server.

Confirm that:

• The hostname resolves to the intended server.
• The certificate covers that hostname in its Subject Alternative Name.
• The certificate is within its validity period.
• The certificate is suitable for server authentication.
• The corresponding private key is available on the PBRS server.
• The certificate chain can be validated by the calling applications.

Use the certificate hostname in HTTPS requests. Do not substitute localhost or an IP address unless the certificate also covers that name or address.

Record the current API protocol, port, and application connection addresses before changing an existing deployment.

2. Install the server certificate

Perform these steps on the PBRS server using an administrator account.

1. Open mmc.exe.
2. Select File → Add/Remove Snap-in.
3. Select Certificates, then click Add.
4. Select Computer account.
5. Select Local computer, then click Finish.
6. Click OK.
7. Expand Certificates (Local Computer) → Personal.
8. Right-click Certificates, then select All Tasks → Import.
9. Import the server certificate into Personal.

When transferring a certificate and its private key from another machine, use a password-protected PFX file and provide its password during import.

If the certificate was issued from a request generated on this server, complete the certificate installation using the matching private key.

Open the installed certificate and confirm that Windows reports an associated private key. A certificate containing only the public key is insufficient for this HTTPS configuration.

Match the certificate store

The commands in this guide use certstorename=MY, which identifies the Local Machine Personal store.

If your administrator uses a different Local Machine store, such as WebHosting, use that store consistently when locating the certificate and creating or updating its binding.

Do not bind a certificate using MY if the certificate and its private key are available only in another store.

Configure certificate-chain trust

The server certificate and the trusted issuing authorities have different roles.

For a private CA, distribute the appropriate CA certificates through your organization's certificate-management process.

Do not install the server's leaf certificate in Trusted Root Certification Authorities as a general deployment step. Do not distribute its private key to API clients.

3. Obtain the certificate thumbprint

In the certificate window:

1. Select Details.
2. Select Thumbprint.
3. Copy the value.
4. Remove spaces and any hidden characters introduced when copying.

You can also inspect certificates in the Personal store from PowerShell:

Get-ChildItem Cert:\LocalMachine\My | Select-Object Subject, Thumbprint, NotAfter, HasPrivateKey

Identify the intended certificate by its hostname, validity, thumbprint, and private-key availability.

Open Windows PowerShell as Administrator and set the values used by the binding commands:

$PbrsHttpsPort = 9001
$PbrsCertificateStore = "MY"
$PbrsCertificateThumbprint = (Read-Host "Enter the server certificate thumbprint").Trim()

Enter the thumbprint without spaces or hidden characters. Keep this PowerShell session open for the following steps.

4. Inspect existing HTTPS bindings

List the current Windows HTTPS bindings:

netsh http show sslcert

Inspect the proposed binding:

netsh http show sslcert "ipport=0.0.0.0:$PbrsHttpsPort"

The binding used here applies to all IPv4 addresses on the selected port. It does not establish an IPv6 binding.

Before proceeding:

• Check for existing bindings using the selected port.
• Confirm whether any existing binding belongs to PBRS or another service.
• Record the existing certificate hash, application ID, store, and additional settings before changing a PBRS binding.
• Choose another available port if the proposed binding would conflict with another service.

Do not delete an unfamiliar binding to make the installation succeed.

If a suitable PBRS binding already exists, verify its certificate and configuration instead of adding a duplicate. For certificate replacement, use the renewal procedure below.

5. Create the HTTPS certificate binding

For a new binding, run this command in the elevated PowerShell session:

netsh http add sslcert "ipport=0.0.0.0:$PbrsHttpsPort" "certhash=$PbrsCertificateThumbprint" "appid={03d06337-1e4d-442d-93f9-10c8de932c8b}" "certstorename=$PbrsCertificateStore"

The application ID identifies the PBRS certificate binding. It is not an API client ID, client secret, or access token.

Confirm that the command succeeds, then inspect the binding:

netsh http show sslcert "ipport=0.0.0.0:$PbrsHttpsPort"

Verify the port, certificate hash, application ID, and certificate-store name.

Creating a certificate binding does not start the PBRS API service.

6. Configure PBRS to use HTTPS

1. Open PBRS.
2. Open Options → REST API to display PBRS API Configuration.
3. Select API Settings.
4. If the API is running, coordinate the interruption and click Stop.
5. Under Configuration Settings, set Protocol to https.
6. Set Port to the port used in the Windows binding.

For the example configuration:

Protocol and Port cannot be changed while the API service is running.

Selecting https does not install the certificate or create its Windows binding.

7. Configure network access

Allow inbound TCP connections to the configured HTTPS port on the PBRS server.

Scope the rule to the intended client addresses or networks and the applicable firewall profiles. Configure any intervening network firewalls as well.

If client outbound traffic is restricted, permit connections from the client to the PBRS server's HTTPS port.

A firewall rule created for HTTP port 9000 does not automatically allow HTTPS port 9001 or another selected port.

8. Start the API service

On the API Settings tab:

1. Click Start under API Status.
2. Confirm that the status reads The PBRS API Service is running.

If the service does not start, inspect the service error and Windows configuration before repeatedly retrying.

Starting the API service does not verify reporting-account access, scheduler state, or report delivery.

9. Test HTTPS connectivity

From the machine that will run your integration, send a Ping request using the certificate hostname and configured port.

In Windows PowerShell:

curl.exe --request GET --url "https://pbrs.example.com:9001/api/Service/Ping" --header "Accept: application/json"

Replace the example hostname and port.

A successful request returns HTTP 200 with:

1

Ping does not require authentication.

Keep certificate verification enabled. Do not use --insecure or -k to bypass certificate errors.

Confirm that:

• The request uses https.
• The hostname matches the certificate.
• The client trusts the certificate chain.
• The request reaches the configured port.
• The response contains 1.

A local HTTP test does not verify HTTPS. A successful binding command does not establish remote connectivity.

Compare local and remote results

You can run the same HTTPS request from the PBRS server, using the certificate hostname rather than automatically substituting localhost.

If it succeeds locally but fails remotely, check name resolution, routing, firewall access, and the remote application's certificate trust.

The example binding covers IPv4. If the hostname also resolves to IPv6, verify that the client's selected network path is supported by your server configuration.

10. Verify an authenticated request

Use Authentication and Token Management to obtain an access token through the HTTPS address.

The token endpoint depends on the authentication method:

Keep /api out of the base address so that either complete endpoint path can be appended correctly.

After obtaining a token, test a protected read-only operation. For example:

$PbrsBaseUrl = "https://pbrs.example.com:9001"
$PbrsAccessToken = Read-Host "Enter an access token"
$PbrsHeaders = @{
    Authorization = "Bearer $PbrsAccessToken"
    Accept = "application/json"
}
Invoke-RestMethod -Method Get -Uri "$PbrsBaseUrl/api/Service/IsSchedulerRunning" -Headers $PbrsHeaders

The response is a boolean indicating scheduler state. false means the scheduler is stopped; it does not indicate an HTTPS failure.

Ping verifies unauthenticated connectivity. A successful protected request also verifies authentication and access to that operation.

Update application base addresses to use the verified HTTPS hostname and port.

Renew the certificate

Renew the certificate before it expires.

1. Install the replacement certificate and its private key.
2. Verify its hostname, validity, certificate chain, and store.
3. Record the existing PBRS binding and its additional settings.
4. Coordinate the API interruption and stop the API service.
5. Set the PowerShell variables to the configured port, replacement certificate store, and replacement thumbprint.
6. Update the existing PBRS binding.
7. Inspect the binding.
8. Start the API service.
9. Repeat the remote HTTPS Ping and authenticated request.

For the binding created by this guide, update it with:

netsh http update sslcert "ipport=0.0.0.0:$PbrsHttpsPort" "certhash=$PbrsCertificateThumbprint" "appid={03d06337-1e4d-442d-93f9-10c8de932c8b}" "certstorename=$PbrsCertificateStore"

Then inspect it:

netsh http show sslcert "ipport=0.0.0.0:$PbrsHttpsPort"

Preserve any additional binding settings required by your deployment.

Do not assume that importing a renewed certificate automatically updates the existing Windows binding.

Confirm that clients receive the replacement certificate. If the issuing CA changes, verify client trust in the new chain.

Recover from an unsuccessful change

If verification fails:

1. Keep application submissions paused while investigating.
2. Check the certificate, private key, binding, PBRS settings, and network access.
3. If necessary, restore the recorded binding settings and the previous certificate, provided that certificate remains valid and usable.
4. Restore the matching PBRS protocol and port.
5. Start the API and repeat both connection tests before resuming submissions.

Do not remove the previous certificate until the replacement configuration has been verified. If the previous certificate is expired or revoked, install a valid replacement instead of restoring it.

Troubleshooting

Next steps

Continue with Authentication and Token Management to configure application authentication.

Use Operate the API and Scheduler to check scheduler state and execution activity.

Then follow Quick Start: Execute and Monitor a Schedule to verify report execution and delivery.