LDAP, SAML, OIDC, External Identity, Credential Rotation, and Authentication Troubleshooting: Concepts, Architecture, and Mental Model

1. The practical problem: “who are you?” has several layers

Chapter 15 separated users, roles, privileges, anonymous access, and service identities. External identity adds another boundary: Nexus may no longer verify a password from its own local user database. Instead it can ask an LDAP directory, participate in a SAML browser flow, or redirect a browser to an OpenID Provider. Yet repository authorization still ends in the same place: Nexus roles and privileges decide whether an authenticated principal can read, publish, delete, or administer.

A production failure can therefore occur at several layers. A successful LDAP TCP connection does not prove that the user search base is correct. A valid SAML assertion does not prove its audience or group attribute matches Nexus configuration. A valid OIDC login does not prove the group claim maps to a Nexus role. And none of those browser-centric flows automatically tells Maven, npm, Docker, pip, or NuGet how to authenticate.

2. Three protocols, three mental models

flowchart TD
LDAPC[Basic-auth client or UI] --> L[Nexus LDAP realm]
L --> D[LDAP bind and search]
D --> LG[Directory user and groups]
B[Browser] --> S[Nexus SAML SP]
S --> IDP[SAML IdP]
IDP --> AS[SAML assertion]
B --> O[Nexus OIDC relying party]
O --> OP[OpenID Provider]
OP --> TK[ID/access token claims]
LG --> MAP[External group to Nexus role mapping]
AS --> MAP
TK --> MAP
MAP --> P[Nexus privileges]
P --> R[Repository or administration action]
LOCAL[Local break-glass identity] --> P

The LDAP path is directory-oriented. Nexus uses connection/bind settings, searches for a user, resolves attributes and group membership, then maps external groups to Nexus roles. Nexus maintains a local LDAP authentication cache to reduce directory traffic.

SAML is browser SSO. Nexus acts as a SAML Service Provider (SP), the enterprise identity system is the Identity Provider (IdP), and a signed assertion returns identity attributes such as username and groups. The Assertion Consumer Service (ACS) is the Nexus endpoint that receives that response. Current Nexus SAML is Pro-only.

OIDC is an identity layer over OAuth 2.0. Nexus acts as a relying party, redirects the browser to an OpenID Provider, then validates tokens and maps configured claims to the Nexus user and groups. Current self-hosted OIDC is Pro-only and requires HTTPS.

3. Define the objects before configuring them

4. Realm order is authentication precedence, not authorization priority

When multiple realms can resolve the same username, active-realm order determines which source wins the name clash. It does not give that principal extra repository privileges. Authorization is still role/privilege driven.

Never remove every active realm. Sonatype warns that doing so prevents access for all users, including administrators.

5. Browser SSO is not package-client authentication

Current SAML documentation explicitly says format clients such as Maven, Docker, and npm do not support SAML SSO and, in Pro, can use Nexus User Tokens. On Community, a dedicated local or LDAP-backed service identity can be the free-compatible noninteractive path when the client supports ordinary Nexus authentication.

6. Where identity state lives

7. Read-only inspection before mutation

export NX_URL="http://127.0.0.1:8081"
export LAB="$(mktemp -d)"
mkdir -p "$LAB/evidence"
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
' "$NX_USER" "$NX_PASS" > "$NX_AUTH_FILE"
unset NX_PASS

curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/status" > "$LAB/evidence/status.txt"
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/system/license" > "$LAB/evidence/license.json" || true
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/realms/active" > "$LAB/evidence/realms-active.json"
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/roles" > "$LAB/evidence/roles.json"
curl -fsS --netrc-file "$NX_AUTH_FILE" "$NX_URL/service/rest/v1/security/users" > "$LAB/evidence/users.json"

Then inspect Settings → Security → Realms and, if present for your edition, LDAP, SAML, or OAuth 2.0 settings. Do not enable a realm merely because it appears in documentation. Use the running instance's Swagger/OpenAPI page to confirm version-specific REST endpoints before automation.

8. Trust boundaries and rotation

External authentication introduces network trust (DNS, TLS, proxy), credential trust (bind/client secrets), assertion/token trust (signatures, issuer/audience), and authorization trust (group-to-role mapping). Rotating one layer does not automatically rotate the others. For example, replacing an LDAP server certificate can be independent of rotating the LDAP bind password; changing a SAML IdP signing key requires updated metadata; rotating an OIDC client secret must be synchronized with the provider and Nexus.

Fail closed. If identity validation is uncertain, the correct result is denied access—not anonymous fallback, not a broad local role, and not temporarily granting nx-admin to make the incident disappear.

9. Knowledge check

10. Production pattern and next step

A production identity design documents protocol, realm order, identity source, group/claim mapping, noninteractive client credentials, certificate/secret ownership, rotation procedure, and a tested recovery principal. Lesson 2 turns that model into a safe fixture-driven workflow so you can observe state transitions without requiring an enterprise IdP.

Official references and version notes

• Sonatype: Authentication and Realms.
• Sonatype: LDAP — bind/search, user/group mapping, LDAP cache, LDAPS trust.
• Sonatype: SAML — Pro-only browser SSO, metadata, ACS, signing, external role mapping.
• Sonatype: OpenID Connect — self-hosted Pro from 3.86, claim mapping, OAuth2 realm, truststore support.
• Sonatype: Security Management API — users, roles, privileges, realms and Pro OIDC configuration endpoints.
• Sonatype: Authentication Attempt Rate Limiting.
• Self-Hosted Nexus Repository Feature Matrix — LDAP Community/Pro; SAML and User Tokens Pro.
• Sonatype: Download and Java Runtime Compatibility Matrix.

Version-sensitive statements were rechecked on 2026-08-26. The current official direct-download page lists Nexus Repository 3.95.0. Nexus 3.87+ on H2/PostgreSQL requires Java 21. The mandatory learning path is Community-compatible and models external identity with local fixtures; SAML and OIDC are optional Pro-only integrations for self-hosted Nexus.