Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
docs: update old servicenow docs to match the current behavior
adilson08445ef290c5
diff --git a/docs/documentation/platform/access-controls/access-requests.mdx b/docs/documentation/platform/access-controls/access-requests.mdxindex 3a2ac7a6e1..50d2555724 100644--- a/docs/documentation/platform/access-controls/access-requests.mdx+++ b/docs/documentation/platform/access-controls/access-requests.mdx@@ -73,6 +73,10 @@ The **Bypass Approvals** option enables emergency access in break-glass situatioWhen **Self Approvals** is disabled, approvers can't approve their own requests through the normal workflow. They can only grant themselves access via break-glass bypass if **Bypass Approvals** is enabled and they're explicitly listed as a bypass user or group member. If no bypass users or groups are configured, self-approval is blocked entirely.</Warning>+### Approving requests in an external system++Under **Approval Workflow**, you can set a policy to send its requests to an external approval system instead of to approvers in Infisical. Nobody can approve those requests in Infisical, so the approval steps, self-approval, and bypass settings don't apply to the policy. To set this up with ServiceNow, see the [ServiceNow integration](/documentation/platform/workflow-integrations/servicenow-integration).+## Submitting access requestsOnce access policies are configured, users can request access to resources covered by those policies.diff --git a/docs/documentation/platform/audit-logs.mdx b/docs/documentation/platform/audit-logs.mdxindex d6c76321ec..8b8ccf7db3 100644--- a/docs/documentation/platform/audit-logs.mdx+++ b/docs/documentation/platform/audit-logs.mdx@@ -1023,6 +1023,7 @@ Infisical emits hundreds of event types. Here are some of the most common ones y| `approval-request-create`, `approval-request-approve`, `approval-request-reject`, `approval-request-cancel` | The lifecycle of an approval request. || `access-approval-request-create`, `access-approval-request-review`, `access-approval-request-update`, `access-approval-request-revoke` | The lifecycle of an access approval request. || `access-approval-request-delegated-dispatch-retry` | A user retried an access approval request that never reached its external approval system, such as [ServiceNow](/documentation/platform/workflow-integrations/servicenow-integration). |+ | `access-approval-request-delegated-decision` | Infisical applied, or failed to apply, a decision that an external approval system such as ServiceNow returned for an access approval request. The event's actor is `platform`. || `access-approval-request-cancel` | A user cancelled a pending access approval request that its external approval system was reviewing. || `secret-approval-request`, `secret-approval-request-review`, `secret-approval-merged`, `secret-approval-closed`, `secret-approval-reopened` | The lifecycle of a secret change request. || `approval-policy-create`, `approval-policy-update`, `approval-policy-delete` | An admin changed an approval policy. |diff --git a/docs/documentation/platform/workflow-integrations/servicenow-integration.mdx b/docs/documentation/platform/workflow-integrations/servicenow-integration.mdxindex 1ace20a2a0..77d532b5d6 100644--- a/docs/documentation/platform/workflow-integrations/servicenow-integration.mdx+++ b/docs/documentation/platform/workflow-integrations/servicenow-integration.mdx@@ -1,155 +1,243 @@----title: "ServiceNow integration"+title: "Access Approvals in Servicenow"description: "Route Infisical access requests through ServiceNow approval flows."---<Info>The ServiceNow integration is opt-in and only available on Enterprise plans.- Contact [[email protected]](mailto:[email protected]) to opt-in and gain access to the ServiceNow Integration.+ Contact [[email protected]](mailto:[email protected]) to get access to the+ ServiceNow integration.</Info>-The ServiceNow integration hands the approval decision for an Infisical [access request](/documentation/platform/access-controls/access-requests) to ServiceNow. Instead of approving in Infisical, your approvers review the request in ServiceNow, where it inherits the governance you already run there: multi-step routing, group approvals, delegation, CAB review, notifications, and audit history.+The ServiceNow integration hands the approval decision for an Infisical [access request](/documentation/platform/access-controls/access-requests) to ServiceNow. Instead of approving in Infisical, your approvers review the request in ServiceNow, where it goes through the approval process you already run there.-Infisical stays the enforcement point. It creates the request, waits for ServiceNow to return a decision, and grants or denies the access itself. ServiceNow never touches your secrets.+Infisical still grants the access. It creates the request, waits for ServiceNow to return a decision, and grants or denies the access itself. ServiceNow never sees your secrets.## How it works1. A user requests access in Infisical to an environment and secret path.2. The request matches an access policy that sends its requests to ServiceNow.-3. Infisical creates an Infisical Access Request record on your ServiceNow instance over the ServiceNow app connection.-4. A ServiceNow flow you own routes that record to the right approvers.-5. When the flow reaches a decision, its final step calls the **Infisical - Notify Decision** action, which tells Infisical that the record has a decision.-6. Infisical reads the decision from the record, then grants the access on approval or closes the request on rejection.+3. Infisical creates an **Infisical Access Request** record on your ServiceNow instance over the [ServiceNow connection](/integrations/app-connections/servicenow). The record includes a callback token that Infisical issued for this request alone.+4. A ServiceNow flow you own routes the record to the right approvers.+5. When the flow reaches a decision, its final step runs the **Infisical - Notify Decision** action. The action records the decision on the record, then sends the callback token to Infisical to say the record has a decision.+6. Infisical reads the decision from the record over the ServiceNow connection, then grants the access on approval or closes the request on rejection.-You don't create an Infisical credential for ServiceNow. Each record carries a token that Infisical issued for that request alone, and the **Infisical - Notify Decision** action sends that token to Infisical with its notice.+If the policy sets a request expiration and ServiceNow doesn't return a decision in time, the request expires in Infisical. Infisical never grants access without an approval from ServiceNow.-If ServiceNow never returns a decision, the request expires in Infisical according to the policy's request expiration setting. Access is never granted by default.+## Prerequisites-## What you need+- A Secrets Management project on Infisical with Access Requests available+- A ServiceNow instance where you can install a scoped application, create users, and build flows in Flow Designer (the `flow_designer` role)+- A ServiceNow instance that Infisical can reach (if your instance restricts inbound traffic, allow [Infisical's IP addresses](/documentation/setup/networking) on its IP access control list)+- Outbound HTTPS access from your ServiceNow instance to your Infisical URL+- If you self-host Infisical, a [`SITE_URL`](/self-hosting/configuration/envars) that starts with `https://`, because ServiceNow notifies Infisical at that address-- A Secrets Management project on Infisical with Access Requests available.-- A ServiceNow instance where you can install a scoped application, create users, and use Flow Designer.-- Network reachability in both directions: Infisical must reach your ServiceNow instance, and your ServiceNow instance must reach your Infisical URL.-- If you self-host Infisical, a [`SITE_URL`](/self-hosting/configuration/envars) that starts with `https://` (ServiceNow notifies Infisical at that address).--## Setup+## Step 1: Install the Infisical application<Steps>- <Step title="Install the Infisical application on your ServiceNow instance">- Install the application package provided by Infisical. Once installed, an **Infisical** application menu appears in the navigator with these modules:+ <Step>+ Install the application package that Infisical provides on your ServiceNow instance.- - **Access Requests**: every request Infisical has sent.- - **Pending Requests**: requests awaiting a decision.- - **Admin Console**: a single-page view of the above.+ The application adds an **Infisical** menu to the navigator with these modules:- The application also installs four roles:+ - **Access Requests**: every request Infisical has sent+ - **Pending Requests**: requests waiting for a decision+ - **Admin Console** (admins only): every request, with a **Resend to Infisical** button for a decision that didn't reach Infisical- | Role | Grants |- | --- | --- |- | `x_infis_approvals.admin` | Full access to every request, including delete, and the **Admin Console**. |- | `x_infis_approvals.approver` | View and decide on access requests. |- | `x_infis_approvals.viewer` | Read-only access to requests and their audit trail. |- | `x_infis_approvals.secret-manager-integration` | API-only role used by Infisical to create requests. |+ You can't approve or reject a request from these modules. Your approvers decide in the approval steps of your flows, which you build in [Step 3](#step-3-build-the-approval-flow).- Assign `x_infis_approvals.admin` to the people who manage the integration, and `x_infis_approvals.approver` to your approver groups.+ </Step>+ <Step>+ Assign the application's roles:++ | Role | Assign it to |+ | --- | --- |+ | `x_infis_approvals.admin` | The people who manage the integration. The role grants full access to every request, including delete, and the **Admin Console**. |+ | `x_infis_approvals.approver` | Every user or group that an **Ask for Approval** step in your flows names as an approver. |+ | `x_infis_approvals.viewer` | People who only need to read requests and their audit trail. |+ | `x_infis_approvals.secret-manager-integration` | Only the integration user that Infisical signs in as, which you create in [Step 2](#step-2-connect-infisical-to-servicenow). |</Step>+</Steps>- <Step title="Connect Infisical to ServiceNow">- Create a ServiceNow integration user, then create a **ServiceNow Connection** in Infisical using that user's credentials. Follow the [ServiceNow Connection](/integrations/app-connections/servicenow) guide.+## Step 2: Connect Infisical to ServiceNow- This connection is how Infisical writes requests into ServiceNow. It is deliberately one-directional: the integration user can create and read access request records and nothing else.+Create a ServiceNow integration user, then create a ServiceNow connection in Infisical with that user's credentials. Follow the [ServiceNow connection](/integrations/app-connections/servicenow) guide.- </Step>+Infisical uses this connection to create each record and to read each decision back. If the connection's credentials stop working, Infisical can't complete the requests waiting in ServiceNow.- <Step title="Build the approval flow">- Approval routing is entirely yours to define in Flow Designer. Infisical doesn't dictate approvers, steps, or SLAs.+## Step 3: Build the approval flow- The fastest path is to clone the included template:+You define approval routing in Flow Designer. Infisical doesn't set approvers, steps, or SLAs. The fastest way to start is to copy the flow template that the Infisical application includes:- 1. Go to **All > Process Automation > Flow Designer**.- 2. Open **Infisical - Single Approval Template** and select **Copy Flow**.- 3. Adjust the trigger condition. The trigger is a record created on **Infisical Access Request [x_infis_approvals_access_request]**, and the condition is what decides which requests this flow owns, for example `Environment is prod` or `Secret Path contains /payments`.- 4. Fill in the approvers on each **Ask for Approval** step, along with the number of approvals required.- 5. Confirm that every branch, approved and rejected alike, ends with an **Update Record** action setting **State**, followed by the **Infisical - Notify Decision** action.- 6. Activate the flow.+<Steps>+ <Step>+ Go to **All** > **Process Automation** > **Flow Designer**.+ </Step>+ <Step>+ Open **Infisical - Single Approval Template** and select **Copy Flow**.+ </Step>+ <Step>+ Set the trigger condition. The flow runs when a record is created in **Infisical Access Request [x_infis_approvals_access_request]**, and the condition sets which requests the flow handles, such as `Environment is prod` or `Secret Path contains /payments`. The template's condition, `Request Type is Secret Access`, matches every request from Infisical.+ </Step>+ <Step>+ On each **Ask for Approval** step, add the approvers and the number of approvals required. Every approver needs the `x_infis_approvals.approver` role.+ </Step>+ <Step>+ Confirm that every branch, approved and rejected alike, ends with the **Infisical - Notify Decision** action.+ </Step>+ <Step>+ Activate your copy of the flow. The template itself stays inactive.+ </Step>+</Steps>- The **Infisical - Notify Decision** action takes two inputs:+To build a flow from scratch instead, trigger it when a record is created in **Infisical Access Request**, route the record with **Ask for Approval** steps, and end each branch with **Infisical - Notify Decision**. If you have more than one flow, make their trigger conditions mutually exclusive. If two flows match the same record, approvers get duplicate approvals.- | Input | Value |- | --- | --- |- | **Access Request** | The trigger record. |- | **Decision** | `approved` or `rejected`. |+### Notify Infisical of the decision- It returns Success and Message outputs, which you can branch on to raise an incident or notify an admin if the callback fails.+The **Infisical - Notify Decision** action records the decision on the record, updates the record's **State**, and notifies Infisical. It takes two inputs:- <Warning>- Every terminal branch of your flow must call **Infisical - Notify Decision**.- A branch that ends without it leaves the request pending in Infisical until it- expires, and the requester gets no answer.- </Warning>+| Input | Value |+| -------------------------------- | ------------------------ |+| **Access Request** | The trigger record |+| **Decision (approved/rejected)** | `approved` or `rejected` |- Building from scratch instead of cloning works the same way: trigger on record creation, route with **Ask for Approval** steps, and finish each branch with **Infisical - Notify Decision**. Keep trigger conditions mutually exclusive across flows, otherwise two flows will both route the same request and approvers will see duplicates.+If **Decision (approved/rejected)** has any other value, the action records no decision and moves the record to **Callback Failed**.- </Step>+The action returns **Success** and **Message** outputs. You can branch on them to raise an incident or notify an admin if the action can't notify Infisical.- <Step title="Enable ServiceNow approvals on an access policy">- In your Secrets Management project, go to **Approvals > Policies** and create or edit an **Access Policy**. Set:+<Warning>+ Every branch that ends your flow must call **Infisical - Notify Decision**. If+ a branch ends without it, the request stays pending in Infisical until it+ expires, and the requester gets no answer.+</Warning>- - **Approval Workflow**: **External Approval System**.- - **Provider**: **ServiceNow**.- - **App Connection**: the connection created in step 2.- - **Environments** and **Secret Path**: what this policy governs, as with any access policy.- - **Request Expiration**: how long a request may sit in ServiceNow before Infisical closes it.+## Step 4: Enable ServiceNow approvals on an access policy++<Steps>+ <Step>+ In your Secrets Management project, select **Approvals** from the sidebar, open the **Policies** tab, and select **Add Policy**. To change an existing access policy instead, edit it from the same tab.+ </Step>+ <Step>+ Set **Policy Type** to **Access Policy**, then fill out **Policy Name**, **Secret Path**, and **Environments** as for any [access policy](/documentation/platform/access-controls/access-requests#policy-configuration-options).+ </Step>+ <Step>+ Optionally, set **Request Expiration** to how long a request can wait in ServiceNow before Infisical closes it. If you leave it empty, requests never expire.+ </Step>+ <Step>+ Under **Approval Workflow**, select **External Approval System**, then set:- Requests matching this policy are now routed to ServiceNow. Policies set to the **Infisical** workflow keep using in-app approvers, so you can move one environment at a time.+ - **Provider**: **ServiceNow**+ - **App Connection**: the connection you created in [Step 2](#step-2-connect-infisical-to-servicenow)</Step>+ <Step>+ Select **Add Policy**, or **Update Policy** if you're editing an existing policy.+ </Step></Steps>+Requests that match this policy now go to ServiceNow. Policies that use the **Infisical** workflow keep using approvers in Infisical, so you can move one environment at a time.++A policy that sends its requests to ServiceNow differs from one with Infisical approvers:++- Nobody can approve its requests in Infisical, so the policy has no approvers, bypassers, or self approval+- You can't edit the policy while it has pending requests (cancel them first, as described in [Follow a request in Infisical](#follow-a-request-in-infisical))++## Follow a request in Infisical++On the **Access Requests** tab, a request sent to ServiceNow shows one of these badges while it's pending:++| Badge | Meaning |+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |+| **Submitting** | Infisical is creating the record in ServiceNow. If ServiceNow can't be reached, Infisical keeps trying for about an hour, then closes the request. |+| **Pending in ServiceNow** | The record exists, and Infisical is waiting for your flow's decision. |+| **Not Submitted** | Infisical couldn't create the record. Open the request to see why. |++Open a request to see its **Status**, the number of its ServiceNow record, and the reason for any failure. From there, you can take two actions:++- **Retry**: sends a **Not Submitted** request to ServiceNow again, once you've fixed the cause (the requester and anyone who can view the project's approval requests can retry)+- **Cancel Request**: closes a pending request (the requester and anyone who can edit the project's approval policies can cancel)++**Cancel Request** is the only way to close a request from Infisical before ServiceNow decides.++Infisical doesn't update the ServiceNow record after creating it. If you cancel a request, or it expires, the record stays in **Pending Approval** in ServiceNow, and Infisical ignores any decision your flow makes on it afterward.+## What ServiceNow receives-Each request becomes one **Infisical Access Request** record, numbered `INFAR<number>`. Infisical shows that number on the request's review sheet, so you can find the matching record in ServiceNow.+Each request becomes one **Infisical Access Request** record, numbered `INFAR<number>`. Infisical shows that number on the request, so you can find the matching record in ServiceNow.++Infisical fills in these fields when it creates the record:-| Field | Contents |-| ------------------------- | --------------------------------------------------------------------------- |-| Request Type | The kind of access requested. During beta this is always **Secret Access**. |-| Requestor Email | The Infisical user who made the request. |-| Project Name / Project ID | The Infisical project the request targets. |-| Environment | The environment slug, for example `prod`. |-| Secret Path | The folder path being requested. |-| Permissions | The permissions requested, for example `read`. |-| Duration Type / Duration | Temporary with a duration, or permanent. |-| Justification | The reason the requester supplied. |-| Infisical Request ID | The Infisical request this record corresponds to. |-| State | Where the request stands, see below. |+| Field | Contents |+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Request Type | The kind of access requested, currently always Secret Access. |+| Requestor Email / Requestor Name | The Infisical user who made the request. |+| Project Name / Project ID | The Infisical project the request targets. |+| Environment | The environment slug, for example `prod`. |+| Secret Path | The folder path being requested. |+| Permissions | The permissions requested, one line per resource, for example `secrets: read, edit`. |+| Duration Type / Duration | Temporary with a duration, or permanent. |+| Justification | The reason the requester gave. |+| Infisical Request ID | The Infisical request this record corresponds to. |+| Callback URL | The Infisical address that **Infisical - Notify Decision** sends its notice to. It can't be changed, so a new `SITE_URL` only applies to new requests. |+| Callback Token | The token that proves a notice comes from this record. ServiceNow stores it encrypted and shows it to nobody, including admins. |-The record is a mirror of the request. Infisical grants what the request asked for, never what the record says. If the **Permissions** field on the record no longer matches the request when it's approved, Infisical cancels the request instead of granting access.+**Infisical - Notify Decision** fills in these fields:++| Field | Contents |+| -------------- | -------------------------------------------------------- |+| Decision | `approved` or `rejected`. Once set, it can't be changed. |+| Decision Date | When the action recorded the decision. |+| Callback Error | Why the action couldn't notify Infisical, if it failed. |++The record is a copy of the request. Infisical grants what the request asked for, never what the record says. If someone changes the **Permissions** field before the request is approved, Infisical closes the request instead of granting access. Changes to spacing, order, or letter case don't count.### States-| State | Meaning |-| ------------------- | ------------------------------------------------------------------ |-| Pending Approval | Waiting on your flow. |-| Approved / Rejected | Your flow reached a decision. |-| Notifying Infisical | The decision is being sent back. |-| Completed | Infisical acknowledged the approval. |-| Callback Failed | The decision couldn't be delivered. See the Callback Error field. |-| Expired | Closed without a decision. |+| State | Meaning |+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Pending Approval | Waiting on your flow. |+| Approved | Your flow approved the request, and **Infisical - Notify Decision** hasn't run yet. |+| Rejected | Your flow rejected the request. The record stays in this state after Infisical receives the rejection. |+| Notifying Infisical | **Infisical - Notify Decision** is notifying Infisical. |+| Completed | Infisical received the approval. It then reads the decision from the record and grants the access, unless it has to close the request (see [Requests closed by Infisical](#requests-closed-by-infisical)). |+| Callback Failed | **Infisical - Notify Decision** couldn't notify Infisical. See the **Callback Error** field. |## Auditing-Both sides keep their own record. In ServiceNow, the access request record carries the full approval history, including who approved at each step and when, through the standard approval and audit tables. In Infisical, the request and the resulting access grant appear in the project's audit log along with the decision received from ServiceNow.+Both sides keep their own record:++- In ServiceNow, the access request record carries the full approval history, including who approved at each step and when, through the standard approval and audit tables+- In Infisical, the project's [audit log](/documentation/platform/audit-logs) records the request, the decision received from ServiceNow (`access-approval-request-delegated-decision`), and the resulting access grant++If your flow fills in **Approved By** or **Decision Notes** on the record, Infisical copies them into the decision's audit log event.## Troubleshooting-| Symptom | Cause and fix |-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Requests never appear in ServiceNow | The policy doesn't send its requests to ServiceNow, or the environment and secret path on the policy don't match the request. Check the Infisical audit log for the delivery attempt. |-| Record created but nothing happens | No active flow matches the record. Verify your flow is activated and its trigger condition matches the record's field values. |-| Approvers see duplicate approvals | Two flows match the same record. Make the trigger conditions mutually exclusive and deactivate the one you no longer want. |-| State stuck at Notifying Infisical | The callback is in flight or the flow errored mid-step. Check the flow's execution details. |-| Callback Failed with HTTP 403 | Infisical already closed this request, the request was deleted along with its project, or ServiceNow notified Infisical about the request more than five times. Check the request's status in Infisical, and create the request again if the requester still needs access. |-| Callback Failed with a connection error | The ServiceNow instance can't reach the **Callback URL** on the record. Fix the instance's outbound firewall rules, then select **Resend to Infisical** on the request in the **Admin Console**. If the URL itself is wrong, correct `SITE_URL` and create the request again. |-| Request expired before approval | The policy's request expiration elapsed while the request sat in ServiceNow. Extend it, or shorten your approval SLA. |-| Infisical says the request couldn't be completed in ServiceNow | Infisical couldn't apply the decision. The reason is shown under the request status: the **Permissions** field was changed in ServiceNow, the record was deleted, or ServiceNow rejected the integration user's credentials. Fix the cause and create the request again. |+| Symptom | Cause and fix |+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| A request shows **Not Submitted** in Infisical | Infisical couldn't create the record, and the reason on the request says why: the integration user's credentials or role, a missing Infisical application, or, if you self-host, a missing `SITE_URL`. Fix the cause, then select **Retry**. For connection problems, see [ServiceNow connection troubleshooting](/integrations/app-connections/servicenow#troubleshooting). |+| A request shows **Submitting** for a long time | Infisical can't reach the instance, or the instance returns errors. Infisical keeps trying for about an hour, then closes the request. Check that the instance is up and reachable from Infisical. |+| Record created but nothing happens | No active flow matches the record. Verify your flow is activated and its trigger condition matches the record's field values. |+| Approvers see duplicate approvals | Two flows match the same record. Make the trigger conditions mutually exclusive and deactivate the one you no longer want. Only the first flow to finish notifies Infisical. In the other flow, **Infisical - Notify Decision** returns an error. |+| State stuck at Notifying Infisical | The flow stopped partway through **Infisical - Notify Decision**. Check the flow's **Executions** tab in Flow Designer. |+| Callback Failed with HTTP 403 | Infisical refused the notice because it already applied a decision to this request or closed it, the request was deleted along with its project, or ServiceNow notified Infisical about the request more than five times. Check the request's status in Infisical, and create the request again if the requester still needs access. |+| Callback Failed with a connection error | The ServiceNow instance can't reach the **Callback URL** on the record. Fix the instance's outbound firewall rules, then select **Resend to Infisical** on the request in the **Admin Console**. If the URL itself is wrong, correct `SITE_URL` and create the request again. |+| Callback Failed with an invalid decision | The flow passed a value other than `approved` or `rejected` to **Infisical - Notify Decision**. **Resend to Infisical** can't help, because no decision was recorded. Fix the flow, then cancel the request in Infisical and create it again. |+| Callback Failed on a record that has no callback URL, event, or callback token | Someone created the record in ServiceNow by hand, so ServiceNow can't notify Infisical about it. Test your flows with requests made in Infisical. |+| Request expired before approval | The policy's **Request Expiration** elapsed while the request sat in ServiceNow. Extend it, or shorten your approval SLA. |+| Infisical says the request couldn't be completed in ServiceNow | Infisical closed the request without granting access. See [Requests closed by Infisical](#requests-closed-by-infisical). |++### Requests closed by Infisical++If Infisical can't finish a request in ServiceNow, it closes the request without granting access. The reason appears under the request's **Status**, and is one of these:++- Someone changed the **Permissions** field on the record+- Someone deleted the record from ServiceNow+- ServiceNow rejected the integration user's credentials when Infisical read the decision+- The requester's user was deleted, or the requester is no longer a member of the project+- The decision arrived after the request expired or was cancelled in Infisical+- ServiceNow notified Infisical about the request more than five times+- Infisical couldn't create the record after about an hour of trying++Fix the cause, then create the request again.diff --git a/docs/integrations/app-connections/servicenow.mdx b/docs/integrations/app-connections/servicenow.mdxindex c020c82be0..f79112d0b1 100644--- a/docs/integrations/app-connections/servicenow.mdx+++ b/docs/integrations/app-connections/servicenow.mdx@@ -1,92 +1,149 @@---title: "ServiceNow connection"sidebarTitle: "ServiceNow"-description: "Learn how to configure a ServiceNow Connection for Infisical."+description: "Learn how to configure a ServiceNow connection for Infisical."---<Info>The ServiceNow integration is opt-in and only available on Enterprise plans.- Contact [[email protected]](mailto:[email protected]) to opt-in and gain access to the ServiceNow Integration.+ Contact [[email protected]](mailto:[email protected]) to get access to the+ ServiceNow integration.</Info>-Infisical connects to ServiceNow using basic authentication. The connection is used to create and read approval records in the Infisical application installed on your ServiceNow instance.+A ServiceNow connection authenticates Infisical to your ServiceNow instance with the username and password of a ServiceNow integration user. Infisical uses the connection to create access requests in the Infisical application on your instance, and to read back the decision your approvers make on each one.++<Note>+ This guide only authenticates Infisical with ServiceNow. Once the app+ connection is ready, you can [use it to set up+ integrations](#step-3-configure-integrations).+</Note>## Prerequisites-- The Infisical application installed on your ServiceNow instance. See the [ServiceNow Integration](/documentation/platform/workflow-integrations/servicenow-integration) guide for installation.-- Permission to create users and assign roles on the ServiceNow instance.-- A ServiceNow instance that Infisical can reach over the public internet. If your instance restricts inbound traffic, allow Infisical's egress IPs on its IP access control list.+- The Infisical application installed on your ServiceNow instance (see [Step 1 of the ServiceNow integration](/documentation/platform/workflow-integrations/servicenow-integration#step-1-install-the-infisical-application))+- Permission to create users and assign roles on the instance+- A ServiceNow instance that Infisical can reach (if your instance restricts inbound traffic, allow [Infisical's IP addresses](/documentation/setup/networking) on its IP access control list)-## Create a ServiceNow integration user+## Step 1: Create a ServiceNow integration user-Use a dedicated ServiceNow user for the connection rather than a personal account. This keeps the audit trail clear and lets you rotate the credential without affecting anyone's access.+Infisical signs in to ServiceNow as a dedicated integration user. Use a new user rather than a personal account, so you can change its password without affecting anyone's access.<Steps>- <Step title="Create the user">- In ServiceNow, navigate to **All > User Administration > Users** and select **New**.-- Set the following:-- - **User ID**: an identifier such as `infisical.integration`.- - **First name** / **Last name**: a recognizable name such as `Infisical Integration`.- - **Password**: a strong password. Save it, you will need it in Infisical.- - **Web service access only**: checked. This prevents the account from being used to sign in to the ServiceNow UI.- - **Active**: checked.-- Submit the form, then reopen the record.-+ <Step>+ In ServiceNow, go to **All** > **User Administration** > **Users** and select **New**.</Step>- <Step title="Assign the integration role">- In the **Roles** related list on the user record, select **Edit** and add:+ <Step>+ Fill out the user's fields:- ```- x_infis_approvals.secret-manager-integration- ```+ - **User ID**: an identifier such as `infisical.integration`+ - **First name** and **Last name**: a recognizable name such as `Infisical Integration`+ - **Password**: a strong password, which you'll enter in Infisical in [Step 2](#step-2-create-the-app-connection)+ - **Web service access only**: checked, so nobody can use the account to sign in to the ServiceNow UI+ - **Active**: checked- This role grants exactly what Infisical needs: the ability to create and read Infisical access request records. It does not grant approval rights or access to anything else on the instance.+ Then, select **Submit** and open the user record again.</Step>- <Step title="Note your instance URL">- Your instance URL is the base URL of your ServiceNow instance, for example- `https://dev12345.service-now.com`. Do not include a path or trailing slash.- </Step>-</Steps>+ <Step>+ In the **Roles** related list on the user record, select **Edit** and add the `x_infis_approvals.secret-manager-integration` role.-## Create a ServiceNow connection in Infisical+ This role lets Infisical create access requests in the Infisical application and read their decisions. It doesn't grant approval rights or access to anything else on the instance.-<Steps>- <Step title="Navigate to App Connections">- Go to **Integrations** > **App Connections** and select **Add Connection**. You can create the connection at- the organization level, or inside the Secrets Management project that uses it.</Step>- <Step title="Select ServiceNow">- Choose **ServiceNow** from the list of available connections.+ <Step>+ Copy the base URL of your instance, such as `https://dev12345.service-now.com`. The URL must use HTTPS and can't include a path or a query string.</Step>- <Step title="Fill in the connection details">- - **Name**: a descriptive name such as `servicenow-prod`.- - **Description** (optional): what this connection is used for.- - **Instance URL**: the base URL of your ServiceNow instance, for example `https://dev12345.service-now.com`.- - **Username**: the User ID of the integration user.- - **Password**: the password for the integration user.-- Click **Connect to ServiceNow**. Infisical validates the credentials against the instance before saving.+</Steps>- </Step>- <Step title="Connection created">- The connection is now available to select when configuring an access policy with ServiceNow approvals.+## Step 2: Create the app connection++Next, create the app connection in Infisical.++<Tip>+ To create the connection using the API, use the [Create ServiceNow+ Connection](/api-reference/endpoints/app-connections/servicenow/create)+ endpoint.+</Tip>++<View title="Organization-level">+ <Steps>+ <Step>+ In the sidebar, select **Integrations**, then open the **App Connections** tab.+ </Step>+ <Step>+ Select **Add Connection** and choose **ServiceNow**.+ </Step>+ <Step>+ Fill out the form's fields:++ - **Name**: a name for the connection, such as `servicenow-prod`+ - **Description** (optional): what the connection is used for+ - **Method**: **Basic Auth**+ - **Instance URL**: the base URL you copied in [Step 1](#step-1-create-a-servicenow-integration-user)+ - **Username**: the **User ID** of the integration user+ - **Password**: the integration user's password++ Then, select **Connect to ServiceNow**.+ </Step>+ </Steps>++</View>++<View title="Project-level">+ <Steps>+ <Step>+ In your Secrets Management project, select **Integrations** from the sidebar, then open the **App Connections** tab.+ </Step>+ <Step>+ Select **Add Connection** and choose **ServiceNow**.+ </Step>+ <Step>+ Fill out the form's fields:++ - **Name**: a name for the connection, such as `servicenow-prod`+ - **Description** (optional): what the connection is used for+ - **Method**: **Basic Auth**+ - **Instance URL**: the base URL you copied in [Step 1](#step-1-create-a-servicenow-integration-user)+ - **Username**: the **User ID** of the integration user+ - **Password**: the integration user's password++ Then, select **Connect to ServiceNow**.+ </Step>+ </Steps>++</View>++Before Infisical saves the connection, it checks that the username and password sign in to the instance. It doesn't check the integration user's role or whether the Infisical application is installed. If either one is missing, the first access request sent over the connection shows **Not Submitted** (see [Troubleshooting](#troubleshooting)).++<Check>Your ServiceNow app connection is ready to use.</Check>++## Step 3: Configure integrations++Now that your ServiceNow app connection is configured, you can use it to set up the following integration:++<Card+ title="ServiceNow integration"+ icon="workflow"+ href="/documentation/platform/workflow-integrations/servicenow-integration"+>+ Route Infisical access requests through ServiceNow approval flows.+</Card>- Infisical verifies that the username and password authenticate against the instance. It does not check the integration role or whether the Infisical application is installed. A problem with either one surfaces the first time Infisical sends an access request.- </Step>-</Steps>+## Troubleshooting-## Rotating the credential+| Symptom | Cause and fix |+| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Infisical asks you to verify the username and password of the integration user | The username or password is wrong, or the user is locked out or inactive. Check the credentials with the command after this table. |+| Infisical says the instance URL redirected | The URL isn't the base URL of your instance, or the instance is hibernating. Wake the instance, then enter its base URL. |+| Infisical can't reach the instance | The instance URL is wrong, or the instance blocks traffic from Infisical. Allow [Infisical's IP addresses](/documentation/setup/networking) on the instance's IP access control list. |+| An access request shows **Not Submitted**, and its reason says the instance has no Infisical Approvals application endpoint | The Infisical application isn't installed or active on the instance. Install it, then select **Retry** on the request. |+| An access request shows **Not Submitted**, and its reason says the instance rejected the integration user's credentials | The integration user's password changed, or the user doesn't have the `x_infis_approvals.secret-manager-integration` role. Update the connection or the user, then select **Retry** on the request. |+| Infisical won't delete the connection | An access policy still uses the connection. Select another connection on the policy, or switch the policy back to Infisical approvals, then delete the connection. |-Change the password on the ServiceNow integration user, then update the **Password** field on the connection in Infisical. Requests already pending in ServiceNow are unaffected, since the decision callback authenticates with a separate Infisical machine identity rather than this connection.+A web service user can't sign in to the ServiceNow UI, so check its credentials from the command line instead:-## Troubleshooting+```bash+curl -u '<username>:<password>' https://<instance>.service-now.com/api/now/ui/user/current_user+```-| Symptom | Cause |-| --- | --- |-| Infisical cannot verify the username and password | Wrong username or password, or the user is locked out or inactive. Verify the credential by signing in with the ServiceNow REST API Explorer. |-| Infisical cannot reach the instance | The instance URL is wrong, or your instance blocks traffic from Infisical. Allow Infisical's egress IPs on your instance's IP access control list. |-| Access requests fail after the connection saves | The user is missing the `x_infis_approvals.secret-manager-integration` role, or the Infisical application is not installed on the instance. |+If the username and password work, ServiceNow returns a `200` response with the integration user's details.