This plugin adds a Keycloak realm to Sonatype Nexus OSS and enables you to authenticate with Keycloak Realm Users and authorize with Keycloak realm/client roles or groups.
It works with Nexus 3.x and Keycloak 3.x ~ 14.x.
- Supports to map the Realm-Roles, Client-Roles and Realm-Groups of Keycloak.
- Supports to map multiple Keycloak realms.
- Supports to login with the Service Account of Keycloak.
- Supports Keycloak Single Sign On (SSO): sign-in and sign-out are all supported.
If you are using the version 0.2.x of this plugin, and want to upgrade the plugin to 0.3.x, you should create some new roles in Nexus3, because the new version of the plugin supports to map the Realm-Roles, Client-Roles and Realm-Groups of Keycloak to the Nexus3 roles.
But don't worry about your data or the existing role-mappings, they will still work well.
The latest version of the plugin is compatible with the old version.
In the new version, the original Keycloak role/group name will be prepended with
RealmRole: (If it's a Realm-Role), ClientRole: (If it's a Client-Role) or RealmGroup: (If it's a Realm-Group).
If something goes wrong when you upgraded the plugin to the new version. DO NOT save or update your configurations again, just go back to the old version and restart Nexus3, then create an issue to report your problem.
Read the details in develop/README.md.
- JDK 8+ is installed
- Apache Maven is installed
- Sonatype Nexus OSS 3.x is installed
When Nexus gets downloaded and unzipped, there are typically two directories created:
- nexus-3.3.2-02
- sonatype-work/nexus3
To avoid confusion, the conventions of the Sonatype reference will be used in the following descriptions:
- nexus-3.3.2-02 will be referred to as $install_dir
- sonatype-work/nexus3 will be referred to as $data_dir
See https://help.sonatype.com/repomanager3/installation/directories for reference.
Build and install the into your local maven repository using the following commands:
git clone https://github.com/flytreeleft/nexus3-keycloak-plugin.git
cd nexus3-keycloak-plugin
mvn clean install -Dmaven.test.skip=true
Note: You can download the compiled jar from the release page directly, just choose the latest version.
PLUGIN_VERSION=0.6.0-SNAPSHOT
jars="org/github/flytreeleft/nexus3-keycloak-plugin/$PLUGIN_VERSION/nexus3-keycloak-plugin-$PLUGIN_VERSION.jar"
for jar in $(echo $jars | sed 's/ /\n/g'); do
mkdir -p $install_dir/system/$(dirname $jar)
cp ~/.m2/repository/$jar $install_dir/system/$jar
done
Append the following line to startup.properties file found in $install_dir/etc/karaf.
Please replace [PLUGIN_VERSION] by the current plugin version.
mvn\:org.github.flytreeleft/nexus3-keycloak-plugin/[PLUGIN_VERSION] = 200
Or running the following command to do that automatically:
echo "mvn\\:org.github.flytreeleft/nexus3-keycloak-plugin/$PLUGIN_VERSION = 200" >> $install_dir/etc/karaf/startup.properties
From the plugin version 0.4.0-SNAPSHOT, it supports to build a new bundle format
KAR
which helps us no need to specify the plugin path in startup.properties for Nexus v3.15+.
If you are using Nexus v3.15+ and want to use KAR bundle, just run
mvn -PbuildKar clean install -Dmaven.test.skip=true, and it will build two packages
nexus3-keycloak-plugin-<version>-bundle.kar and nexus3-keycloak-plugin-<version>.jar.
Then just put the *.kar into the directory $install_dir/deploy/, and there is no need
to change startup.properties anymore.
Note:
- The
*.karfile can be downloaded from the release page. - The
*.jarfile can be used for Nexus v3.14 and earlier directly.
Login to your Keycloak, and navigate to "[Choose your realm] -> Clients -> [Choose the existing client or create a new client, e.g. 'nexus3']".
Activate the Settings tab, choose confidential for Access Type,
then enable Service Accounts Enabled and Authorization Enabled,
click Save button to make configuration effective.
Then Activate the Service Account Roles tab, choose realm-management for Client Roles,
then select view-realm, view-clients and view-users in Available Roles,
click Add selected button to add them to Assigned Roles.
Create a keycloak.json file in $install_dir/etc.
Login to your Keycloak, and navigate to "[Choose your realm] -> Clients -> nexus3 -> Installation -> [Choose 'Keycloak OIDC JSON' option]".
Copy the json content to $install_dir/etc/keycloak.json:
echo '{
"realm": "default",
"auth-server-url": "http://localhost:8080/auth",
"ssl-required": "external",
"resource": "nexus3",
"credentials": {
"secret": "a203feab-4bcf-4e73-b66e-05adc1da0da6"
},
"policy-enforcer": {}
}' > $install_dir/etc/keycloak.json
After installation you have to activate the plugin in the administration frontend. You have to login with an administrative nexus account to do so. The default admin credentials are
- username: admin
- password: admin123 (don't forget to change it!)
After login you can navigate to the realm administration.
Activate the Keycloak Authentication Realm plugin by dragging it to the right hand side.
As a last step you have to map your Keycloak realm client roles to nexus internal roles.
A good starting point is mapping one Keycloak realm client role to nx-admin role, so you can start managing Nexus with your Keycloak Login.
- Choose a Keycloak realm client role (once the plugin is enabled you can check what keycloak roles are assigned to user using the Log Viewer)
- Think up a new unique name for the mapped role
- Add nx-admin to the contained roles
That's it. Now you can login your keycloak account.
Move into your $install_dir. Edit the file bin/nexus.vmoptions to contain the following line
-Dkaraf.startLocalConsole=true
After that (re-)start nexus. It will then startup with an interactive console enabled. (If the console doesn't show up, you may hit the Enter key after startup). Your console should look like this afterwards:
karaf@root()>
Within the console just type
bundle:install -s file://[ABSOLUTE_PATH_TO_YOUR_JAR]
From the version 0.3.3, the plugin supports multiple Keycloak realms. You can map at least 4 different Keycloak realms' roles/groups to Nexus3.
If you want to enable this feature, just export the Keycloak OIDC JSON from the Keycloak realm to the file $install_dir/etc/keycloak.{index}.json,
and the {index} is a number which can be 0, 1 or 2.
Then, enable the corresponding Keycloak authentication realm in Nexus3:
Finally, you just need to map the new realm roles/groups to Nexus3 as the default one.
From the plugin version 0.3.4, you can login Nexus3 using Keycloak as SSO (Single Sign On) provider.
Before enable SSO, you need to put a reverse gateway (Nginx, Httpd etc.) before your Nexus3 server.
Then, the reverse gateway should do authentication via Keycloak and pass the HTTP header
X-Keycloak-Sec-Auth: <username>:<auth token> to your Nexus3 server.
You also can pass username and auth token via the HTTP header
X-Auth-Username: <username>andX-Auth-Token: <auth token>from the plugin version 0.4.0.
You can check the code of develop/nginx-gateway/vhost.d/nexus3.conf for more details.
Note, if you login as Administrator, and refresh the administration page, you will see the 'Sign in' window:
Don't worry about it, you still login, just close the window.
Note: After you login, you can click the logout button to logout and it will redirect to the Keycloak login page.
You can execute command bash docker/build.sh to build your Nexus3 Docker image with this plugin.
The image is based on https://github.com/sonatype/docker-nexus3 which is running Nexus v3.19.1-01.
You can change the version of the base image or the version of this plugin in docker/Dockerfile.
After the image has been built, you should prepare your keycloak.json
and put it into the directory docker/, then execute command bash docker/run.sh to create and run a Nexus3 container.
If you want to change the default port/volume mappings, just edit docker/run.sh before running the container.
Thanks to all contributors who helped to get this up and running.