Sonatype Nexus Repository Security Guide: Realms, Tokens, Roles and Audit

A Nexus Repository instance holds the packages every build trusts and the credentials every pipeline uses to publish them, so the way users, tokens and roles are set up decides who can change what ships to production. Most access to a repository manager is non-human: CI jobs, build tools and container runtimes pulling and pushing components with stored credentials. This guide covers how authentication realms, user tokens, service account tokens, roles and privileges work in Sonatype Nexus Repository 3, how to lock down administration, which settings to change after installation, and what to log. It is for platform engineers, DevOps teams and the security teams who review them. For the wider supply chain view, see the Software Supply Chain Security Guide.

This is an independent guide from NHI Mgmt Group, based on Sonatype's public documentation as of November 2026. It is not sponsored or reviewed by Sonatype. Product features change, so confirm settings against Sonatype's current documentation.

Key takeaways

• Close the post-install defaults first. Change the initial admin password from the admin.password file, decide on anonymous access in the setup wizard, and replace the default admin email.
• Give pipelines tokens, not passwords. Service account tokens (from 3.97.0) and user tokens keep directory passwords out of settings.xml, .npmrc and CI variables, and both can expire and be revoked.
• Turn off anonymous read for production. Sonatype's own best practice is to disable it, or attach a custom role that names only the repositories that must be public.
• Build roles from repository-view privileges. Grant add and edit only on the hosted repositories a team publishes to, and treat nx-all and nexus:users:update as administrator rights.
• Keep the audit log and scripting defaults. The Audit capability is on by default and Groovy scripting is off by default; keep both that way and forward audit.log to your SIEM.

How identity and access work in Sonatype Nexus Repository

Nexus Repository 3 separates authentication, handled by realms, from authorisation, handled by roles made of privileges. Every request, from the web UI, the REST API or a build tool, is authenticated by one of the active realms and then checked against the roles mapped to that user.

Realms

Realms are activated and ordered under Security then Realms. Order decides which realm wins when the same user name exists in more than one. Sonatype advises keeping the Local Authenticating Realm at the top of the active list, so the local administrator can always sign in, and never removing every realm, which locks everyone out.

Availability: Sonatype marks the SAML, Crowd, OAuth2 and User Token realms as Pro features, and lists service account tokens for Nexus Repository Pro, Pro+ and Sonatype Cloud. Activate only the realms that match your licence and the formats you host.

Roles and privileges

• Repository View privileges: created automatically for each format and repository, named nx-repository-view-{format}-{repository}-{action}. Actions are browse (see in UI and search), read (download), edit, add (upload) and delete.
• Repository Admin privileges: control the configuration of repositories, separate from their content.
• Repository Content Selector privileges: limit access to content matching a selector expression, such as one team's namespace in a shared repository.
• Application privileges: control UI and API features such as users, roles, realms and settings.
• Wildcard and script privileges: nx-all grants nexus:*, and script privileges control the Groovy script APIs.
• Admin-equivalent rights: Sonatype warns that nexus:users:update lets a user change roles, including their own, so it is as powerful as nx-admin.

Admin roles and privileged access

