Repository navigation
client/dockerhub: return a ready-to-use Docker Hub credential (username, expiry, expired-session error, Desktop connect) #682
Description
Summary
Docker Compose now uses Docker Desktop's Docker Hub session (via client/dockerhub) to authenticate pulls. To get a credential it can actually use, Compose had to write about 120 lines on top of the SDK. Most of that code isn't specific to Compose. Any consumer that wants "the signed-in user's Docker Hub credential" (the CLI, buildx, other tools) would have to write the same thing. This issue lists what client/dockerhub (checked at client/v0.1.2 and main) is missing, with links to the Compose code that fills each gap.
Compose implementation: internal/registry/desktop.go
1. GetDefaultSession does not give you a username
A registry credential needs a username. containerd treats a password with no username as a refresh token. UserSession.Claims.Username is often empty, so Compose has to call GetDefaultProfile again:
session, err := s.hub.GetDefaultSession(ctx)
// ...
username := session.Claims.Username
if username == "" {
profile, err := s.hub.GetDefaultProfile(ctx) // second round trip
// ...
username = profile.Username
}
if username == "" {
return ..., errNoUsername
}Internally, GetDefaultSession already loads the default profile to find the account entry, then discards it. So callers pay for two profile lookups.
Ask: return the username, or the whole profile, with the session. For example, add Profile/Username to UserSession, or provide a dedicated call (see the proposal below).
2. No token expiry helper
To know how long a token can be reused, Compose reads Claims.ExpiresAt. If that is missing, it decodes the JWT payload itself and reuses dockerhub.NumericDate to parse exp:
func sessionExpiry(session dockerhub.UserSession) (time.Time, bool) {
if exp := session.Claims.ExpiresAt; exp != nil {
return exp.Time, true
}
return jwtExpiry(session.AccessToken) // split, base64-decode, unmarshal {"exp"}
}The package already owns Claims and NumericDate, and documents that "Claims are zero when the payload carries none". Parsing the token belongs there.
Ask: func (s UserSession) ExpiresAt() (time.Time, bool), and/or fill in Claims from the JWT when the stored payload leaves them out.
3. An expired session is returned as if it were valid
GetDefaultSession returns a stored token even after it has expired (for example, the user signed out or Desktop hasn't refreshed it). Every caller has to check the expiry itself and define its own error:
var errSessionExpired = errors.New("the session has expired (not signed in to Docker Desktop?)")
// ...
if expiresAt, ok := sessionExpiry(session); ok {
validUntil = expiresAt.Add(-sessionExpirySkew)
if !now.Before(validUntil) {
return ..., errSessionExpired
}
}Ask: a dockerhub.ErrSessionExpired that wraps ErrNoSession, returned for expired tokens, ideally with a configurable clock-skew margin.
4. No single way to check "no usable session"
To decide between falling back quietly to other credentials and warning the user, Compose checks three unrelated errors:
func isSessionUnavailable(err error) bool {
return errors.Is(err, seclient.ErrSecretsEngineNotAvailable) ||
errors.Is(err, dockerhub.ErrNoSession) ||
errors.Is(err, errSessionExpired)
}Ask: with (3) in place, document a single check for this case (e.g. errors.Is(err, dockerhub.ErrNoSession) also covering "engine not available"), or provide a helper such as dockerhub.IsUnavailable(err).
5. Connecting to Desktop requires the unstable x module
The client.New doc says "To connect to Docker Desktop, use WithSocketPath(api.DesktopSocketPath())". But api lives in github.com/docker/secrets-engine/x, so a stable-client consumer has to depend on x just to find the socket:
c, err := seclient.New(
seclient.WithSocketPath(api.DesktopSocketPath()), // github.com/docker/secrets-engine/x/api
seclient.WithTimeout(desktopLookupTimeout),
)
return c.HubAuth(opts...), nilAsk: client.WithDesktopSocket() / client.NewDesktop(...), or re-export DesktopSocketPath from client.
6. (Optional) A caching, retrying credential source
Compose also wraps the lookup with a cache: one shared lookup for concurrent pulls, token reuse until it nearly expires, and a backoff after failures so it doesn't hit a hung or absent Desktop on every pull:
This is generic too. A wrapper such as dockerhub.NewCachedAuth(auth, opts...) would be useful, but it is the most debatable item if the SDK wants to stay stateless.
Proposal
Items 1–3 together could be one call that returns what a registry client needs:
type Credential struct {
Username string
AccessToken string
ExpiresAt time.Time // zero if unknown
}
// GetDefaultCredential returns the default account's credential. It returns
// ErrNoDefaultProfile / ErrNoSession when nobody is signed in, and
// ErrSessionExpired (wrapping ErrNoSession) when the stored token has expired.
GetDefaultCredential(ctx context.Context) (Credential, error)With that, plus (4) and (5), the Compose side shrinks to building a types.AuthConfig from Credential. jwtExpiry, sessionExpiry, errNoUsername, errSessionExpired, isSessionUnavailable, the second profile lookup and the dependency on x/api would all go away. The matching Compose tests (TestJWTExpiry, …ExpiryFromTokenWhenClaimsLackIt, …UsernameFromProfile, TestIsSessionUnavailable) would move here.
Happy to send PRs for any of these.
Activity
Benehiko commentedon Oct 9, 2026
Update on items 1 and 2: we won't add a separate
Usernamefield toUserSession.UserSession.Claims.Usernameis the field to use.Claims.Usernamecame back empty because Docker Desktop didn't always parse the access token's claims when it stored the credential. That's fixed, so in most casesClaimsis now filled in, includingexp. A migration is underway that will make this consistent for all stored credentials. Once it's done, Compose'sGetDefaultProfilefallback and its own JWTexpdecoding shouldn't be needed.Closing #683, which added the field. Items 3–6 are unaffected.