Single Sign-On patch for Nexus OSS

Patch for Nexus OSS with authorization via SSO and tokens. By default this features available only in PRO version (see comparison), but this patch provides them an alternative implementation without violating the license.

Solution implement as Docker container (based on official image with SSO patch applied) and compose.yml config with Nginx. Example of usage:

# Clone configuration and change to working directory
git clone https://github.com/a-langer/nexus-sso.git
cd ./nexus-sso
# Copy compose.override.yml from template for you settings
cp _compose.override.yml compose.override.yml
# Set environment variables for container user
export NEXUS_USER=$(id -u) NEXUS_GROUP=$(id -g)
# Run service and open http://localhost in web browser
docker compose up -d

Supported features and examples of usage

List of features this patch adds:

• SAML/SSO - authentication via Single Sign-On (SSO) using a SAML identity provider such as Keycloak, Okta, ADFS and others. Nexus uses access system based on Apache Shiro, this patch extends it with a Pac4j and buji-pac4j libraries, which can be configured with shiro.ini (see SAML.md and documentation of Apache Shiro and Pac4j for more detail informations). SSO users are created as internal Nexus accounts the first time they sign-in and are updated every next time. Example of usage SSO:

  • Go to menu "Sign in", press to button "Sign in with SSO".
  • You will be redirected to the login page of identity provider.
  • Type you credentials (login, password, 2FA, etc.).
  • You will be redirected to the main page of Nexus, roles and permissions will be mapped with your account as configured.

• User Auth Tokens - are applied when security policies do not allow the users password to be used, such as for storing in plain text (in settings Docker, Maven and etc.) or combined with SAML/SSO. Each user can set a personal token that can be used instead of a password. The creation of tokens is implemented through the "NuGet API Key" menu (privilegies nx-apikey-all required), however, the tokens themselves apply to all types of repositories.

  NOTE: For SSO and user tokens, it is enough to have two realms: "Local Authenticating Realm" and "Local Authorizing Realm". Other realms are not required and may lead to conflicts.

  Example of usage user token:

  • Go to menu "Nexus -> Manage your user account -> NuGet API Key", press "Access API key".

  • Type your username if using SSO login, otherwise type password, then press "Authenticate".

  • Copy "Your NuGet API Key", press "Close" and "Sign out".

  • To validate a token: press "Sign in", type your username and token instead of password.

  • Also, a pair of username+token can be used for authorization in Maven, Docker, Pip, etc., example for HTTP api:

    # Authorization header for basic:
    Basic <login:token in base64>

• Docker Repository Reverse Proxy - this Nginx configuration implements a proxy strategy to use Docker registries without additional ports or hostnames (while the official documentation only suggests two proxy strategies: "Port Mapping" and "Host Mapping"). To apply the proxy strategy, required pre-configuration of Nexus (see gistcomment-4188452):

  • After deployment, three Docker registries need to be created:

    • docker-login - uses to check authorization, it is recommended to choose type "group" containing registry "proxy" for "hub.docker.com". To allow anonymous access, enable "Allow anonymous docker pull".
    • docker-group - choose type "group", uses to look up images in docker registries. CLI searches will be performed on all registries added to this group (assuming the user has read permissions or the "Allow anonymous docker pull" option is enabled).
    • docker-root (optional) - is used to pull an image from the Docker registry hosted in the Nexus root, i.e. without a given repository name. Can be of any type, for host your own images required the "hosted" type. Image names in this repository must not contain a slash (for example, myhost/myimage:latest).

  • After authorization, working with docker registries is controlled by Nexus permissions. For example, if you don't give a user permission to write to the "super-secret-docker-hosted-repo" registry, they can log in, but they can't push images to that registry.

  • Example of usage for host "https://nexus_host" and registry "my-hosted-registry":

    # Download an image "alpine" from a public registry
    docker pull alpine:latest
    # Change tag of image "alpine"
    docker tag alpine:latest nexus_host/my-hosted-registry/alpine:latest
    # Log in to the local registry
    docker login nexus_host -u $username -p $password_or_token
    # Pushing image "alpine" to registry "my-hosted-registry"
    docker push nexus_host/my-hosted-registry/alpine:latest
    # Search image "alpine" in hosted registry "my-hosted-registry"
    docker search nexus_host/my-hosted-registry/alpine:latest
    # Pulling image "alpine" from hosted registry "my-hosted-registry"
    docker pull nexus_host/my-hosted-registry/alpine:latest

• OrientDB studio - web interface to interact with an embedded database, will available at the URL http://localhost:2480/studio/index.html if run service with profile "debug" (does not start by default):

  docker compose --profile debug up

• Non-transitive privileges in group repositories - by default group repository privileges in Nexus are transitive (all or nothing), this property enables mode of non-transitive privileges (only what is allowed):

  nexus.group.nontransitive.privileges.enabled=true

  Note that:

  • It is sufficient for a user to have the "browse" or "read" privilege (either one) to read files from the repository.
  • Privileges must be granted to the repository itself and to the group repository in which it is a member.

Additional settings (tips and tricks)

• Docker compose configuration may be extended with compose.override.yml (for example, pass additional files to the container).

• SAML/SSO authentication may be configured with environment variables in .env file, for more flexible settings, can make changes directly to shiro.ini (variable interpolation supported). However, this also requires that the configuration files of service provider (ex., sp-metadata.xml) and identity provider (ex., metadata-okta.xml or metadata-keycloak.xml) will be passed to the container. Examples of creating SAML configurations see in "Keycloak SAML integration with Nexus application" (except "Configure Sonatype Platform", instead follow SAML.md).

• Nginx SSL is pre-configured, to enable it, need copy file _ssl.conf to ssl.conf and pass to directory ${NEXUS_ETC}/nginx/tls/ two files:

  • site.crt - PEM certificate of domain name.
  • site.key - key for certificate.

• UrlRewriteFilter is used to route HTTP requests within the application and can be further configured using urlrewrite.xml (for example override or protect API endpoint). Status of UrlRewriteFilter available in http://localhost:8081/rewrite-status. Also it supports hot-reload, to apply the any settings without restarting the container, run the command:

  docker compose exec -- nexus curl -sSfkI http://localhost:8081/rewrite-status/?conf=etc/sso/config/urlrewrite.xml

  NOTE: Hot-reload not working for environment variables defined in .env, this changes take effect only after the container is restarted.

Development environment

Need installed Maven and Docker:

1. Change Nexus version if update required (see Release Notes for more information), ex.:

   # Set version of the current project and any child modules
   mvn versions:set -DnewVersion=3.46.0

2. Execute assembly commands:

   # Build docker image
   mvn clean install -PbuildImage
   # Or build only jar bundle if needed
   mvn clean package

3. Run docker container and test it:

   # Run service and open http://localhost in web browser
   docker compose down && docker compose up

4. Accept or revert modifications to the pom.xml files:

   # Accept modifications
   mvn versions:commit
   # Or revert modifications and rebuild docker image
   mvn versions:revert && mvn clean install -PbuildImage