Users, Roles, Privileges, Realms, Anonymous Access, User Tokens, and Least-Privilege Design: Concepts, Architecture, and Mental Model

1. The practical problem: a repository request is also an identity decision

Earlier chapters proved that repository type, package path, group routing, and content-selector policy all affect whether bytes are returned. There is another question before those controls can help: who is making the request? A browser session, Maven build, npm client, Docker engine, CI runner, or operator script presents some form of credential—or no credential at all. Nexus must first map that request to a principal, then determine what that principal is allowed to do.

If identity and authorization are blended together, operators create dangerous shortcuts: shared admin credentials in CI, broad roles assigned because a token failed, anonymous reads enabled to make a build pass, or realm changes used to solve what was actually a repository privilege problem.

2. The authentication-to-authorization chain

flowchart TD
C[Client request] --> R[Active realms in order]
R --> I[Authenticated identity]
A[No credentials] --> AN[Anonymous principal when enabled]
AN --> I
I --> RO[Assigned roles]
DR[Default role if configured] --> RO
RO --> P[Privileges and inherited roles]
P --> Q{Requested action on resource}
Q -->|matching grant exists| Y[Allow]
Q -->|no matching grant| N[Deny]

A realm is an authentication source or protocol handler. It helps Nexus identify a principal; it does not itself grant repository content. The authenticated user or system identity receives one or more roles. Roles aggregate privileges, and privileges grant actions such as browse, read, add, edit, delete, or application administration. Nexus permissions are additive: another role can widen the result.

The anonymous path is a special case. When anonymous access is enabled, an unauthenticated request is evaluated as the configured anonymous principal. That principal's role grants define what unauthenticated clients can do.

3. Define the security objects

4. Local users versus external identities

Nexus can store local users in its own security source and can also authenticate against external identity systems through configured realms. Local identities are valuable for bootstrap, recovery, disposable labs, and tightly scoped service accounts. For larger organizations, centralized identity usually reduces onboarding/offboarding work and lets account lifecycle policy live in the authoritative identity provider.

Do not conclude that “external” means “automatically safer.” External identity still needs correct Nexus role mapping, group mapping, credential/token handling, and a recovery path if the provider is unavailable. Chapter 16 handles LDAP, SAML, and OIDC in depth; this lesson only establishes the boundary.

5. Built-in admin and anonymous identities

The default admin account has full administrative authority and is intended for initial setup and recovery-sensitive administration. Its initial random password is stored in admin.password in the data directory and must be changed during initial setup. It is not a CI credential and should not be a daily developer identity.

The default anonymous identity is not a login account. When anonymous access is active, requests without credentials are treated as that principal. Sonatype recommends disabling anonymous access when it is not needed or narrowing what anonymous users can reach.

6. Password, User Token, and package API key are different credentials

Credential type does not define authorization. Whether a password or token authenticates the same principal, the principal's effective roles and privileges still decide access.

7. Read-only inspection before mutation

On a disposable self-hosted instance, capture the running status, anonymous configuration, active/available realms, users, roles, and privileges. Use an administrator credential stored in a permission-restricted temporary netrc file so the secret does not appear in process arguments:

export NX_URL="http://127.0.0.1:8081"
export NX_USER="admin"
read -r -s -p 'Disposable Nexus admin password: ' NX_PASS; echo
export NX_AUTH_FILE="$(mktemp)"; chmod 600 "$NX_AUTH_FILE"
printf 'machine 127.0.0.1 login %s password %s\n' "$NX_USER" "$NX_PASS" > "$NX_AUTH_FILE"
unset NX_PASS

mkdir -p ch15-readonly-evidence
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/status"   > ch15-readonly-evidence/status.txt
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/anonymous"   > ch15-readonly-evidence/anonymous.json
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/realms/active"   > ch15-readonly-evidence/realms-active.json
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/realms/available"   > ch15-readonly-evidence/realms-available.json
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/users"   > ch15-readonly-evidence/users.json
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/roles"   > ch15-readonly-evidence/roles.json
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/privileges"   > ch15-readonly-evidence/privileges.json

These responses are security configuration and identity metadata. They do not inspect repository blobs or database tables. Review the files before sharing them because usernames, email addresses, role names, and internal naming conventions may still be sensitive even when passwords are absent.

8. Realm ordering is authentication precedence

Current Nexus exposes active realms as an ordered list. If two realms can resolve the same username, the active order decides which realm has priority. Do not “fix” a 403 by reordering realms until you know whether authentication actually failed. A 403 after successful authentication usually points to authorization—not realm precedence.

9. Why this matters in DevOps

Build agents and deployment jobs often operate continuously and carry credentials into environments humans do not watch interactively. A compromised CI credential with nx-admin can alter repositories, users, roles, cleanup rules, and security configuration. A compromised CI identity with only add/read to one hosted repository has a much smaller blast radius. Identity design is therefore part of artifact integrity and availability, not merely account administration.

10. Common wrong mental models

• “Authenticated means authorized.” Authentication identifies; privileges authorize.
• “A restrictive role overrides a broad role.” Nexus grants are additive.
• “Anonymous access is outside RBAC.” Anonymous requests are evaluated through the configured anonymous principal/role.
• “A browser SSO login solves package-client authentication.” Noninteractive clients often need a different credential method.
• “A User Token is a Community feature because the API exists.” The current self-hosted feature matrix lists User Token Support as Pro-only.

11. Knowledge check

12. Summary and next step

Nexus security is a pipeline: realm identifies a principal; roles aggregate privileges; privileges grant actions; anonymous access maps unauthenticated requests into the same authorization model. Lesson 2 turns this model into a disposable Community lab with named users, a service identity, explicit positive/negative tests, anonymous-access control, and credential rotation.

Official references and version notes

• Sonatype: Access Control — RBAC object model, default roles, additive grants, and least privilege.
• Sonatype: Users and Roles.
• Sonatype: Privileges — repository, application, selector, and wildcard privilege semantics.
• Sonatype: Realms and Authentication.
• Sonatype: Anonymous Access.
• Sonatype: User Tokens and User Tokens API.
• Sonatype: Security Management API and API Reference.
• Self-Hosted Nexus Repository Feature Matrix — User Token Support and enterprise identity boundaries.
• Sonatype: Download and 2026 self-hosted release notes.

Version-sensitive statements were rechecked on 2026-08-26. Sonatype's current official self-hosted download page exposes Nexus Repository 3.95.0 (archive build 3.95.0-07), while version-index pages may lag. The mandatory chapter path is Community-compatible: local users, roles, privileges, realms, anonymous-access settings, Raw repositories, and temporary passwords. Self-hosted User Token Support is Pro-only and appears only as an optional extension or fixture.