Skip to main content

Allow External Access

Secure external access

Use an NGINX reverse proxy to publish approved NIM experiences without exposing NIM Studio or administrative APIs.

Apps such as onboarding, password reset, and SAML sign-in are often intended for users outside the internal network. Place NGINX on a separate Windows Server in your DMZ and use it as the only public entry point; keep the NIM Service on the internal network or VPN.

warning

Do not expose NIM Studio or the administrative API to the public internet. Work with your network and security teams to validate the DNS, network paths, certificates, and allowed application routes before publishing a service.

Internet
  │ HTTPS (443) and HTTP (80, certificate renewal only)
  ▼
NGINX reverse proxy in the DMZ
  │ Publishes approved apps, password reset, onboarding, and SAML sign-in
  │ Denies Studio, administrative APIs, and other internal-only endpoints
  ▼
NIM Service on the internal network

Administrators should connect to NIM Studio directly over the internal network or VPN, not through the NGINX server.

This separation follows CISA's Internet Exposure Reduction guidance: publish only services that require internet access. NIST's Zero Trust Architecture also treats network position as insufficient proof of trust, so continue to enforce sign-in and App access rules on the routes you publish.

Prepare NGINXDirect link to Prepare NGINX

  1. Use a Windows Server in the DMZ that can receive public traffic on ports 80 and 443 and can reach the NIM Service on its configured HTTP or HTTPS port.
  2. Create a public DNS record for the external hostname, such as apps.example.com, that resolves to the NGINX server.
  3. Download and extract the Windows build of NGINX, for example to C:\nginx.
  4. Start NGINX with ./nginx.exe to verify it runs, then stop it with ./nginx.exe -s stop.
  5. Use NSSM to run NGINX as a Windows service. Set its startup directory to C:\nginx, configure the service to start automatically, and restart it after configuration changes.
Set the public host URLThe external hostname must match the External host URL in NIM Preferences. Public DNS resolves it to NGINX; internal DNS can resolve the same name directly to the NIM server when appropriate for your environment.

Generate the NGINX configuration in NIM StudioDirect link to Generate the NGINX configuration in NIM Studio

NIM Studio can generate a configuration that separates approved public routes from internal-only routes.

  1. Sign in to NIM Studio as an administrator and go to Settings › HTTP.
  2. Select Download nginx config.
  3. Enter the internal NIM address and port that the NGINX server can reach.
  4. Choose whether to allow all hosted apps, expose only selected apps, or deny selected apps.
  5. Save the downloaded file as C:\nginx\conf\nimsuite.conf and include it inside the http { } block in C:\nginx\conf\nginx.conf.
# Inside the existing http { } block
include nimsuite.conf;

Confirm that the generated upstream block uses the internal NIM address and port. Re-download the configuration after changing NIM’s listening settings or changing the list of public apps.

Keep administrative routes internalDirect link to Keep administrative routes internal

Use the Studio-generated configuration as the source of truth for route restrictions. It should deny NIM Studio, /api/cmd/admin, the internal system-integration API routes, and the MCP endpoint unless you have deliberately designed and reviewed an exception.

Only expose the hosted apps that external users need. The default app is normally kept public by the configuration generator; review the generated allow or deny selection before deploying it.

Use Let’s Encrypt with NGINXDirect link to Use Let’s Encrypt with NGINX

NGINX terminates the public HTTPS connection, so it needs its own certificate. On Windows, win-acme is a practical ACME client for obtaining and renewing a free Let’s Encrypt certificate.

  1. Download win-acme and extract it, for example to C:\win-acme.
  2. Create an ACME webroot at C:\win-acme\webroot and add the following location inside the port 80 server block in nimsuite.conf:
location /.well-known/acme-challenge/ {
    root C:/win-acme/webroot;
}
  1. Run nginx -t, then restart the NGINX service.
  2. Run wacs.exe, choose a new certificate with simple options, enter the public hostname, and use FileSystem validation with C:\win-acme\webroot.
  3. Add the generated certificate and key paths to the HTTPS server block:
ssl_certificate     C:/ProgramData/win-acme/.../apps.example.com-chain.pem;
ssl_certificate_key C:/ProgramData/win-acme/.../apps.example.com-key.pem;
  1. Run nginx -t and restart NGINX again.

Port 80 must remain publicly reachable for HTTP-01 validation and renewal. win-acme creates a scheduled renewal task; ensure NGINX reloads after a successful renewal so it serves the updated certificate.

Verify the deploymentDirect link to Verify the deployment

  • Confirm an approved app loads at https://apps.example.com/app/<app-name>.
  • Confirm Studio and /api/cmd/admin return 403 from the public hostname.
  • Confirm onboarding, password reset, and SAML sign-in work as expected.
  • Optionally run ./wacs.exe --renew --force, restart NGINX, and confirm the certificate has been updated.

For eligible organizations, CISA Cyber Hygiene Services can provide external vulnerability and web application scanning. Use the results to review the public NGINX host and approved Apps, then recheck route restrictions after changes. Coordinate scanning with your security team and service owners.

TroubleshootingDirect link to Troubleshooting

Choose the card that matches the symptom. After changing the proxy configuration, run nginx -t, restart NGINX, and repeat the affected check from Verify the deployment.

NGINX does not startDirect link to NGINX does not start

Problem

NGINX does not start

Likely cause

The NGINX configuration has an error, or the NSSM service uses the wrong startup directory.

Resolution

Run nginx -t from C:\nginx and correct any reported error. Confirm the NSSM service startup directory is C:\nginx, then restart it.

502 Bad GatewayDirect link to 502 Bad Gateway

Problem

502 Bad Gateway

Likely cause

NGINX cannot reach the NIM Service at the configured upstream address or port.

Resolution

Verify the generated upstream address and port, then confirm the NGINX server can reach the NIM Service. Test the public app again after correcting the connection.

A public app failsDirect link to A public app fails

Problem

A public app fails

Likely cause

The generated proxy configuration does not allow that app, or its route selection is out of date.

Resolution

Re-download the configuration from NIM Studio, review the app allow or deny selection, then test the approved public route.

Studio is reachable publiclyDirect link to Studio is reachable publicly

Problem

Studio is reachable publicly

Likely cause

The proxy configuration is missing or bypassing the restrictions for Studio and administrative routes.

Resolution

Stop using the configuration. Re-download it from Studio, verify the restrictive routes are present, and confirm public requests to Studio and /api/cmd/admin are denied before resuming access.

ACME validation failsDirect link to ACME validation fails

Problem

ACME validation fails

Likely cause

The public hostname, port 80 route, or ACME challenge location is unavailable to the certificate authority.

Resolution

Confirm the hostname resolves to NGINX, port 80 is reachable, and the ACME location has been loaded. Retry validation after correcting the path.

Certificate renewal failsDirect link to Certificate renewal fails

Problem

Certificate renewal fails

Likely cause

The win-acme renewal task failed or did not complete.

Resolution

Check the win-acme renew (main) scheduled task and run ./wacs.exe --renew to view the error. Resolve it, then confirm NGINX serves the renewed certificate.

Last updated on