diff --git a/Readme.md b/Readme.md index cf035b1..a92bd4a 100644 --- a/Readme.md +++ b/Readme.md @@ -2,14 +2,15 @@ Welcome to the StackRox contributions repository. This repository stores a variety of configuration files, scripts, and samples related to the deployment and use of the [StackRox Kubernetes security platform](https://www.stackrox.io) and [Red Hat Advanced Cluster Security](https://www.redhat.com/en/technologies/cloud-computing/openshift/advanced-cluster-security-kubernetes). -All code in this repo is provided as-is without warranty or support from Red Hat. +All code in this repo is provided as-is without warranty or support from Red Hat. Join the #stackrox channel on [CNCF Slack](https://cncf.slack.com/) for community discussion and support. -We'd love your feedback! Please take care with any of the configurations in this repo before applying using these in your environment. +We'd love your feedback! Please take care with any of the configurations in this repo before applying using these in your environment. ## What's in this Repository -* `ci/` samples for using StackRox *roxctl* command-line tool in CI/CD pipelines +* `ci/` samples for using StackRox *roxctl* command-line tool in CI/CD pipelines * `ingress/` configurations for StackRox under popular Kubernetes ingress controllers * `completions/` shell auto-completions for roxctl * `util-scripts/` scripts using Stackrox API or roxctl for popular tasks (export to csv,...) +* `guides/` instructions on how to configure ACS or integrate it with 3rd party services diff --git a/guides/cloud-provider-integrations/azure-service-principal-m2m-auth.md b/guides/cloud-provider-integrations/azure-service-principal-m2m-auth.md new file mode 100644 index 0000000..7f64182 --- /dev/null +++ b/guides/cloud-provider-integrations/azure-service-principal-m2m-auth.md @@ -0,0 +1,74 @@ +## Using Azure Entra ID service principals for machine to machine auth with ACS + +**Note:** Instructions provided in this guide are provided as-is without warranty or support from Red Hat. + +### 1. Create Azure service principal + +For this, we can use [the following guide from Microsoft Learn](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal?source=recommendations#register-an-application-with-microsoft-entra-id-and-create-a-service-principal). + +The only step: “**Register an application with Microsoft Entra ID and create a service principal”** is required. We do not have to add roles for that service principal because it does not have to access any Azure resource. It will be used only for authentication in ACS. + +### 2. Setup authentication for created service principal + +This is required in order for the service principal to authenticate to Azure. + +We can use [the following steps from the same Microsoft Learn page](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal?source=recommendations#set-up-authentication). + +After authentication setup, we can use the `az` command to log into Azure and retrieve the access token required to do m2m authentication to ACS. + +### 3. Login with `az` + +This example uses a secret to authenticate (**Option 3** in the “Setup authentication” guide mentioned under step 2.). + +``` +az login --service-principal \ + --username \ + --password \ + --tenant \ + --allow-no-subscriptions +``` + +It is important to use the `--allow-no-subscriptions` flag if the service principal does not have any roles. + +**Note:** Logging as a regular user with `az login` would also work. In that case, the difference would be that we need to use `unique_name` or another claim from the token during the configuration of ACS machine access (Step 4\. below) + +After this, the command: + +``` +az account list --output yamlc +``` + +Should output account with `user` property. The name of that user should be the service principal ID. + +``` + user: + name: + type: servicePrincipal +``` + +### 4. Configure ACS + +You can follow [Configuring short-lived access documentation on Red Hat documentation](https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_security_for_kubernetes/4.6/html/operating/managing-user-access#configure-short-lived-access). *Ensure to use documentation from used ACS version.* + +Create a **Machine access configuration** - with the following fields: + +Issuer: `https://sts.windows.net//` + +Add a rule with: +Key: `appid` +Value: `` + +**Important:** ACS has to be able to access: `https://sts.windows.net//.well-known/openid-configuration` + +### 5. Test everything + +Use the following `roxctl` command: + +``` +roxctl central machine-to-machine exchange \ + --token="$(az account get-access-token --tenant "" --query "accessToken" --output tsv)" +``` + +*If `--output tsv` does not provide valid token format. There is option to use JSON output and `jq` command to select token from payload.* + +After successful login, running: `roxctl central whoami` should output ACS authentication information. And “User name:” in the output should be the same as provided `` in the `az` login command.