diff --git a/task/rhacs-m2m-authenticate/0.1/README.md b/task/rhacs-m2m-authenticate/0.1/README.md new file mode 100644 index 00000000..381f1381 --- /dev/null +++ b/task/rhacs-m2m-authenticate/0.1/README.md @@ -0,0 +1,87 @@ +# Red Hat Advanced Cluster Security Machine to machine authentication Task + +Exchanges a service account token against a short-lived RHACS authorization +token to configure a pipeline run using `roxctl`. + +**Note: this Task requires a 4.4.2 roxctl image (task default) or a more recent +image version.** + +## Prerequisites + +This task requires an active installation of [Red Hat Advanced Cluster Security (RHACS)](https://www.redhat.com/en/resources/advanced-cluster-security-for-kubernetes-datasheet) +or [StackRox](https://www.stackrox.io). It also requires configuration of a +machine-to-machine integration. + + + +## Install the Task + +```bash +kubectl apply -f https://api.hub.tekton.dev/v1/resource/tekton/task/rhacs-m2m-authenticate/0.1/raw +``` + +## Parameters + +- **`rox_central_endpoint`**: The address:port tuple for StackRox Central. +Default: **central.stackrox.svc:443** +- **`insecure-skip-tls-verify`**: Skip verification the TLS certs of the Central +endpoint and registry. Examples: _"true", **"false"**_. +- **`rox_config_dir`**: Path to the roxctl config directory within the +`roxctl-config` workspace (if machine to machine authentication is used). The +path must be prefixed with `/roxctl-config`. +Examples: _"/roxctl-config", **""**_. +- `rox_image`: The image providing the roxctl tool (optional). +Default: quay.io/stackrox-io/roxctl:4.4.2 +(this is also the minimum version working with this task). +- `output_file`: path to a file where to redirect roxctl standard output. +Default: "" (redirects to stdout). +- `error_file`: path to a file where to redirect roxctl standard error. +Default: "" (redirects to stderr). + +## Workspaces + +- **roxctl-config**: A [Workspace](https://github.com/tektoncd/pipeline/blob/main/docs/workspaces.md) +in which to write the configuration for roxctl. + +## Usage + + +Check the [documentation](https://docs.openshift.com/acs/operating/manage-user-access/configure-short-lived-access.html#configure-short-lived-access_configure-short-lived-access) +to configure the trust with the OIDC token issuer. This +[example](samples/configure-m2m.md) describes a possible RHACS +machine-to-machine integration configuration. + +This task performs the token exchange itself. + +**Example task use:** + +The task configuration in that case must provide the `roxctl-config` workspace +and the `rox_config_dir` parameter with values pointing at the location where +the roxctl configuration will be written. + +```yaml + tasks: + - name: authenticate-to-rhacs + taskRef: + name: rhacs-m2m-authenticate + kind: Task + workspaces: + - name: roxctl-config + workspace: shared-workspace + params: + - name: rox_central_endpoint + value: central.stackrox.svc:443 + - name: rox_config_dir + value: /roxctl-config + runAfter: + - fetch-repository +``` + +**Samples:** + +* [pipeline.yaml](samples/pipeline.yaml) demonstrates use in a pipeline. +* [pipelinerun.yaml](samples/pipelinerun.yaml) demonstrates use in a pipelinerun. + +# Known Issues + +* Skipping TLS Verify is currently required. diff --git a/task/rhacs-m2m-authenticate/0.1/rhacs-m2m-authenticate.yaml b/task/rhacs-m2m-authenticate/0.1/rhacs-m2m-authenticate.yaml new file mode 100644 index 00000000..4e9c8a70 --- /dev/null +++ b/task/rhacs-m2m-authenticate/0.1/rhacs-m2m-authenticate.yaml @@ -0,0 +1,89 @@ +--- +apiVersion: tekton.dev/v1 +kind: Task +metadata: + name: rhacs-m2m-exchange + labels: + apps.kubernetes.io/version: "0.1" + annotations: + tekton.dev/tags: security + tekton.dev/categories: Security + tekton.dev/displayName: "Exchange a service account token for a Red Hat Advanced Cluster Security short-lived token" + tekton.dev/platforms: "linux/amd64,linux/arm64,linux/ppc64le,linux/s390x,darwin/amd64,darwin/arm64,windows/amd64" + tekton.dev/pipelines.minVersion: "0.50.0" +spec: + description: >- + Exchanges a kubernetes service account token against a Red Hat Advanced Cluster Security short-lived token. + workspaces: + - name: roxctl-config + description: | + A workspace containing the configuration for roxctl. + The task will update the access config for the target central with a short-lived token obtained from the remote central. + mountPath: /roxctl-config + params: + - name: rox_image + description: Image providing the roxctl tool. + default: 'quay.io/stackrox-io/roxctl:4.4.2' + - name: rox_central_endpoint + description: The address:port tuple for RHACS Stackrox Central. + type: string + default: central.stackrox.svc:443 + - name: insecure-skip-tls-verify + description: | + Do not verify TLS certificates. + + When set to "true", skip verifying the TLS certs of the Central endpoint. + type: string + default: "false" + - name: rox_config_dir + type: string + description: | + Path to the roxtl config directory within the roxctl-config workspace. + The path must be prefixed with "/roxctl-config". + default: "" + - name: output_file + type: string + description: | + Path to a file where to write the roxctl standard output stream. + If empty, the output stream goes to the container standard output. + default: "" + - name: error_file + type: string + description: | + Path to a file where to write the roxctl standard error stream. + If empty, the error stream goes to the container standard error. + default: "" + stepTemplate: + env: + - name: INSECURE + value: $(params.insecure-skip-tls-verify) + - name: ROX_ENDPOINT + value: $(params.rox_central_endpoint) + - name: ROX_CONFIG_DIR + value: $(params.rox_config_dir) + - name: ROX_EXECUTION_ENV + value: Tekton + - name: ROX_OUTPUT_FILE + value: $(params.output_file) + - name: ROX_ERROR_FILE + value: $(params.error_file) + steps: + - name: exchange-service-account-token + image: $(params.rox_image) + volumeMounts: + - name: token-vol + mountPath: /service-account-token + args: + - central + - m2m + - exchange + - --insecure-skip-tls-verify=$(INSECURE) + - --token-file=/service-account-token/token + volumes: + - name: token-vol + projected: + sources: + - serviceAccountToken: + audience: rhacs + path: token + expirationSeconds: 3600 diff --git a/task/rhacs-m2m-authenticate/0.1/samples/configure-m2m.md b/task/rhacs-m2m-authenticate/0.1/samples/configure-m2m.md new file mode 100644 index 00000000..c4154b45 --- /dev/null +++ b/task/rhacs-m2m-authenticate/0.1/samples/configure-m2m.md @@ -0,0 +1,47 @@ +## Configure RHACS Central to trust the OIDC ID tokens + +The first step is to configure RHACS to trust tokens issued by the OIDC provider +and mapping claims to specific roles within Central. + +Here is a sample configuration for a GCP cluster: + +``` +curl -u "admin:" https:///v1/auth/m2m -d @- << EOF +{ + "config": { + "type": "GENERIC", + "tokenExpirationDuration": "5m", + "mappings": [ + { + "key": "sub", + "valueExpression": "system:serviceaccount:default:build-bot", + "role": "Continuous integration" + } + ] + "issuer": "https://storage.googleapis.com/rhacs-tekton-task-demo-oidc" + } +} +EOF +``` + +In the above example, the `build-bot` service account in the `default` namespace +of the `rhacs-tekton-task-demo` cluster is granted the `Continuous Integration` +role. The tokens issued by Central for this service account are valid for 5 +minutes. + +Looking in deeper details at the fields of this configuration: +- `"type": "GENERIC"` : The configuration type is for a generic OIDC provider. +- `"issuer": "https://storage.googleapis.com/rhacs-tekton-task-demo-oidc"` : The +configuration will issue short lived tokens for OIDC tokens issued by +"https://storage.googleapis.com/rhacs-tekton-task-demo-oidc". +- `"tokenExpirationDuration": "5m"` : The issued tokens will be valid for a +duration of 5 minutes. +- each entry in the `"mappings"` section is a matching rule applied to the +presented OIDC token, mapping token claim key-value pairs with RHACS roles. +Here, when the ID token received by Central has +`system:serviceaccount:default:build-bot` as subject, the issued token will have +the `Continuous Integration` role. + +The `mappings` section can do more advanced JWT token field to RHACS role +mapping. See the [documentation](https://docs.openshift.com/acs/4.4/operating/manage-user-access/configure-short-lived-access.html#configure-short-lived-access_configure-short-lived-access) +for more details. diff --git a/task/rhacs-m2m-authenticate/0.1/samples/pipeline.yaml b/task/rhacs-m2m-authenticate/0.1/samples/pipeline.yaml new file mode 100644 index 00000000..60c996fd --- /dev/null +++ b/task/rhacs-m2m-authenticate/0.1/samples/pipeline.yaml @@ -0,0 +1,150 @@ +--- +apiVersion: tekton.dev/v1beta1 +kind: Pipeline +metadata: + name: rox-pipeline +spec: + + workspaces: + - name: shared-workspace + + params: + - name: deployment-name + type: string + description: name of the deployment resource to be patched + - name: deployment + type: string + description: filename of the deployment to be patched + - name: git-url + type: string + description: url of the git repo for the code of deployment + - name: git-revision + type: string + description: revision to be used from repo of the code for deployment + default: main + - name: IMAGE + type: string + description: image to be build from the code + - name: rox_central_endoint + type: string + description: The address:port tuple for RHACS Stackrox Central. + default: central.stackrox.svc:443 + - name: rox_config_dir + type: string + description: The path to the roxctl configuration directory + default: /roxctl-config + - name: rox_image + type: string + description: The Red Hat Advanced Cluster Security container image + default: quay.io/stackrox-io/roxctl:4.4.2 + + tasks: + - name: rhacs-authenticate + taskRef: + name: rhacs-m2m-exchange + kind: Task + params: + - name: insecure-skip-tls-verify + value: "true" + - name: rox_config_dir + value: $(params.rox_config_dir) + workspaces: + - name: roxctl-config + workspace: shared-workspace + + # checkout source code + - name: fetch-repository + taskRef: + name: git-clone + kind: ClusterTask + workspaces: + - name: output + workspace: shared-workspace + params: + - name: url + value: $(params.git-url) + - name: subdirectory + value: "" + - name: deleteExisting + value: "true" + - name: revision + value: $(params.git-revision) + runAfter: + - rhacs-authenticate + + # validate deployment against defined RHACS policies + - name: police-deployment + taskRef: + name: rhacs-deployment-check + kind: Task + workspaces: + - name: source + workspace: shared-workspace + - name: roxctl-config + workspace: shared-workspace + params: + - name: deployment + value: $(params.deployment) + - name: insecure-skip-tls-verify + value: "true" + - name: rox_config_dir + value: $(params.rox_config_dir) + - name: rox_image + value: $(params.rox_image) + runAfter: + - fetch-repository + + - name: build-image + taskRef: + name: buildah + kind: ClusterTask + params: + - name: IMAGE + value: $(params.IMAGE) + - name: TLSVERIFY + value: "false" + workspaces: + - name: source + workspace: shared-workspace + runAfter: + - fetch-repository + + # scan image for vulns using RHACS + - name: scan-image + taskRef: + name: rhacs-image-scan + kind: Task + workspaces: + - name: roxctl-config + workspace: shared-workspace + params: + - name: image + value: "$(params.IMAGE)@$(tasks.build-image.results.IMAGE_DIGEST)" + - name: insecure-skip-tls-verify + value: "true" # stackrox to OCP image registry x509 fail... + - name: rox_config_dir + value: $(params.rox_config_dir) + - name: rox_image + value: $(params.rox_image) + runAfter: + - build-image + + # validate image against RHACS policies + - name: police-image + taskRef: + name: rhacs-image-check + kind: Task + workspaces: + - name: roxctl-config + workspace: shared-workspace + params: + - name: image + value: "$(params.IMAGE)@$(tasks.build-image.results.IMAGE_DIGEST)" + - name: insecure-skip-tls-verify + value: "true" + - name: rox_config_dir + value: $(params.rox_config_dir) + - name: rox_image + value: $(params.rox_image) + runAfter: + - scan-image diff --git a/task/rhacs-m2m-authenticate/0.1/samples/pipelinerun.yaml b/task/rhacs-m2m-authenticate/0.1/samples/pipelinerun.yaml new file mode 100644 index 00000000..ccdfa5ff --- /dev/null +++ b/task/rhacs-m2m-authenticate/0.1/samples/pipelinerun.yaml @@ -0,0 +1,30 @@ +--- +apiVersion: tekton.dev/v1beta1 +kind: PipelineRun +metadata: + name: rox-pipelinerun +spec: + pipelineRef: + name: rox-pipeline + params: + - name: deployment-name + value: pipelines-vote-api + - name: deployment + value: k8s/deployment.yaml + - name: git-url + value: https://github.com/openshift/pipelines-vote-api.git + - name: git-revision + value: pipelines-1.7 + - name: IMAGE + value: image-registry.openshift-image-registry.svc:5000/$(context.pipelineRun.namespace)/pipelines-vote-ui + - name: insecure-skip-tls-verify + value: "true" + workspaces: + - name: shared-workspace + volumeClaimTemplate: + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 500Mi diff --git a/task/rhacs-m2m-authenticate/OWNERS b/task/rhacs-m2m-authenticate/OWNERS new file mode 100644 index 00000000..ce302a94 --- /dev/null +++ b/task/rhacs-m2m-authenticate/OWNERS @@ -0,0 +1,6 @@ +approvers: +- dhaus67 +- rhybrillou +reviewers: +- dhaus67 +- rhybrillou