fetchBearerToken reverts too easily to basic authentication

[TerryHowe]

The fetchBearerToken method seems to revert to basic authentication too easily. With docker.io for instance, they claim to only support bearer auth in their 'WWW-Authenticate', but they do not support RefresherToken as a password or personal access token. You can use bearer authentication with as pasword with either a password or a personal access token though.

https://github.com/oras-project/oras-go/blob/main/registry/remote/auth/client.go#L305

I am getting reports of other registries that request bearer via the WWW-Authenticate and auth fails with ORAS because it reverts to basic auth which is not supported.

[TerryHowe]

Related helm/helm#30970

[Wwwsylvia]

I am getting reports of other registries that request bearer via the WWW-Authenticate and auth fails with ORAS because it reverts to basic auth which is not supported.

Does it help to set ForceAttemptOAuth2 to true?

[mattfarina]

@Wwwsylvia In the Helm case, Helm interacts with some registries that do not support OAuth2 while others do. Dealing with both is important rather than setting for just one.

[TerryHowe]

From a user perspective, it makes a lot more sense to have a ForceBasicAuth for bearer auth rather than a variable to actually use bearer auth for bearer auth.

[Wwwsylvia]

@Wwwsylvia In the Helm case, Helm interacts with some registries that do not support OAuth2 while others do. Dealing with both is important rather than setting for just one.

@mattfarina Makes sense. To facilitate Helm, what would be the desired behavior of oras-go for getting a bearer token? Should it always attempt OAuth2 first and automatically fallback to the distribution GET flow under certain conditions? Or should it choose the flow to follow based on specific conditions?

Currently, in the oras-go implementation, if ForceAttemptOAuth2 is set to true, the OAuth2 flow will be followed when

• Either username/password or refresh token is provided.

The distribution flow will be followed only when:

• No credentials are provided.

[Wwwsylvia]

From a user perspective, it makes a lot more sense to have a ForceBasicAuth for bearer auth rather than a variable to actually use bearer auth for bearer auth.

@TerryHowe We should avoid changing the default behavior as it would be breaking. We can consider introducing an option for the new behavior if needed, maybe something like PreferOAuth2? 🤔

Anyway, before making any changes, we need to identify the requirements and expected behavior here.

[TerryHowe]

I think there are two options here, we could do as you suggest and create something like PreferOAuth2 (although I don't love that name) or cut a major release for the breaking change.

[TerryHowe]

The reason I'm kind of in favor or new major release is it just isn't right to favor basic auth when the registry requests bearer.

[Wwwsylvia]

@TerryHowe We do have a plan for v3 which may include significant refactoring of the auth client. But we don't think it is the right moment to cut a v3 release just for this feature.

If the proposal is to attempt OAuth2 whenever credentials are provided (#973), that’s effectively the same as setting ForceAttemptOAuth2 = true.

One option to consider is updating DefaultClient to have ForceAttemptOAuth2 enabled by default. Since this change isn’t considered breaking, it could be included in the next minor release v2.7.0.

/cc @shizhMSFT for comments on planning and the security concern

[shizhMSFT]

The authentication strategy of oras-go v2 follows distribution token authentication for maximum compatibility. Since distribution token authentication only supports username / password authentication and does not support identity token, oras-go v2 follows OAuth2 token authentication when authenticating using identity token.

Note

When ForceAttemptOAuth2 in auth.Client of oras-go v2 is set. oras-go v2 only attempts OAuth2 token authentication without falling back to distribution token authentication on error when authenticating using username and password.

I want to clarify that distribution token authentication (i.e. fetchDistributionToken) is not basic auth for the registry server. It does send bearer token to the registry server just like the OAuth2 token authentication (i.e. fetchOAuth2Token).

Here's the sequence diagram of how distribution token authentication works.

sequenceDiagram
    participant oras as oras-go v2
    participant auth as Token Server
    participant reg as Registry Server

    oras->>auth: GET request with username / password in `WWW-Authenticate: Basic`
    auth-->>oras: Return access token
    oras->>reg: Request with access token in `WWW-Authenticate: Bearer`
    reg-->>oras: Return registry resource 

Loading

Here's the sequence diagram of how OAuth2 token authentication works.

sequenceDiagram
    participant oras as oras-go v2
    participant auth as Token Server
    participant reg as Registry Server

    oras->>auth: POST request with username / password or identity token in the request body
    auth-->>oras: Return access token
    oras->>reg: Request with access token in `WWW-Authenticate: Bearer`
    reg-->>oras: Return registry resource 

Loading

As you can observe, both authentication methods use Bearer tokens.

---

On the other side, oras-go v1 is built on top of containerd 1.x. Therefore, it follows the containerd auth logic as described in authorizer.go. Basically, oras-go v1 / containerd always attempt OAuth2 token authentication and fall back to distribution token authentication on error with response status code 4xx.

Note

containerd 2.x has the same authentication strategy as 1.x (see authorizer.go).

---

Now back to the original issue, helm/helm#30970 reports that the auth method changes from oras-go v1 to oras-go v2, causing regressions.

To fix it, the best way is to provide an option ContainerdMode in auth.Client of oras-go v2.

type Client struct {
	// other fields...

	// ForceAttemptOAuth2 controls whether to follow OAuth2 with password grant
	// instead the distribution spec when authenticating using username and
	// password.
	// References:
	// - https://distribution.github.io/distribution/spec/auth/jwt/
	// - https://distribution.github.io/distribution/spec/auth/oauth/
	ForceAttemptOAuth2 bool

	// ContainerdMode controls whether to follow the authentication stragegy of
	// containerd. Precisely, always follow OAuth2 and then fall back to the
	// distribution spec when authenticating using username and password.
	// ForceAttemptOAuth2 is ignored when ContainerdMode is set to true.
	ContainerdMode bool
}

[shizhMSFT]

Based on my understanding, the assumption of authentication strategy of containerd is that all registries adopt OAuth2, and its fallback method will be removed eventually.

oras-go v2 does the other way around. It tries to achieve max compatibility as possible and also gives an option ForceAttemptOAuth2 when the industry is mature where all registries adopt OAuth2.

I cannot tell which vision / direction is better but ContainerdMode might be a good alternative.

[FeynmanZhou]

Linking helm/helm#30963