Allow supplying your own webhook key

Until now the webhook key could only be generated by the server, which
does not play well with configuration as code: every time the resource
is re-applied the key changes and the repository webhook has to be
updated by hand.

The webhook_key field is now also writable (write only) on projects,
job templates and workflow job templates. When a key is supplied it is
kept as is, so the same secret can be stored in a vault and applied to
both the repository and the resource by automation. When the field is
left blank the previous behavior remains: a new key is generated
whenever the webhook service is set or changed, and blanking the key of
an active webhook generates a fresh one. Keys are never returned on the
resource itself, reading them still requires the webhook_key endpoint,
and copies of a resource always get their own key.

The key field in the UI is now an editable input with the same
semantics.

Author: fernandorocagonzalez

awx/api/serializers.py

@@ -1499,6 +1499,13 @@ class ProjectSerializer(UnifiedJobTemplateSerializer, ProjectOptionsSerializer):
     status = serializers.ChoiceField(choices=Project.PROJECT_STATUS_CHOICES, read_only=True)
     last_update_failed = serializers.BooleanField(read_only=True)
     last_updated = serializers.DateTimeField(read_only=True)
+    webhook_key = serializers.CharField(
+        write_only=True,
+        required=False,
+        allow_blank=True,
+        max_length=64,
+        help_text=_('Shared secret that the webhook service will use to sign requests. Leave blank to generate a new one when the webhook service is set.'),
+    )
     show_capabilities = ['start', 'schedule', 'edit', 'delete', 'copy']
     capabilities_prefetch = ['admin', 'update', {'copy': 'organization.project_admin'}]
 
@@ -1514,6 +1521,7 @@ class Meta:
             'default_environment',
             'signature_validation_credential',
             'webhook_service',
