fix: Updates documentation for user-id to sys-id

Author: davidhessler

aws_security_incident_response_sample_integrations/aws_security_incident_response_service_now_integration_stack.py

@@ -93,12 +93,14 @@ def __init__(
             no_echo=True,
         )
 
-        # Store Service Now User ID parameter
+        # Store Service Now User sys_id parameter
+        # NOTE: Parameter name kept as "serviceNowUserId" for backwards compatibility.
+        # The CLI flag is --sys-id and the value must be the user's sys_id (32-char GUID), not the username.
         service_now_user_id_param = CfnParameter(
             self,
             "serviceNowUserId",
             type="String",
-            description="The ServiceNow user ID for JWT authentication.",
+            description="The ServiceNow user's sys_id for JWT authentication (not the username).",
         )
 
         # Private key bucket parameter (from deploy script)
@@ -142,7 +144,7 @@ def __init__(
             "serviceNowUserIdSSM",
             parameter_name="/SecurityIncidentResponse/serviceNowUserId",
             string_value=service_now_user_id_param.value_as_string,
-            description="Service Now user ID",
+            description="ServiceNow user sys_id for JWT authentication",
         )
         service_now_user_id_ssm.apply_removal_policy(RemovalPolicy.DESTROY)
 

deploy-integrations-solution.py

@@ -1,13 +1,14 @@
 #!/usr/bin/env python3
 """Deployment script for AWS Security Incident Response Sample Integrations.
 
-This script provides a command-line interface for deploying Jira and ServiceNow
+This script provides a command-line interface for deploying Jira, ServiceNow, and Slack
 integrations with AWS Security Incident Response. It handles CDK deployment
 with proper parameter passing for different integration types.
 
 Usage:
     ./deploy-integrations-solution.py jira --email user@example.com --url https://example.atlassian.net --token TOKEN --project-key PROJ
-    ./deploy-integrations-solution.py service-now --instance-id example --username admin --password PASSWORD --integration-module itsm
+    ./deploy-integrations-solution.py service-now --instance-id example --client-id CLIENT_ID --client-secret SECRET --sys-id USER_SYS_ID --private-key-path ./private.key --integration-module itsm
+    ./deploy-integrations-solution.py slack --bot-token xoxb-... --signing-secret SECRET --workspace-id WORKSPACE_ID
 """
 
 import argparse
@@ -156,7 +157,7 @@ def deploy_servicenow(args):
             "--parameters",
             f"AwsSecurityIncidentResponseServiceNowIntegrationStack:serviceNowClientSecret={args.client_secret}",
             "--parameters",
-            f"AwsSecurityIncidentResponseServiceNowIntegrationStack:serviceNowUserId={args.user_id}",
+            f"AwsSecurityIncidentResponseServiceNowIntegrationStack:serviceNowUserId={args.sys_id}",  # CDK parameter name kept as serviceNowUserId for backwards compatibility
             "--parameters",
             f"AwsSecurityIncidentResponseServiceNowIntegrationStack:privateKeyBucket={bucket_name}",
             "--parameters",
@@ -272,7 +273,7 @@ def main():
         "--client-secret", required=True, help="ServiceNow OAuth client secret"
     )
     servicenow_parser.add_argument(
-        "--user-id", required=True, help="ServiceNow user ID for JWT authentication"
+        "--sys-id", required=True, help="ServiceNow user's sys_id (32-character GUID) for JWT authentication"
     )
     servicenow_parser.add_argument(
         "--private-key-path", required=True, help="Local path to private key file (e.g., ./private.key)"
@@ -327,7 +328,7 @@ def main():
                 textwrap.dedent("""
                 Please specify 'jira', 'service-now', or 'slack' as the integration type.
                 Example: deploy-integrations-solution jira --email user@example.com --url https://example.atlassian.net --token YOUR_TOKEN --project-key PROJ
-                Example: deploy-integrations-solution service-now --instance-id example --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --user-id YOUR_USER_ID --private-key-path ./private.key --integration-module itsm
+                Example: deploy-integrations-solution service-now --instance-id example --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --sys-id YOUR_SYS_ID --private-key-path ./private.key --integration-module itsm
                 Example: deploy-integrations-solution slack --bot-token xoxb-... --signing-secret YOUR_SECRET --workspace-id YOUR_WORKSPACE_ID
             """)
             )

