nexus-oidc-proxy

README

Nexus OIDC RBAC-Syncing Proxy

This server acts as a reverse proxy to add OIDC support to Nexus. Nexus supports this directly by allowing a header to be set indicating the user ID to log in as, to be provided by a reverse proxy such as this one. A number of other open-source tools already do this, however, they only implement authentication, not authorization. This requires the administrator to manually manage the set of users, and their granted roles, manually, which defeats the purpose of single sign-on.

This server is different, and instead intergates with OIDC in a way that will feel familiar to anyone that has used Harbor. This tool assumes another tool like OAuth2-Proxy is reverse proxying it to provide it the SSO access token, and then, translate that token into a Nexus API User object, and synchronize the Nexus user automatically on a configurable interval, as well as creating the user in the first place, in addition to reverse proxying each request. This allows for true integration with OIDC.

This tool is still in early development, and experimental. Everything is subject to change. Use at your own risk.

Building

Needed tools:

• Go 1.16+
• Docker (Or compatible OCI image builder tool) (if building docker image)
• Kubectl, Helm, Kind (For running integration tests)

# Executable
go build -o proxy main.go
# Docker image
docker build -t ${your_registry}/meln5674/nexus-oidc-proxy:$(git rev-parse HEAD)
docker push ${your_registry}/meln5674/nexus-oidc-proxy:$(git rev-parse HEAD)

Configuration

Configuration is set through a configuration file for non-sentive information, and environment variables for sensitive information

Configuration File

http:
  # Address and port to listen on
  address: <listen address>:<listen port>
  # Optional. Configuration for the token endpoint (see below)
  tokenEndpoint:
    path: Path to serve the token endpoint on
tls:
  # Set to true to serve using TLS (HTTPS)
  # Default false
  enabled: <true|false>
  # Path to your TLS certificate file
  certFile: </path/to/tls.crt>
  # Path to your TLS private key
  keyFile: </path/to/tls.key> 
nexus:
  # URL of the Upstream Nexus server
  upstream: http[s]://<nexus host>:<nexus port>[/<base path>]
  # The name of the header to set to the user ID in proxied requests 
  rutAuthHeader: <header name>
oidc:
  # How long to wait between synchronizing users/roles
  # See https://pkg.go.dev/time#ParseDuration for syntax
  syncInterval: <#(s|m|h|...)>
  # Name of the HTTP header to expect the downstream proxy to set to the JWT OIDC Access token 
  accessTokenHeader: <header name>
  # Golang template, see https://pkg.go.dev/text/template for xyntax 
  # Should produce a nexus user API object to onboard that user in YAML/JSON format
  # You will have access to Sprig functions (https://masterminds.github.io/sprig/)
  # You will have access to https://pkg.go.dev/github.com/golang-jwt/jwt/v4#Token as the .Token variable
  userTemplate: |-
    <template>
  # List of Golang templates, see https://pkg.go.dev/text/template for xyntax 
  # Each output should be a YAML list/JSON array of strings, each string being a valid nexus role name
  # You will have access to Sprig functions (https://masterminds.github.io/sprig/)
  # You will have access to https://pkg.go.dev/github.com/golang-jwt/jwt/v4#Token as the .Token variable
  # Outputs will be set unioned
  roleTemplates:
  - |-
    <template>
  - ...
  # List of default roles to provide to a user which has no roles
  # generated by the userTemplate or any roleTemplates
  # This is required, as nexus will refuse to create a user with no roles.
  # It is recommended to set this to nx-anonymous, since that will result in a user with no
  # roles being treated as if they hadn't logged in at all
  defaultRoles:
  - ...

Environment Variables

NEXUS_OIDC_PROXY_NEXUS_USERNAME

Username to use for onboarding and synchronizing users.

NEXUS_OIDC_PROXY_NEXUS_PASSWORD

Password to use for onboarding and synchronizing users.

Command Line Arguments

--config

Specify path the configuration file described above

Trusted Certificates

If your Nexus server uses a self-signed certificate or uses an internal CA, this application is written in Go and uses the standard locations for finding CA Certificate Bundles. Add your self-signed certificate or internal CA to one of these bundles to have this server trust your Nexus server.

Permissions

This application requires the following Nexus permissions to operate correctly:

• nx-users-create
• nx-users-read
• nx-users-update
• nx-userschangepw

Nexus Setup

In addition to providing credentials, you must enable the Remote User Token (RUT) capability and Auth Realm. See here for instructions on doing this.

This tool only requires the OSS version of Nexus, it does not require any features from Pro or above.

Deploying

It is recommended to deploy this tool containerized, in a Kubernetes Cluster. A Dockerfile and Helm chart are provided for doing so. See here for an example.

Nexus Passwords

Nexus still has the ability to log in via user passwords with this tool deployed behind OIDC. As such, it can be useful to think of these local passwords as "tokens" for use with a separate interface that does not use OIDC. This can be used, for example, as the password for downloading private maven or pip artifacats using an automated tool.

To simplify the management of this, the proxy includes an optional endpoint. This endpoint, when visited, provides a bare-bones web form to generate a new "token", which is set as the user's password.

Running Tests

./integration-test/run.sh