skip to content

How do you configure repository authentication in Maven, and how is a server linked to a repository?

level: middleimportance: must knowfreq 65%

answer

  1. <servers> in settings.xml
  2. server <id> == repo/mirror id (join key)
  3. username/password or privateKey/passphrase
  4. mvn --encrypt-password + settings-security.xml
  5. ID mismatch = silent 401/403

basics

~10 s

Put credentials in a <server> entry inside <servers> in settings.xml. The <server>'s <id> must match the <id> of the repository (or mirror) it authenticates. Use username/password, or privateKey for SSH-style transports.

solid answer

~40 s

Authentication lives in `settings.xml` under `<servers>`, never in the POM. Each `<server>` has an `<id>` plus credentials. The crucial rule: the `<server>`'s `<id>` must **exactly match** the `<id>` of the repository, distributionManagement repo, or mirror it secures — that ID is the join key. For HTTP(S) repos (Nexus/Artifactory) you use `<username>`/`<password>`; for SCP/SSH you use `<privateKey>` and optionally `<passphrase>`. Passwords can be encrypted via `mvn --encrypt-password` with a master password in `~/.m2/settings-security.xml`, so the file doesn't store plaintext. You can also pass extra HTTP headers or a `<configuration>` block for the transport (e.g. wagon). Because the ID is the link, a mistyped server ID silently means "no credentials sent," producing 401/403 errors that confuse people who assume the username is matched.

code

xml · 7 lines
xml
<servers>
  <server>
    <id>company-releases</id>
    <username>deploy-bot</username>
    <password>{COQLCE6DU6GtcS5P=}</password>
  </server>
</servers>

go deeper

for a junior

Knows credentials live in <servers> in settings.xml with username/password.

for a middle

Knows the id-to-id matching rule and the HTTP vs SSH (privateKey) options.

for a senior

Uses password encryption, diagnoses 401s as id-mismatch, handles mirror-vs-repo id subtleties.

for a principal

Defines org standards for credential distribution (encrypted, CI secret injection, settings templating) and rotation.

## Where credentials go Repository credentials belong in `settings.xml` under the `<servers>` element, so they stay off version control. A `<server>` entry looks like: ```xml <settings> <servers> <server> <id>company-releases</id> <username>deploy-bot</username> <password>{COQLCE6DU6GtcS5P=}</password> </server> <server> <id>internal-scp</id> <privateKey>${user.home}/.ssh/id_rsa</privateKey> <passphrase>optional-passphrase</passphrase> </server> </servers> </settings> ``` ## The ID is the link Maven matches a `<server>` to a repository by **`<id>` equality**. So if your POM (or `distributionManagement`, or a `<mirror>`) declares: ```xml <repository> <id>company-releases</id> <url>https://nexus.example.com/releases</url> </repository> ``` then the `<server id="company-releases">` supplies its credentials. If the IDs don't match, Maven simply sends **no** credentials and you get 401/403. This is the single most common settings.xml mistake. ## HTTP vs SSH - HTTP(S) repositories: `<username>` + `<password>`. - SCP/SFTP/SSH transports: `<privateKey>` + optional `<passphrase>` (instead of password). ## Encrypting passwords Plaintext passwords are discouraged. Maven supports a two-step encryption: ```bash mvn --encrypt-master-password # creates master, store in ~/.m2/settings-security.xml mvn --encrypt-password # encrypts a server password -> paste {...} into settings.xml ``` The encrypted value is wrapped in `{...}` and decrypted at runtime using the master password file. ## Mirrors need server entries too If a `<mirror>` points at an authenticated proxy/repository manager, the `<server>` id must match the **mirror's** id, not the original repo id, because the mirror is the URL actually contacted.

  • A deploy returns 401 even though the username/password are correct. What's the most likely cause?
    The <server> <id> doesn't match the repository/distributionManagement <id> (or the active mirror's id), so Maven sends no credentials. IDs are the join key.
  • How do you avoid storing a plaintext password in settings.xml?
    Use mvn --encrypt-master-password to create a master in ~/.m2/settings-security.xml, then mvn --encrypt-password to produce a {...}-wrapped encrypted value for the <password> field.

saying these in an interview costs you the question

  • Saying credentials go in the POM's <repository> element.
  • Thinking the <server> is matched by URL or username rather than by <id>.
  • Forgetting that an authenticated mirror needs the server id to match the mirror id, not the underlying repo id.

context

resolving links…