LDAP, SAML, OIDC, External Identity, Credential Rotation, and Authentication Troubleshooting: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic sequence: identify the layer before changing state

1. Preserve concise client/browser status, timestamp, username source, request URL, and correlation clues.
2. Confirm Nexus version, edition/license, Java runtime, and whether the intended feature exists.
3. Confirm client mode: browser SSO, Basic/token client, or local account.
4. Inspect active realms and username-collision risk. Confirm the local recovery identity still works before changing external realm state.
5. Inspect the external connection: DNS/TLS/proxy, then protocol-specific endpoint.
6. For LDAP: bind → user search → group search/membership → external mapping.
7. For SAML/OIDC: redirect → assertion/token validation → subject/claim mapping → external mapping.
8. Inspect Nexus roles/privileges only after identity is proven.
9. Inspect authentication/security logs and rate-limit evidence.
10. Apply the smallest controlled correction, then retest one request.

2. LDAP: “bind works” is not “user works”

Current Nexus caches LDAP authentication information. If a corrected directory state appears stale, use the supported LDAP cache control rather than deleting files or restarting unrelated services blindly.

3. SAML: browser success has several checkpoints

A user can authenticate successfully at the IdP and still fail Nexus SSO. Check Entity ID/audience, ACS recipient/destination, signature validity, attribute names, groups, and browser cookie state. Since 3.89.0-09, Nexus SAML login requires the SAML2_AUTH_REQUEST cookie to complete the flow.

IdP authentication: SUCCESS
Assertion audience: https://old-nexus.example.invalid/service/rest/v1/security/saml/metadata
Expected Nexus base: https://nexus.example.invalid
ACS recipient: https://nexus.example.invalid/saml
SAML2_AUTH_REQUEST cookie: missing
Groups attribute: nexus-academy-readers
Result: login cannot be completed

Do not “repair” this by granting the user a repository role. The failure occurs before authorization. Compare the current Nexus SP metadata with the IdP registration, preserve the intended base URL, and test in a private browser after cookie/proxy corrections.

4. OIDC: validate issuer, redirect, keys, then claims

Never log raw access tokens or client secrets to an evidence packet. A claim-name inventory and token header metadata are usually enough for mapping diagnosis.

5. Rotated secret or certificate not deployed

Rotation incidents often look like network failures because authentication suddenly stops at a known cutover time. Compare timestamps with the change record. For an LDAP bind password, prove the service account works with the new secret and that Nexus was updated. For SAML signing keys, confirm new IdP metadata/signing certificate. For OIDC client-secret rotation, confirm both provider and Nexus hold the same active secret.

Certificate changes must be distinguished from hostname verification. Importing a CA cannot fix a certificate issued to the wrong host. Likewise, changing reverse-proxy headers cannot fix a bad OIDC issuer.

6. Authentication rate limiting is not a network outage

Current Nexus authentication attempt rate limiting is enabled by default. The documented defaults are three consecutive failures, a 30-second base delay, and a maximum delay of 900 seconds. When throttled, Nexus returns 429 Too Many Requests with Retry-After. It applies to Basic and token-based authentication; SAML SSO login attempts are handled by the IdP instead.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{"message":"Authentication attempts are temporarily rate limited"}

The wrong response is to restart Nexus or change firewall rules. Preserve the 429, stop retry storms, wait the indicated interval, fix the bad credential, then make one controlled request.

7. Authentication success can still produce authorization failure

A 403 after successful login is usually an authorization question: external group changed, role mapping is stale/wrong, group name differs in case, or the mapped Nexus role lacks the required privilege. Return to the Chapter 14 matrix: test the exact repository/path/action and inspect every role that can grant it.

8. Performance boundaries

9. Minimal incident evidence packet

• timestamp + Nexus version/edition/runtime;
• active realm IDs/order;
• caller type: browser, Basic/token package client, local account;
• non-secret endpoint/issuer/entity IDs;
• LDAP stage reached: connect, bind, user search, group search;
• SAML/OIDC stage reached: redirect, validation, claims, mapping;
• HTTP status including 401/403/429 and Retry-After if present;
• mapped role IDs/privilege IDs;
• certificate fingerprints, not private keys;
• the one correction applied and controlled retest.

10. Knowledge check

11. Next step

Lesson 5 combines the model into one operator checkpoint: a synthetic LDAP integration, exact external group mapping, fake bind-secret rotation, three independent authentication failures, recovery-path verification, and cleanup.

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.