documentation/SERVICE_NOW/SERVICE_NOW.md

@@ -11,7 +11,7 @@ section in this document.
   --instance-id <your-servicenow-instance-id> \
   --client-id <your-oauth-client-id> \
   --client-secret <your-oauth-client-secret> \
-  --user-id <your-servicenow-user-id> \
+  --sys-id <your-servicenow-user-sys-id> \
   --private-key-path <path-to-private-key-file> \
   --integration-module <itsm|ir> \
   --log-level <info|error|debug>
@@ -24,7 +24,7 @@ Eg.
   --instance-id dev1234 \
   --client-id test-1234 \
   --client-secret "XXXXXXXXXXXXXXXXXXXX" \
-  --user-id abcd.1234 \
+  --sys-id a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 \
   --private-key-path private.key \
   --integration-module ir \
   --log-level info
@@ -85,6 +85,7 @@ JWT (JSON Web Token) OAuth authentication uses RSA key pairs to generate signed
       - First Name: `AWS`
       - Last Name: `Integration`
 4. If you have a user, search with user-id and open the record
+5. Note the user's `sys_id` — you will need this for deployment. The `sys_id` is a 32-character unique identifier (e.g., `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`). You can find it by right-clicking the header bar of the user record and selecting "Copy sys_id", or from the URL when viewing the user record.
 5. Assign the following roles under the `Roles` tab by clicking on `Edit`:
 
    **ITSM Mode (incident table):**
@@ -259,7 +260,7 @@ Bootstrap is a prerequisite to deployment. You cannot deploy the solution which
    - **Access Token Lifespan**: `3600`
    - **Clock skew**: `300`
    - **Token Format**: `Opaque`
-   - **User field**: `User Id`
+   - **User field**: `sys_id`
    - **Enable JTI verification**: ✅
    - **JTI Claim**: `jti`
    - **JWKS Cache Lifespan**: `720`
@@ -600,7 +601,7 @@ The stack provides the following outputs that can be used for integration:
      --instance-id <your-servicenow-instance-id> \
      --client-id <your-oauth-client-id> \
      --client-secret <your-oauth-client-secret> \
-     --user-id <your-servicenow-user-id> \
+     --sys-id <your-servicenow-user-sys-id> \
      --private-key-path <path-to-private-key-file> \
      --integration-module <itsm|ir> \
      --log-level info
@@ -609,7 +610,7 @@ The stack provides the following outputs that can be used for integration:
    **Required Parameters:**
    - `--client-id`: OAuth client ID from ServiceNow OAuth application
    - `--client-secret`: OAuth client secret from ServiceNow OAuth application  
-   - `--user-id`: ServiceNow user ID for JWT authentication
+   - `--sys-id`: ServiceNow user's `sys_id` for JWT authentication (not the username — see [Setup ServiceNow Integration User](#setup-servicenow-integration-user))
    - `--private-key-path`: Path to RSA private key file for JWT signing
    - `--integration-module`: Choose `itsm` for IT Service Management or `ir` for Incident Response module
    

documentation/SERVICE_NOW/SERVICE_NOW_TROUBLESHOOTING.md

@@ -26,7 +26,7 @@ This document provides detailed information on troubleshooting, validation, and
      --instance-id <your-servicenow-instance-id> \
      --client-id <your-oauth-client-id> \
      --client-secret <your-oauth-client-secret> \
-     --user-id <your-servicenow-user-id> \
+     --sys-id <your-servicenow-user-sys-id> \
      --private-key-path <path-to-private-key-file> \
      --integration-module <itsm|ir> \
      --log-level info
@@ -35,7 +35,7 @@ This document provides detailed information on troubleshooting, validation, and
    **Required Parameters:**
    - `--client-id`: OAuth client ID from ServiceNow OAuth application
    - `--client-secret`: OAuth client secret from ServiceNow OAuth application
-   - `--user-id`: ServiceNow user ID for JWT authentication
+   - `--sys-id`: ServiceNow user's `sys_id` (32-character GUID) for JWT authentication
    - `--private-key-path`: Path to RSA private key file for JWT signing
    - `--integration-module`: Choose `itsm` for IT Service Management or `ir` for Incident Response module