skip to content

What does the `authentication {}` block control on a repository, and when would you explicitly choose BasicAuthentication versus the default behavior?

level: middleimportance: nice to knowfreq 25%

answer

  1. authentication = which scheme (how)
  2. credentials = what to send
  3. BasicAuthentication = preemptive header
  4. default = 401 challenge negotiation
  5. Basic only over HTTPS

basics

~10 s

The authentication {} block picks which auth scheme Gradle uses for a repo. Adding create<BasicAuthentication>("basic") forces Gradle to send Basic credentials preemptively instead of waiting for a 401 challenge.

solid answer

~30 s

By default, when you give a repo `PasswordCredentials`, Gradle negotiates authentication — it sends the request, and on a 401 challenge replies with the scheme the server asked for (often digest/basic). The `authentication {}` block lets you *override* that and pin a specific scheme: `create<BasicAuthentication>("basic")` makes Gradle send the `Authorization: Basic` header *preemptively* on the first request. This matters for servers that don't issue a proper challenge (so negotiation never starts) or that only accept basic. For header-token repos you instead use `HttpHeaderAuthentication`. So the block is the 'how to authenticate' switch, complementing credentials, which are the 'what to send'.

code

kotlin · 9 lines
kotlin
repositories {
    maven {
        url = uri("https://repo.example.com/private")
        credentials(PasswordCredentials::class)
        authentication {
            create<BasicAuthentication>("basic")  // send Basic header preemptively
        }
    }
}

go deeper

for a junior

Know that authentication{} chooses how credentials are sent and that the default usually just works.

for a middle

Distinguish default 401-challenge negotiation from preemptive BasicAuthentication and know when to pin a scheme.

for a senior

Reason about non-conforming servers, avoiding a round trip, and the HTTPS-only requirement for Basic.

for a principal

Set conventions discouraging plain Basic over http and standardizing scheme choice across the org's repositories.

## Credentials vs authentication schemes Two orthogonal concepts: - **Credentials** — the secret material: `PasswordCredentials` (username/password), `HttpHeaderCredentials` (header name/value), `AwsCredentials` (for S3-backed repos). - **Authentication schemes** — *how* those credentials are presented over HTTP: `BasicAuthentication`, `DigestAuthentication`, `HttpHeaderAuthentication`. ## Default negotiation If you supply `PasswordCredentials` and leave `authentication {}` unset, Gradle uses challenge-response: it makes an unauthenticated request and, on a `401` with a `WWW-Authenticate` header, responds using the indicated scheme. This works for most servers automatically. ## When to pin a scheme ```kotlin repositories { maven { url = uri("https://repo.example.com/private") credentials(PasswordCredentials::class) authentication { create<BasicAuthentication>("basic") } } } ``` Declaring `BasicAuthentication` makes Gradle send the Basic `Authorization` header **preemptively** — on the very first request, before any challenge. You do this when: - the server doesn't return a proper `401` challenge (so negotiation never kicks in), - the server only supports Basic and you want to skip the round trip, or - you must avoid a scheme the server would otherwise negotiate. ## Header tokens are a different scheme For token-in-header repos you use `HttpHeaderAuthentication` with `HttpHeaderCredentials` instead — same block, different scheme. The two are not interchangeable: Basic encodes username:password in base64; HttpHeader sends an arbitrary header you specify. ## Security note Basic (and preemptive Basic especially) sends credentials in a trivially decodable form, so it must only be used over HTTPS. Never point Basic-auth repos at plain `http://` URLs.

  • What is the practical effect of declaring BasicAuthentication versus leaving authentication{} empty?
    Empty relies on 401-challenge negotiation; declaring BasicAuthentication sends the Basic Authorization header preemptively on the first request, needed when the server doesn't issue a proper challenge or only supports Basic.
  • Why must Basic authentication only be used over HTTPS?
    Basic encodes username:password as base64, which is trivially decoded; without TLS it is effectively sent in clear text and can be intercepted.

saying these in an interview costs you the question

  • Saying authentication{} and credentials are the same thing — one is the scheme (how), the other is the secret (what).
  • Using Basic auth against a plain http:// repository URL.

context

resolving links…