From c2e8b78e9a2cfca2ef2f3cc426e504d356c0b93a Mon Sep 17 00:00:00 2001 From: Shahram Kalantari Date: Wed, 4 Dec 2024 21:38:48 +1000 Subject: [PATCH] docs: update the design doc Signed-off-by: Shahram Kalantari --- docs/design/Refactor Azure authentication.md | 22 +++++++++++++++++++ docs/img/AzureAuthRefactor/image.png | Bin 0 -> 7005 bytes 2 files changed, 22 insertions(+) create mode 100644 docs/img/AzureAuthRefactor/image.png diff --git a/docs/design/Refactor Azure authentication.md b/docs/design/Refactor Azure authentication.md index 9d69370d1..b5d662b2b 100644 --- a/docs/design/Refactor Azure authentication.md +++ b/docs/design/Refactor Azure authentication.md @@ -120,6 +120,17 @@ func NewChainedCredential() (*azidentity.ChainedTokenCredential, error) { return azidentity.NewChainedTokenCredential(creds, nil) } ``` + +In the code sample above, the chained token credential will try to authenticate using workload identity first, then managed identity will be attempeted, and then the CLI authentication will be attempted. If any of the attempts succeed at any stage, it will return the corresponding credential. + +There is another option that can be used which is the default azure credential: `azidentity.NewDefaultAzureCredential`. It's an opinionated, preconfigured chain of credentials and is designed to support many environments, along with the most common authentication flows and developer tools. In graphical form, the underlying chain looks like this: +![image](../img/AzureAuthRefactor/image.png) + +Howecer, this option is not recommended for the following reasons: +1. Debugging challenges: When authentication fails, it can be challenging to debug and identify the offending credential. You must enable logging to see the progression from one credential to the next and the success/failure status of each. In contrast, [debugging a chained credential](https://www.rfc-editor.org/rfc/rfc3280#section-1) is relatively easy. +2. Unpredictable behavior: DefaultAzureCredential checks for the presence of certain environment variables. It's possible that someone could add or modify these environment variables at the system level on the host machine. Those changes apply globally and therefore alter the behavior of DefaultAzureCredential at runtime in any app running on that machine. +3. Ability to provide required parameters: When using the default azure credential option, we can only rely on the environment variables, meaning that we cannot provide the client_id, tenant_id, or any other parameter explicitly. This is particularly problematic when Ratify is provided with multiple auth providers. With the chanined token credentials, each credential type in the chain can be provided with the required parameters explicitly if needed. + #### **2. Refactor ORAS Auth Providers** - Combine `azureidentity.go` and `azureworkloadidentity.go` into a single file. - Update the implementation to use the `pkg/common/cloudauthproviders/azure` package for authentication. @@ -129,6 +140,17 @@ func NewChainedCredential() (*azidentity.ChainedTokenCredential, error) { - Update the providers to leverage the new `pkg/common/cloudauthproviders/azure` package for authentication. - Remove redundant logic and ensure consistent authentication processes across all providers. +#### **4. Configuration change** +- Introduce a new generic auth provider: `azure` +. A sample Oras store config has a section for auth provider that looks like this: +``` +authProvider: + name: azureWorkloadIdentity + clientID: XYZ +``` +We will introduce a new authProvider: `name: azure`. This will let Ratify know that it should use the chained token credential. We can provide the required parameters explicitly like `clientId` and `tenantID` as well, and this will let the chain token credential know that it will need to use these parameters instead of the environment variables. For backward compatibility, we will also provide the ability to override the chained token credential implementation by specifying additional attribute named `credential` which can be set to either `managedIdentity`, `workloadIdentity`, or `cli`. This will trigger the specified credential option instead of the chanined token credential. + + --- ### **Advantages of the Proposed Refactoring** diff --git a/docs/img/AzureAuthRefactor/image.png b/docs/img/AzureAuthRefactor/image.png new file mode 100644 index 0000000000000000000000000000000000000000..3f879ade279ee629ef81ce0f73942eff0b348160 GIT binary patch literal 7005 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 E4>z4qu>b%7 literal 0 HcmV?d00001