diff --git a/.ansible-sign/sha256sum.txt b/.ansible-sign/sha256sum.txt index 573f193..b29d520 100644 --- a/.ansible-sign/sha256sum.txt +++ b/.ansible-sign/sha256sum.txt @@ -95,7 +95,7 @@ b64a9ce7ade9b8fae7bda827f7a8d179809a8df065c8bafc1af07ae827ffb2aa SNOWSetup/imag 3b6b1d02322d2b0435b86bec366c94c6fe928ab84f0d2b881cf102021c44dddc SNOWSetup/images/workflow_start.jpg cb3a760e0f134314711929e87e54b3a46d3d4898f0baa2d641000ee1e3b63708 SNOWSetup/images/write_scope.png b8bc0e6865c91d1d8cedf5bc9faa24782629806c15f99d0b24e3397ec294dcbb SNOWSetup/images/write_scope_deets.png -d8a460f1afb64f9a13ad5d5216f632551f60b24b0207e58474a1144bfde8d91b SNOWSetup/readme.md +f3c52e657192d729a118b414ce3e1e82f0b78586a28f511e4469d0d469435b9f SNOWSetup/readme.md 8d64a90e1cf927f9adf8074d405a62ec50f4df417865706d1f4bc5ff5bdfeaa5 ServiceNowCR_and_approve.yml db0cf6bab374ea48077c3898aea1602a570541a49ed82797b7459c9ce9a9824c ServiceNowCR_canceled.yml 675d62c62ed528e495f8144290d181875521766c5cebb9661fc15552f1db1083 ServiceNowCR_closed.yml diff --git a/.ansible-sign/sha256sum.txt.sig b/.ansible-sign/sha256sum.txt.sig index ab1879b..d3f1f9d 100644 --- a/.ansible-sign/sha256sum.txt.sig +++ b/.ansible-sign/sha256sum.txt.sig @@ -1,14 +1,14 @@ -----BEGIN PGP SIGNATURE----- -iQGzBAABCAAdFiEE/bJvyFHKKJdaZDOLTiIiIXrUDNEFAmbsQR4ACgkQTiIiIXrU -DNHQ6AwAlbI5mAgZXSIsZUd8fOLdJZx60Gx7wYQZ9f1lni2gUsEkyB5YZbXZi1e/ -1jwHfJH0kRl2CjIdSaBqG/+tJL3r1HTjAX0oI35p+EeXJynUtTCxvH/abMK3BIAR -P1xI3YDMpji2rJmfU1PxsEd5YAWmpAaR9B9T8yYsYOyHdU7osUb6RGGTQQL6rKn6 -r+Ai6E8ycCJe8lT6XBXvslrsx/w/CBWa9SmC2vZ46ux5mjgjKgFR6wuFrChCizTm -6NOPEiKMBJOo+7nJnPXHE87CTeemK+cp0heb56pWtdGcAgHGi856+SJMDMB7lVMM -nTK7tIT3oWVf8asLXvT8lGJO1EgugM/cwLXefdqJG5WW852qb/tXYxgxkeJTwZTS -+wzk07JBcgUi6VKSyp8bND5Vv1B2g2op5eDHB8uoMwqyOk7YNba3t34yefpSwr5X -CaQqtPDeOn1LjssVC+RAgI6LUykUsGlIKGYrJHc8IZ4smXiFppQP0mwUk7u1IcA9 -K5WZUoyL -=Ic6E +iQGzBAABCAAdFiEE/bJvyFHKKJdaZDOLTiIiIXrUDNEFAmco2EgACgkQTiIiIXrU +DNHgXwv/aJ81elwV3X3/z6Sri9C/MQ+ajxJqIW8AIvQDvLnl2/iL88liNkKcjL/N +WS/HYFqg4FlqH3F6zoym8igCXoBvTvFi8STSeSWL9LtLcVBqt4FB755XzEbdIaKM +xN6r4DkVcOZ1zV8CCSPk3afjoGYvT6jH6RGK4Pqz03eexR9FfeiIDlEvWQV/fHJN +0Cvt+ozB7NebspyHtrxEqqkjLl00TZiF0CsV1iy7sDkZ/WERi3H/dEMWQGx+md3f +697XUZdp23rdniYBB6ZUY9NR85IRv25TalS4hQDCyTjV3+cC6wq92XPd3fY8KdzI +A+5zl4HkhTSH/mZMWTxvwSso+JdWBABhd1UqeQd+jH7v6aAOtvep/sCnvXVraVSd +qYHhSCSyZROcJQMzhqn56jJBqF/9jAP6ibBYS6vy4J9kWNw1RMMG6IP50mEst+dK +0AFCN3t62gooh8xsu9W2vzUMxIioAJb9ett6tzEJjqi5qDtFWXgAoRaPQ3Sf94Ny +1iuRU1Md +=/MtQ -----END PGP SIGNATURE----- diff --git a/SNOWSetup/readme.md b/SNOWSetup/readme.md index ef321d6..fdd8655 100644 --- a/SNOWSetup/readme.md +++ b/SNOWSetup/readme.md @@ -35,7 +35,7 @@ ### Preparing AAP #### 1) -In AAP, navigate to **Applications** on the left side of the screen. Click the **Blue Add Button** on the right, which will present you with a Create Application dialog screen. Fill in the following fields: +In AAP 2.4 and older, navigate to **Applications** on the left side of the screen and then click the **Blue Add Button** on the right, which will present you with a Create Application dialog screen. In AAP 2.5 and newer, navigate to **Access Management -> OAuth Applications** on the left side of the screen and then click the **Blue Create OAuth application Button** on the top, which will present you with a Create Application dialog screen. Fill in the following fields: | Parameter | Value | |-----|-----| | Name | Descriptive name of the application that will contact AAP | @@ -47,12 +47,14 @@ In AAP, navigate to **Applications** on the left side of the screen. Click the * AAP Create Application #### 2) -Click the blue **Save** button, at which point a window will pop up, presenting you with the Client ID and Client Secret needed for ServiceNow to make API calls into AAP. This will only be presented **ONCE**, so capture these values for later use. +Click the blue **Save** button in AAP 2.4 and older or the blue **Create OAuth application** in AAP 2.5 and newer, at which point a window will pop up, presenting you with the Client ID and Client Secret needed for ServiceNow to make API calls into AAP. This will only be presented **ONCE**, so capture these values for later use. AAP Application Secrets #### 3) -Next, navigate to **Settings** on the left side of the screen and then **Miscellaneous Authentication settings**. After you click Edit at the bottom, you’ll want to toggle the **Allow External Users to Create Oauth2 Tokens** option to ***on***. Click the blue **Save** button to commit the change. +Next, in AAP 2.4 or older navigate to **Settings** on the left side of the screen and then **Miscellaneous Authentication settings**. After you click Edit at the bottom, you’ll want to toggle the **Allow External Users to Create Oauth2 Tokens** option to ***on***. Click the blue **Save** button to commit the change. + +In AAP 2.5 or newer navigate to **Settings -> Platform gateway** on the left side of the screen. After you click Edit platform gateway settings at the top right, you’ll want to set enabled for the **Allow External Users to Create Oauth2 Tokens** option. Click the blue **Save platform gateway settings** button to commit the change. ## Note - This is only needed if using a non-local user within automation controller for the integration. @@ -91,16 +93,16 @@ On the new application screen, fill in these details: SNOW Application Registry Details -| Parameter | Value | -|-----|-----| -| Name | Descriptive Application Name | -| Client ID | The Client ID you got from AAP | -| Client Secret | The Client Secret you got from AAP | -| Default Grant Type | `Authorization Code` | -| Authorization URL | `https:///api/o/authorize/` | -| Token URL | `https:///api/o/token/` | -| Redirect URL | `https://.service-now.com/oauth_redirect.do` | -| Send Credentials | `As Basic Authorization Header` | +| Parameter | 2.4 and older Value | 2.5 and newer Value | +|-----|-----|-----| +| Name | Descriptive Application Name | Descriptive Application Name | +| Client ID | The Client ID you got from AAP | The Client ID you got from AAP | +| Client Secret | The Client Secret you got from AAP | The Client Secret you got from AAP | +| Default Grant Type | `Authorization Code` | `Authorization Code` | +| Authorization URL | `https:///api/o/authorize/` | `https:///o/authorize/` | +| Token URL | `https:///api/o/token/` | `https:///o/token/` | +| Redirect URL | `https://.service-now.com/oauth_redirect.do` | `https://.service-now.com/oauth_redirect.do` | +| Send Credentials | `As Basic Authorization Header` | `As Basic Authorization Header` | Click the **Submit** button at the bottom. @@ -129,12 +131,12 @@ Navigate to **System Web Services-->Outbound-->REST Messages**. Click the blue * REST Message -| Parameter | Value | -|-----|-----| -| Name | `Provision Cloud Webservers with Users` | -| Endpoint | The url endpoint of the AAP action you wish to do. This can be taken from the browsable API at `https:///api` | -| Authentication Type | `Oauth 2.0` | -| Oauth Profile | Select the Oauth profile you created | +| Parameter | 2.4 and older Value | 2.5 and newer Value | +|-----|-----|-----| +| Name | `Provision Cloud Webservers with Users` |`Provision Cloud Webservers with Users` | +| Endpoint | The url endpoint of the AAP action you wish to do. This can be taken from the browsable API at `https:///api/v2/` | The url endpoint of the AAP action you wish to do. This can be taken from the browsable API at `https:///api/controller/v2/` | +| Authentication Type | `Oauth 2.0` | `Oauth 2.0` | +| Oauth Profile | Select the Oauth profile you created | Select the Oauth profile you created | Right-click inside the grey area at the top; click **Save**. @@ -154,7 +156,7 @@ Under the HTTP Methods section at the bottom, click the blue New button. At the - **HTTP Method**: `POST` - **Name**: Descriptive HTTP Method Name -- **Endpoint**: The url endpoint of the AAP action you wish to do. This can be taken from the browsable API at `https:///api` +- **Endpoint**: The url endpoint of the AAP action you wish to do. This can be taken from the browsable AAP 2.4 and older API at `https:///api/v2/` or `https:///api/controller/v2/` in AAP 2.5 and newer for example `https:///api/controller/v2/job_templates/41/launch` - **HTTP Headers**: ***(under the HTTP Request tab)*** - The only HTTP Header that should be required is `Content-Type: application/json` - **HTTP Query Parameters**: ***(under the HTTP Request tab)*** @@ -308,7 +310,7 @@ This walkthrough assumes you have an Integration Hub Standard/Professional subsc ### Preparing AAP #### 1) -In AAP, navigate to **Applications** on the left side of the screen. Click the **Blue Add Button** on the right, which will present you with a Create Application dialog screen. Fill in the following fields: +In AAP 2.4 and older, navigate to **Applications** on the left side of the screen. Click the **Blue Add Button** on the right, which will present you with a Create Application dialog screen. Fill in the following fields: | Parameter | Value | |-----|-----| | Name | Descriptive name of the application that will contact AAP | @@ -319,6 +321,15 @@ In AAP, navigate to **Applications** on the left side of the screen. Click the * AAP Create Application +In AAP 2.5 and newer, navigate to **Access Management -> OAuth Applications** on the left side of the screen and then click the **Blue Create OAuth application Button** on the top, which will present you with a Create Application dialog screen. Fill in the following fields: +| Parameter | Value | +|-----|-----| +| Name | Descriptive name of the application that will contact AAP | +| Organization | `Default` | +| Authorization Grant Type | `Authorization code` | +| Redirect URIs | `https://.service-now.com/oauth_redirect.do` | +| Client Type | `Confidential` | + #### 2) Click the blue **Save** button, at which point a window will pop up, presenting you with the Client ID and Client Secret needed for ServiceNow to make API calls into AAP. This will only be presented **ONCE**, so capture these values for later use. @@ -374,28 +385,38 @@ Navigate to **Connections & Credentials-->Connection & Credential Aliases**. Cli #### 7) Under Related Links select "Create New Connection & Credential" and enter in the following information: -| Parameter | Value | -|-----|-----| -| Connection Name | ` Spoke Connection` | -| Connection URL | `https://` | -| Credential Name | ` Spoke Credentials` | -| Application Registry Name | `` | -| OAuth Client ID | The Client ID you got from AAP | -| OAuth Client Secret | The Client Secret you got from AAP | -| OAuth Entity Profile Name | Ansible Entity Profile | -| OAuth Entity Scope | `write` | -| Authorization URL | `https:///api/o/authorize/` | -| Token URL | `https:///api/o/token/` | -| OAuth Redirect URL | `https://.service-now.com/api/sn_ansible_spoke/ansible_oauth_redirect` | +| Parameter | 2.4 and older Value | 2.5 and newer Value | +|-----|-----|-----| +| Connection Name | ` Spoke Connection` | ` Spoke Connection` | +| Connection URL | `https://` | `https://` | +| Credential Name | ` Spoke Credentials` |` Spoke Credentials` | +| Application Registry Name | `` | `` | +| OAuth Client ID | The Client ID you got from AAP | The Client ID you got from AAP | +| OAuth Client Secret | The Client Secret you got from AAP | The Client Secret you got from AAP | +| OAuth Entity Profile Name | Ansible Entity Profile | Ansible Entity Profile | +| OAuth Entity Scope | `write` | `write` | +| Authorization URL | `https:///api/o/authorize/` | `https:///o/authorize/` | +| Token URL | `https:///api/o/token/` | `https:///o/token/` | +| OAuth Redirect URL | `https://.service-now.com/api/sn_ansible_spoke/ansible_oauth_redirect` | `https://.service-now.com/oauth_redirect.do` | Connection & Credential Select **Create and Get OAuth Token** to complete the Ansible spoke set up. This will generate a window asking to authorize ServiceNow against your AAP instance/cluster. Click **Authorize**. +## NOTE In AAP 2.5 this will fail with an HTTP Error 401 - Unauthorized Error because of an API Scipt auto applied by ServiceNow. To fix this: + +1) Go to **System OAuth-->Application Registry**. Select the Application Registry you just created. Delete the OAuth API Script field. Click **Update** at the top. + +2) Navigate to **All > Connections & Credentials > Credentials**. Select your newly created credential. Under Related Links select **Get Oauth Token**. This will generate a window asking to authorize ServiceNow against your AAP instance/cluster. Click **Authorize**. This should now successfully generate a token + +3) You will also need to adjust the API endpoint for AAP 2.5 for Jobs to launch properly. Navigate to **All > Connections & Credentials > Connections** and select your newly created connection. In the Attributes section, Version change **v2** to be **controller/v2** and click Update. + Note: The ServiceNow user MUST be able to access the ServiceNow API (check if the user you are logged into ServiceNow with has API access) Note: If you wish to have AAP use a specific user when reaching out from ServiceNow (such as a dedicated servicenow user) ensure you are logged in as that user when you click Authorize. You can utilize a System Administrator or a Normal User as this user. If you are using a Normal User, ensure they have execute access on any Job Templates or Workflow Job Templates you intend to run. **Authorize**. +HTTP Error 401 - Unauthorized + ### Create a Catalog Item for Users #### 8) @@ -616,7 +637,7 @@ A more detailed rulebook example with an https webhook source and a token for so ``` #### 4) -After your rulebook has been pushed to Git, we will login to Event-Driven Ansible controller and go to Projects. Either sync an existing Project if you already have one or go to **+ Create Project** and provide a name and your SCM URL and click **Create Project**. Ensure the Project has succesfully synced. +On AAP 2.4 After your rulebook has been pushed to Git, we will login to Event-Driven Ansible controller and go to Projects. Either sync an existing Project if you already have one or go to **+ Create Project** and provide a name and your SCM URL and click **Create Project**. Ensure the Project has succesfully synced. Create a Rulebook Activation by going to **Rulebook Activations** and clicking **+ Create rulebook activation**. Give it a name, select your existing Project, the rulebook you previously created, and your Decision environment (the default Decision Environment will work). Click **Create rulebook activation**. @@ -624,11 +645,21 @@ On the new page, click **History** and ensure the rulebook is successfully runni Event-Driven Ansible Controller +On AAP 2.5 and newer, login to the Unified UI. Go to **Automation Decisions -> Projects**. Either sync an existing Project if you already have one or go to **+ Create Project** and provide a name and your SCM URL and click **Create Project**. Ensure the Project has succesfully synced. + +Now we will create a Credential for the Event Stream to use. Go to **Automation Decisions -> Infrastructure -> Credentials**. Select **Create credential**. Enter a name, select an organization and select **ServiceNow Event Stream** as the Credential Type. Then enter in a token (this can be a randomly generated token from something like Bitwarden). Click **Create credential at the bottom** + +Now we will create a Credential for the Automation Platform so Job and Workflow Templates can be launched. Go to **Automation Decisions -> Infrastructure -> Credentials**. Select **Create credential**. Enter a name, select an organization and select **Red Hat Ansible Automation Plaform** as the Credential Type. Enter in host `https:///api/controller/`, Username that exists in the platform and Password. Click **Create credential at the bottom** + +Now go to **Automation Decisions -> Event Streams**. Click **Create event stream** at the top. Enter in a name, select an Organization, select the event stream type of **ServiceNow Event Stream** select the Credential you created in the previous step. Then click **Create event stream** + +Now we will create the Rulebook Activation and attach it to the Event Stream. Go to **Automation Decisions -> Rulebook Activations** Select **Create rulebook activation**. Enter a name and Organization. Select the Project you previously created and then your ServiceNow rulebook. Select the Gear icon next to Event Streams which will open up a new dialog box. Select your Rulebook Source (which will be the header of your rulebook) and then your Event Stream (your previously created ServiceNow Event Stream) and click **Save**. Click the magnifying glass next to Credential and select the Red Hat Ansible Automation Platform credential you previously created. Select your Decision environment (the default Decision Environment will work). Click **Create rulebook activation**. + ### Back to ServiceNow #### 5) Now we will configure the Event-Driven Ansible Notification as the ServiceNow user we just assigned permissions. Navigate to the **All** menu and select **Event-Driven Ansible Notifications -> Properties**. In the Webhook Configurations section fill in a Webhook URL and a -Webhook authorization token if desired. The webhook URL should the FQDN of your Event-Driven Ansible Controller server plus the port your rulebook webhook will be listening on, for example **http://eda.shadowman.dev:5003/endpoint** +Webhook authorization token if desired. The webhook URL should the FQDN of your Event-Driven Ansible Controller server plus the port your rulebook webhook will be listening on, for example on AAP 2.4 **http://eda.shadowman.dev:5003/endpoint** with AAP2.5 you'll navigate to the Event Stream you created at **Automation Decisions -> Event Streams**, select it, and then copy the URL that appears. For example `https://:443/eda-event-streams/api/eda/v1/external_event_stream/574d0d17-f0b2-4bgf-93ad-g8186a03eede/post/`. If you are using a 443 endpoint you can remove the port, so for example `https:///eda-event-streams/api/eda/v1/external_event_stream/574d0d17-f0b2-4bgf-93ad-g8186a03eede/post/` No MID Server is needed if the Webhook URL is accessible directly from the running ServiceNow instance. Otherwise, fill in a proper MID Server name. Your Event-Driven Ansible Controller server listening to the webhook requests must be reachable by the MID Server. To validate the MID Server use the **All** menu and select **MID Servers -> Servers**. The selected MID Server must appear on the server list and its Status field must be Up and its Validated field must be Yes. @@ -644,7 +675,7 @@ Finally click the **OK** button to persist all the settings. These settings can #### 6) To test the configuration and see the output provided by ServiceNow, you can easily create a test Incident. For this test, navigate to the **All** menu and select **Event-Driven Ansible Notifications -> Properties**. Check **When Created** for the Incident table if you haven't already. Click **OK** to confirm the changes. Create a new Incident, navigate to the **All** menu and select **Incident -> Create New**. Fill in the incident information (at a minimum you need Caller and Short description) and click Submit. -Navigate to Event-Driven Ansible Controller and select **Rule Audit**. You should see a new Rule that has been triggered. Select the name. Go to **Events** and click on **ansible.eda.webhook** to see the full json payload that was received by EDA. This is what you can use to create the conditions for your rulebook in the future. You can now utilize the Event-Driven Ansible Notification Service. +Navigate to Event-Driven Ansible Controller and select **Rule Audit** on AAP 2.4 or **Automation Decisions -> Rule Audit** on AAP 2.5. You should see a new Rule that has been triggered. Select the name. Go to **Events** and click on **ansible.eda.webhook** to see the full json payload that was received by EDA. This is what you can use to create the conditions for your rulebook in the future. You can now utilize the Event-Driven Ansible Notification Service. Event-Driven Ansible Controller JSON