ServiceNow PrivX Integration

This repository contains design, implementation artifacts, and operational documentation for integrating ServiceNow with PrivX.

The integration currently focuses on two use cases:

• UC01: Time-bound privileged host access request from ServiceNow to PrivX, including provisioning and automatic revoke.
• UC02: Secret retrieval from PrivX Vault for ServiceNow-driven third-party integrations.

What Is In Scope

• Use-case definitions and business flow descriptions
• Architecture diagrams in PlantUML and exported assets
• ServiceNow scripts, including actions, client scripts, scheduled jobs, script includes, and table documentation
• PrivX configuration guidance
• API endpoint references for integration work
• Developer setup notes

Repository Structure

.
|-- 00-use-cases/
|   |-- UC01 – Time-Bound Privileged Host Access Request.md
|   `-- UC02 - ServiceNow Discovery with PrivX External Credential Resolver.md
|-- 01-architecture/
|   `-- diagrams/
|       |-- UC01/
|       `-- UC02/
|-- 02-servicenow/
|   |-- UC01/
|   |   |-- actions/
|   |   |-- catalog/
|   |   |-- client_scripts/
|   |   |-- flows/
|   |   |-- scheduled_jobs/
|   |   |-- script_includes/
|   |   |-- tables/
|   |   `-- update_sets/
|   `-- UC02/
|       |-- infrastructure/
|       |   |-- external-credential-resolver/
|       |   `-- mid-server/
|       `-- README.md
|-- 03-privx/
|   |-- UC01/
|   |   `-- config.md
|   `-- UC02/
|       `-- config.md
|-- 04-rest-api/
|   |-- UC01/
|   |   `-- README.md
|   `-- UC02/
|       `-- README.md
|-- 05-developer-guide/
|   `-- UC01.md

Start Here

1. Review use-case intent:
   • UC01 time-bound host access
   • UC02 ServiceNow Discovery with PrivX External Credential Resolver
2. Review architecture:
   • UC01 architecture
   • UC02 architecture
3. Configure PrivX API authentication:
   • UC01 PrivX configuration
   • UC02 PrivX configuration
4. Review API contracts:
   • UC01 REST API notes
   • UC02 REST API notes
5. Implement in ServiceNow using the scripts and setup notes in 02-servicenow.
6. Follow the developer setup checklist in 05-developer-guide/UC01.md.

UC01 Implementation Pointers

• Fresh PDI setup guide: 02-servicenow/UC01/README.md
• Actions: 02-servicenow/UC01/actions
• Client scripts: 02-servicenow/UC01/client_scripts
• Scheduled jobs and revoke flow: 02-servicenow/UC01/scheduled_jobs
• Script include: 02-servicenow/UC01/script_includes
• Table documentation: 02-servicenow/UC01/tables

UC02 Implementation Pointers

• Use-case definition: 00-use-cases/UC02 - ServiceNow Discovery with PrivX External Credential Resolver.md
• Fresh PDI setup guide: 02-servicenow/UC02/README.md
• PrivX configuration note: 03-privx/UC02/config.md
• MID Server installation note: 02-servicenow/UC02/infrastructure/mid-server/overview.md

Prerequisites

• ServiceNow developer instance with admin-level configuration access
• PrivX test or development environment with API client configuration access
• Network path from ServiceNow or a MID Server to the required PrivX endpoints
• Environment-specific OAuth client, scopes, roles, and credential storage configured outside this repository

Notes

• Naming uses UC01 and UC02 across docs and scripts for traceability.
• Some folders are scaffolding for packaging and runbook content and may be intentionally sparse.
• Treat local scratch or test scripts as non-production artifacts unless they are explicitly documented as implementation files.

Security And Compliance

• Do not commit real credentials, API keys, OAuth client secrets, tokens, private certificates, or production hostnames.
• Store OAuth client secrets and tokens in ServiceNow credential storage or another approved secret manager.
• Use sample values in documentation and code snippets.
• Perform an environment-specific security review before production rollout.

Support & Commercial Services

This is a public open-source project licensed under Apache 2.0 and not covered by standard support SLA. Community feedback and contributions are welcome. Support is provided on a best-effort basis only.

For dedicated support, customisations, or enterprise assistance, please raise a ticket via the SSH support portal or via your local support partner. Any requests will be assigned to your account manager.

License

This project is licensed under the Apache License 2.0. See LICENSE.