+            'webhook_key',
             'webhook_ref_filter',
         ) + (
             'last_update_failed',
@@ -1591,6 +1599,8 @@ def get_field_from_model_or_attrs(fd):
                     raise serializers.ValidationError({fd: _('Update options must be set to false for manual projects.')})
         if get_field_from_model_or_attrs('webhook_service') and not get_field_from_model_or_attrs('scm_type'):
             raise serializers.ValidationError({'webhook_service': _('Webhooks are not supported for manual projects.')})
+        if attrs.get('webhook_key') and not get_field_from_model_or_attrs('webhook_service'):
+            raise serializers.ValidationError({'webhook_key': _("Cannot set a webhook key without a webhook service.")})
         return super(ProjectSerializer, self).validate(attrs)
 
 
@@ -3295,6 +3305,9 @@ def validate(self, attrs):
         webhook_service = attrs.get('webhook_service', getattr(self.instance, 'webhook_service', None))
         webhook_credential = attrs.get('webhook_credential', getattr(self.instance, 'webhook_credential', None))
 
+        if attrs.get('webhook_key') and not webhook_service:
+            raise serializers.ValidationError({'webhook_key': _("Cannot set a webhook key without a webhook service.")})
+
         if webhook_credential:
             if webhook_credential.credential_type.kind != 'token':
                 raise serializers.ValidationError({'webhook_credential': _("Must be a Personal Access Token.")})
@@ -3314,6 +3327,13 @@ class JobTemplateSerializer(JobTemplateMixin, UnifiedJobTemplateSerializer, JobO
     capabilities_prefetch = ['admin', 'execute', {'copy': ['project.use', 'inventory.use']}]
 
     status = serializers.ChoiceField(choices=JobTemplate.JOB_TEMPLATE_STATUS_CHOICES, read_only=True, required=False)
+    webhook_key = serializers.CharField(
+        write_only=True,
+        required=False,
+        allow_blank=True,
+        max_length=64,
+        help_text=_('Shared secret that the webhook service will use to sign requests. Leave blank to generate a new one when the webhook service is set.'),
+    )
 
     class Meta:
         model = JobTemplate
@@ -3343,6 +3363,7 @@ class Meta:
             'job_slice_count',
             'webhook_service',
             'webhook_credential',
+            'webhook_key',
             'prevent_instance_group_fallback',
         )
         read_only_fields = ('*',)
@@ -3797,6 +3818,13 @@ class WorkflowJobTemplateSerializer(JobTemplateMixin, LabelsListMixin, UnifiedJo
 
     skip_tags = serializers.CharField(allow_blank=True, allow_null=True, required=False, default=None)
     job_tags = serializers.CharField(allow_blank=True, allow_null=True, required=False, default=None)
+    webhook_key = serializers.CharField(
+        write_only=True,
+        required=False,
+        allow_blank=True,
+        max_length=64,
+        help_text=_('Shared secret that the webhook service will use to sign requests. Leave blank to generate a new one when the webhook service is set.'),
+    )
 
     class Meta:
         model = WorkflowJobTemplate
@@ -3815,6 +3843,7 @@ class Meta:
             'ask_limit_on_launch',
             'webhook_service',
             'webhook_credential',
+            'webhook_key',
             '-execution_environment',
             'ask_labels_on_launch',
             'ask_skip_tags_on_launch',

awx/api/templates/api/webhook_key_view.md

@@ -10,3 +10,6 @@ by webhook events.  The response will include the following fields:
 
 Make an empty POST request to this resource to generate a new
 replacement `webhook_key`.
+
+A specific key can also be set by writing to the `webhook_key` field
+of the job template, workflow job template or project resource itself.

awx/main/models/jobs.py

@@ -235,7 +235,7 @@ class JobTemplate(UnifiedJobTemplate, JobOptions, SurveyJobTemplateMixin, Resour
     """
 
     FIELDS_TO_PRESERVE_AT_COPY = ['labels', 'instance_groups', 'credentials', 'survey_spec', 'prevent_instance_group_fallback']
-    FIELDS_TO_DISCARD_AT_COPY = ['vault_credential', 'credential']
+    FIELDS_TO_DISCARD_AT_COPY = ['vault_credential', 'credential', 'webhook_key']
     SOFT_UNIQUE_TOGETHER = [('polymorphic_ctype', 'name', 'organization')]
 
     class Meta:

awx/main/models/mixins.py

@@ -570,14 +570,26 @@ def rotate_webhook_key(self):
     def save(self, *args, **kwargs):
         update_fields = kwargs.get('update_fields')
 
-        if not self.pk or self._values_have_edits({'webhook_service': self.webhook_service}):
-            if self.webhook_service:
-                self.rotate_webhook_key()
-            else:
+        if self.pk:
+            service_edited = self._values_have_edits({'webhook_service': self.webhook_service})
+            key_edited = self._values_have_edits({'webhook_key': self.webhook_key})
+        else:
+            service_edited = True
+            key_edited = bool(self.webhook_key)
+
+        if service_edited:
+            if not self.webhook_service:
                 self.webhook_key = ''
+            elif not (key_edited and self.webhook_key):
+                # No key was supplied by the caller, generate one. A caller
+                # provided key (e.g. one managed as configuration) is kept as is.
+                self.rotate_webhook_key()
 
-            if update_fields and 'webhook_service' in update_fields:
+            if update_fields and 'webhook_service' in update_fields and 'webhook_key' not in update_fields:
                 update_fields.add('webhook_key')
+        elif key_edited and self.webhook_service and not self.webhook_key:
+            # Blanking the key of an active webhook means please generate a new one.
+            self.rotate_webhook_key()
 
         super().save(*args, **kwargs)
 

awx/main/models/projects.py

@@ -255,7 +255,7 @@ class Project(UnifiedJobTemplate, ProjectOptions, ResourceMixin, RelatedJobsMixi
 
     SOFT_UNIQUE_TOGETHER = [('polymorphic_ctype', 'name', 'organization')]
     FIELDS_TO_PRESERVE_AT_COPY = ['labels', 'instance_groups', 'credentials']
-    FIELDS_TO_DISCARD_AT_COPY = ['local_path']
+    FIELDS_TO_DISCARD_AT_COPY = ['local_path', 'webhook_key']
     FIELDS_TRIGGER_UPDATE = frozenset(['scm_url', 'scm_branch', 'scm_type', 'scm_refspec'])
 
     class Meta:

awx/main/models/workflow.py

@@ -544,6 +544,7 @@ class WorkflowJobTemplate(UnifiedJobTemplate, WorkflowJobOptions, SurveyJobTempl
         'job_tags',
         'execution_environment',
     ]
+    FIELDS_TO_DISCARD_AT_COPY = ['webhook_key']
 
     class Meta:
         app_label = 'main'

awx/main/tests/functional/api/test_webhooks.py

@@ -350,6 +350,98 @@ def test_set_webhook_service_manual_project(manual_project, patch, admin):
     assert response.data == {'webhook_service': ["Webhooks are not supported for manual projects."]}
 
 
+@pytest.mark.django_db
+@pytest.mark.parametrize(
+    "model_kwarg, url_name",
+    [
+        ('projects', 'api:project_detail'),
+        ('job_templates', 'api:job_template_detail'),
+        ('workflow_job_templates', 'api:workflow_job_template_detail'),
+    ],
+)
+def test_set_custom_webhook_key(organization_factory, job_template_factory, workflow_job_template_factory, project, patch, get, admin, model_kwarg, url_name):
+    objs = organization_factory("org")
+    if model_kwarg == 'projects':
+        obj = project
+    elif model_kwarg == 'job_templates':
+        obj = job_template_factory("jt", organization=objs.organization, inventory='test_inv', project='test_proj').job_template
+    else:
+        obj = workflow_job_template_factory("wfjt", organization=objs.organization).workflow_job_template
+
+    url = reverse(url_name, kwargs={'pk': obj.pk})
+    response = patch(url, {'webhook_service': 'github', 'webhook_key': 'secret-managed-as-config'}, user=admin, expect=200)
+    obj.refresh_from_db()
+
+    assert obj.webhook_service == 'github'
+    assert obj.webhook_key == 'secret-managed-as-config'
+    # the key is write only, it can only be read back through the webhook_key endpoint
+    assert 'webhook_key' not in response.data
+
+    key_url = reverse('api:webhook_key', kwargs={'model_kwarg': model_kwarg, 'pk': obj.pk})
+    response = get(key_url, user=admin, expect=200)
+    assert response.data == {'webhook_key': 'secret-managed-as-config'}
+
+
+@pytest.mark.django_db
+def test_change_webhook_key_keeps_service(github_project, patch, admin):
+    old_key = github_project.webhook_key
+
+    url = reverse('api:project_detail', kwargs={'pk': github_project.pk})
+    patch(url, {'webhook_key': 'new-secret'}, user=admin, expect=200)
+    github_project.refresh_from_db()
+
+    assert github_project.webhook_service == 'github'
+    assert github_project.webhook_key == 'new-secret'
+    assert github_project.webhook_key != old_key
+
+
+@pytest.mark.django_db
+def test_blank_webhook_key_generates_new_one(github_project, patch, admin):
+    old_key = github_project.webhook_key
+
+    url = reverse('api:project_detail', kwargs={'pk': github_project.pk})
+    patch(url, {'webhook_key': ''}, user=admin, expect=200)
+    github_project.refresh_from_db()
+
+    assert github_project.webhook_key != ''
+    assert github_project.webhook_key != old_key
+
+
+@pytest.mark.django_db
+def test_webhook_service_change_rotates_key_unless_key_given(github_project, patch, admin):
+    old_key = github_project.webhook_key
+
+    url = reverse('api:project_detail', kwargs={'pk': github_project.pk})
+    patch(url, {'webhook_service': 'gitlab'}, user=admin, expect=200)
+    github_project.refresh_from_db()
+    assert github_project.webhook_key not in ('', old_key)
+
+    patch(url, {'webhook_service': 'github', 'webhook_key': 'pinned-secret'}, user=admin, expect=200)
+    github_project.refresh_from_db()
+    assert (github_project.webhook_service, github_project.webhook_key) == ('github', 'pinned-secret')
+
+
+@pytest.mark.django_db
+def test_webhook_key_requires_service(project, patch, admin):
+    url = reverse('api:project_detail', kwargs={'pk': project.pk})
+    response = patch(url, {'webhook_key': 'orphan-secret'}, user=admin, expect=400)
+
+    assert response.data == {'webhook_key': ["Cannot set a webhook key without a webhook service."]}
+
+
+@pytest.mark.django_db
+def test_copied_project_gets_its_own_webhook_key(github_project, post, admin):
+    url = reverse('api:project_copy', kwargs={'pk': github_project.pk})
+    response = post(url, {'name': 'copied-project'}, user=admin, expect=201)
+
+    from awx.main.models.projects import Project
+
+    copied = Project.objects.get(pk=response.data['id'])
+    assert copied.webhook_service == 'github'
+    assert copied.webhook_key != ''
+    assert copied.webhook_key != github_project.webhook_key
+
+
 @pytest.mark.django_db
 def test_github_push_triggers_project_update(github_project, post):
     with mock.patch.object(ProjectUpdate, 'signal_start') as signal_start:

awx/ui/src/screens/Project/ProjectAdd/ProjectAdd.js

@@ -33,6 +33,9 @@ function ProjectAdd() {
       values.signature_validation_credential =
         values.signature_validation_credential.id;
     }
+    if (webhook_key) {
+      values.webhook_key = webhook_key;
+    }
     setFormSubmitError(null);
     try {
       const {

awx/ui/src/screens/Project/ProjectEdit/ProjectEdit.js

@@ -34,6 +34,9 @@ function ProjectEdit({ project }) {
         values.signature_validation_credential.id;
     }
 
+    if (webhook_key) {
+      values.webhook_key = webhook_key;
+    }
     try {
       const {
         data: { id },

awx/ui/src/screens/Project/shared/Project.helptext.js

@@ -144,7 +144,9 @@ job will not run.`,
                 trigger a project sync.`,
   webhookKey: t`Secret shared with the webhook service. The service uses
                 it to sign its requests, so only your repository can
-                trigger a project sync.`,
+                trigger a project sync. Type your own secret to manage it
+                as configuration, or leave the field blank to have one
+                generated on save.`,
 });
 
 export default getProjectHelpText;