1. Secure the initial administrator: the first admin password is written to admin.password in the data directory and must be changed before the setup wizard or REST API can be used. Set a long unique password, store it in a vault and replace the default admin email address.
2. Use a central identity source for people: Nexus supports LDAP, SAML and Crowd realms; we recommend one of them over local user management. For LDAP, use ldaps; Sonatype advises against simple authentication without it in production because passwords travel in clear text. Use a bind user with read access only to the users and groups Nexus needs. See the LDAP Security Deep Dive Guide or the SAML Security Guide.
3. Map groups to roles: when an LDAP or SAML group matches a Nexus role ID, members receive that role. Keep administrator membership in one small directory group and review it each quarter.
4. Keep administration local and rare: keep the Local Authenticating Realm above SAML so administrators can sign in if the identity provider is down, but treat the local admin account as break-glass. See the Break-Glass Account Guide.
5. Separate operational duties: create roles for repository administration, security administration (users, roles, realms, tokens) and read-only support, rather than giving nx-admin to everyone who manages repositories. Keep nx-usertoken-users (reset other users' tokens) and nx-sa-admin with the security role.
6. Enforce local password rules: set nexus.password.validator (a regular expression) and nexus.password.validator.message in nexus.properties for any remaining local users.
7. Keep login rate limiting on: authentication attempt rate limiting is enabled by default, starting after 3 consecutive failures with a 30 second base delay rising to 900 seconds, set by the nexus.auth.ratelimit.* properties.
8. Design for granting, not restricting: Sonatype advises against negative content selectors, which are slow and easily overridden by other permissions. Use team-specific hosted repositories where read access must be restricted.

Integrations, API tokens and service accounts

Pipelines, build agents and deployment tools are the heaviest users of a repository manager. Each is a non-human identity that can publish components everyone else then trusts. See the CI/CD Pipeline Identity Security Guide.

Choosing a credential type

• Service account tokens for pipelines: create them under Settings, Security, Service Account Tokens, after activating ServiceAccountRealm. Clients authenticate with the service account name and the password sat.{token}, or a bearer header for some formats. Sonatype's guidance: store tokens in a secrets manager, never commit them, prefer time-limited tokens, use Never sparingly, give the least-privileged role, and revoke unused tokens.
• One token per pipeline and purpose: separate tokens for read-only dependency resolution and for publishing to a hosted repository, each with its own role, so a leaked read token cannot publish.
• User tokens for people: enable them under Settings, User Token (needs nx-usertoken-settings), and turn on Require user tokens for repository authentication so repository URLs accept only tokens. Sonatype notes this option does not work for Docker when anonymous Docker pull is enabled.
• Plan expiry before turning it on: user token expiry is measured from each token's creation date, so existing tokens older than the limit expire immediately. Warn teams and update CI settings first.
• Keep tokens out of files in repositories: Maven reads the token from the server section of settings.xml and npm from .npmrc. Inject these at build time from a secrets store. See the Secrets Management Guide.
• Scripts and the REST API: Groovy scripting has been off by default since 3.21.2, nexus.scripts.allowCreation defaults to false, and Sonatype has announced Groovy scripting end of life for December 2026. Automate with the REST API and a service account token instead.

Logging and detection

The Audit capability is created and enabled by default and writes one JSON object per line to $data-dir/log/audit/audit.log, rotated daily with up to 90 days kept. Each entry records the initiator, domain, type and context. Forward it to a SIEM so the record survives a compromise of the server.

Metrics that show it is working

• Percentage of pipeline access using service account or user tokens rather than passwords.
• Number of service account tokens with expiry Never (target near zero, each with an exception).
• Number of users holding nx-admin, nx-all or nexus:users:update.
• Percentage of proxy repositories with HTTPS remotes and an assigned routing rule.
• Days since the last review of roles and of the anonymous role.

Hardening baseline

Rollout plan

1. Inventory: export users, roles, realms, anonymous settings, proxy remotes and every credential configured in CI that points at Nexus.
2. Test instance: restore a backup to a test server and trial realm order, SAML, token settings and routing rules there rather than in production, the approach Sonatype recommends for testing scripts.
3. Introduce tokens: issue service account tokens per pipeline and user tokens per person, and move CI to them while passwords still work.
4. Enforce: turn on Require user tokens for repository authentication and token expiry, then disable anonymous access, after notifying teams.
5. Tighten roles: replace broad roles with repository-scoped ones and remove stale users. Roll back by restoring the previous role assignment from your export if builds fail.
6. Keep current: apply Sonatype's security updates promptly and follow Sonatype's security advisories.

Framework mapping

Common misconfigurations

• Anonymous read left on after installation: anonymous read stays on until it is configured in the wizard, and the built-in anonymous role reads every repository. Turn it off or attach a narrow custom role.
• Directory passwords in build files: a developer's LDAP password in settings.xml or .npmrc unlocks far more than Nexus. Replace it with a user token or service account token.
• One shared deploy account for every pipeline: a leak from any job can publish to every release repository, and the audit log cannot tell jobs apart. Issue one token per pipeline with its own role.
• Service account tokens set to Never by default: use expiring tokens and rotate them from the secrets manager; keep Never for documented exceptions.
• Proxy repositories with no routing rules: an unrestricted proxy can fetch any public name, including one that collides with an internal package. Add ALLOW rules for expected namespaces. See the Malicious Package and Dependency Confusion Guide.
• Local Authenticating Realm moved below SAML or removed: administrators can be locked out when the identity provider fails, and recovery is difficult. Keep it at the top.

Practitioner checklist

• Change and vault the initial admin password and replace the default admin email.
• Disable anonymous access, or assign a custom role limited to named public repositories.
• Activate only the realms you need, with the Local Authenticating Realm at the top; use ldaps or SAML for people.
• Create repository-scoped roles; limit nx-admin, nx-all and nexus:users:update to a small group.
• Issue one expiring service account token per pipeline and purpose, stored in a secrets manager.
• Enable user tokens, require them for repository URLs and set token expiry.
• Serve Nexus over HTTPS only and use HTTPS for every proxy remote.
• Assign routing rules to proxy repositories for the namespaces you use.
• Keep scripting off, rate limiting on and the audit log forwarded to your SIEM.
• Back up configuration and blob stores, test restores, and apply Sonatype security updates promptly.

Standards and references

• Sonatype: Realms
• Sonatype: Service Account Tokens
• Sonatype: User Tokens
• Sonatype: Privileges
• Sonatype: Administration Best Practices
• Sonatype: Post Install Checklist
• Sonatype: Auditing
• Sonatype: Routing Rules

Related NHI Mgmt Group resources: Malicious Package and Dependency Confusion Guide · CI/CD Pipeline Identity Security Guide · Service Account Security Guide · Software Supply Chain Security Guide