diff --git a/CODEOWNERS b/CODEOWNERS index afe62c4dc833fe42d51c57581c36a1b1975ed41c..3cd0a7e15eae924a59ba1cfa07f2134b23d818d4 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,2 +1,2 @@ -#followup and see who else belongs here * @grant.duncklee +#* @anyone? diff --git a/README.md b/README.md index 7336c7b7c87cc8a4967ef1b9ad3fc8252de8d55e..f734a30d48793b489a7eaf8f8389fc34525bed3d 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,12 @@ -# Sonatype Nexus Repository Manager (NXRM) +# Sonatype Nexus Repository Manager (NXRM) Documentation -Source of truth for components, artifacts, binaries, etc. - -This chart was sourced from [Sonatype's Helm Charts.](https://github.com/sonatype/helm3-charts) with minimal changes. - -## Prerequisites -- Kubernetes Cluster deployed -- Kubernetes config installed in ~/.kube/config -- Helm installed -- Keycloak (Optional - SSO) -- Sonatype NXRM License. Required for SAML integration +## Table of Contents +- [NXRM SSO Integration](docs/keycloak.md) +- [NXRM High Availability](docs/general.md#high-availability) +- [NXRM Storage](docs/general.md#storage) +- [NXRM Database](docs/general.md#database) +- [NXRM Dependent Packages](#nxrm-dependent-packages) +- [NXRM BigBang Caveats, Notes, etc.](#bigbang-additions-comments-and-important-information) ## Iron Bank You can `pull` the Iron Bank image [here](https://registry1.dso.mil/harbor/projects/3/repositories/sonatype%2Fnexus%2Fnexus) and view the container approval [here](https://ironbank.dso.mil/repomap/sonatype/nexus). @@ -21,17 +18,7 @@ Please reference complete list of providable variables [here](https://github.com git clone https://repo1.dso.mil/platform-one/big-bang/apps/developer-tools/nexus-repository-manager.git helm install nexus-repository-manager chart ``` - ## BigBang Additions, Comments, and Important Information -### SAML/SSO Integration -BigBang requires/prefers SAML/SSO integration out of the box; unfortunately, the upstream Helm chart did not have a -solution at the drafting of this integration. To achieve our goal, we added a Kubernetes job that handles the SAML/SSO -integration. To enable this functionality, ensure `sso.enabled` is set to `true`; you will additionally require a -Keycloak instance, the IDP metadata file, along with other parameters you may defined in `sso.idp_data`. Our -implementation closely follows the [Sonatype SAML Integration](https://support.sonatype.com/hc/en-us/articles/1500000976522-SAML-integration-for-Nexus-Repository-Manager-Pro-3-and-Nexus-IQ-Server-with-Keycloak) documentation. - -Retrieve a list of all available privileges: -`curl -X GET "https://{{ base_url }}/service/rest/v1/security/privileges" -H "accept: application/json"` ### Random Admin Password NXRM's upstream chart ships with a standardized password and an optional values parameter to randomize a password. The @@ -61,3 +48,6 @@ We expect you to secure your license; the license will be provided as a binary. encoded string, secure with sops, and place in `.Values.addons.nexusRepositoryManager.license_key`. The `_helpers.tpl` will create a named template and generate the appropriate secret within the namespace. The chart will reference the license via a secret volumeMount to ensure the application starts licensed. + +### NXRM Dependent Packages +Nexus IQ Server requires Nexus Repository Manager. diff --git a/docs/README.md b/docs/README.md index d1458642aa25001822e301530c6a3a96c6506bf2..7336c7b7c87cc8a4967ef1b9ad3fc8252de8d55e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,12 +1,63 @@ -# Nexus Artifact Repository Pro Docs +# Sonatype Nexus Repository Manager (NXRM) -## Usage +Source of truth for components, artifacts, binaries, etc. -### Prerequisites +This chart was sourced from [Sonatype's Helm Charts.](https://github.com/sonatype/helm3-charts) with minimal changes. -### Deployment +## Prerequisites +- Kubernetes Cluster deployed +- Kubernetes config installed in ~/.kube/config +- Helm installed +- Keycloak (Optional - SSO) +- Sonatype NXRM License. Required for SAML integration -### Nexus Post Install Configuration Notes +## Iron Bank +You can `pull` the Iron Bank image [here](https://registry1.dso.mil/harbor/projects/3/repositories/sonatype%2Fnexus%2Fnexus) and view the container approval [here](https://ironbank.dso.mil/repomap/sonatype/nexus). -#### Allow SSO login +## Helm +Please reference complete list of providable variables [here](https://github.com/sonatype/helm3-charts/tree/master/charts/nexus-repository-manager#configuration) +```bash +git clone https://repo1.dso.mil/platform-one/big-bang/apps/developer-tools/nexus-repository-manager.git +helm install nexus-repository-manager chart +``` + +## BigBang Additions, Comments, and Important Information +### SAML/SSO Integration +BigBang requires/prefers SAML/SSO integration out of the box; unfortunately, the upstream Helm chart did not have a +solution at the drafting of this integration. To achieve our goal, we added a Kubernetes job that handles the SAML/SSO +integration. To enable this functionality, ensure `sso.enabled` is set to `true`; you will additionally require a +Keycloak instance, the IDP metadata file, along with other parameters you may defined in `sso.idp_data`. Our +implementation closely follows the [Sonatype SAML Integration](https://support.sonatype.com/hc/en-us/articles/1500000976522-SAML-integration-for-Nexus-Repository-Manager-Pro-3-and-Nexus-IQ-Server-with-Keycloak) documentation. + +Retrieve a list of all available privileges: +`curl -X GET "https://{{ base_url }}/service/rest/v1/security/privileges" -H "accept: application/json"` + +### Random Admin Password +NXRM's upstream chart ships with a standardized password and an optional values parameter to randomize a password. The +problem with this approach it the user would be required to `exec` into the pod to retrieve the password. We are +leveraging the existing `nexus.env['NEXUS_SECURITY_RANDOMPASSWORD']` item to force the creation of the random password +on the pod. However, we are generating a random password via `randAlphaNum` and creating a Kubernetes secret. This +method allows us to overwrite the generated file containing the Nexus generated random password with a Kubernetes +secret to enable programmatic ingestion. + +Ensure the following is present to enable the randomized Kubernetes password: +```bash +# values.yaml +nexus: + env: + - name: NEXUS_SECURITY_RANDOMPASSWORD + key: "true" +... +secret: + enabled: true + mountPath: /nexus-data/admin.password + subPath: admin.password + readOnly: true +``` + +### License +We expect you to secure your license; the license will be provided as a binary. Encode the binary file as a base64 +encoded string, secure with sops, and place in `.Values.addons.nexusRepositoryManager.license_key`. The `_helpers.tpl` +will create a named template and generate the appropriate secret within the namespace. The chart will reference the +license via a secret volumeMount to ensure the application starts licensed. diff --git a/docs/general.md b/docs/general.md new file mode 100644 index 0000000000000000000000000000000000000000..c57c3bcdd657ed6ce013989c6e25a945335dcc97 --- /dev/null +++ b/docs/general.md @@ -0,0 +1,9 @@ +# NXRM Storage, Database, and High Availability + +## Storage + +### Blob Store + +## Database + +## High Availability diff --git a/docs/keycloak.md b/docs/keycloak.md new file mode 100644 index 0000000000000000000000000000000000000000..16ea7311d485b47a656a965dc82ca5937202875f --- /dev/null +++ b/docs/keycloak.md @@ -0,0 +1,75 @@ +# NXRM Keycloak Configuration + +**SAML/SSO integration is a *Pro* license feature.** + +BigBang requires/prefers SAML/SSO integration out of the box; unfortunately, the upstream Helm chart did not have a solution at the drafting of this integration. To achieve our goal, we added a Kubernetes job that handles the SAML/SSO integration as part of the NXRM Helm installation. To enable this functionality, ensure `sso.enabled` is set to `true`; you will additionally require a Keycloak instance, the IDP metadata file, along with other parameters you may define in `sso.idp_data`. + +Our implementation closely follows the [Sonatype SAML Integration](https://support.sonatype.com/hc/en-us/articles/1500000976522-SAML-integration-for-Nexus-Repository-Manager-Pro-3-and-Nexus-IQ-Server-with-Keycloak) documentation. + +## Download Keycloak IdP Metadata +1. Login to the Keycloak Admin Console i.e. /auth/admin/master/console/ +2. From the left-side menu, click on *Realm Settings*. +3. From the General tab, right-click on SAML 2.0 Identity Provider Metadata under the Endpoints field and save the link/file locally. This is the Keycloak IdP metadata that will be needed when configuring NXRM/IQ. + +## Configure Users and Groups in Keycloak +4. To add groups, via the left-side menu, under *Manage*, select *Groups* and then *New*. +5. In the next screen enter a group name and select *Save*. This will create a group that will be used for role mapping on the NXRM/IQ side. +6. To add users, via the left-side menu, under *Manage*, select *Users* and then *Add user*. +7. In the next screen, enter a *username*, First Name, Last Name* and *Email*, then click *Save*. +8. Once saved, the user will be created but will not have a default password set or be assigned to any groups. To set the password, click on the *Credentials* tab, set a password and click *Reset Password*. +9. To add the user to a group, click on the Groups tab and from the *Available Groups* field enter the name of the group created in Step 5 and click *Join*. + + +## NXRM Configuration +``` +# values.yaml +sso: + enabled: false + idp_data: + entityId: "{{ base_url }}/service/rest/v1/security/saml/metadata" + usernameAttribute: "username" + firstNameAttribute: "firstName" + lastNameAttribute: "lastName" + emailAttribute: "email" + groupsAttribute: "groups" + validateResponseSignature: true + validateAssertionSignature: true + idpMetadata: 'string' + realm: + - "NexusAuthenticatingRealm" + - "NexusAuthorizingRealm" + - "SamlRealm" + role: + id: "nexus" + name: "nexus" + description: "nexus group" + privileges: + - "nx-all" + roles: + - "nx-admin" + +# Retrieve a list of all available privileges: +# curl -X GET "https://{{ base_url }}/service/rest/v1/security/privileges" -H "accept: application/json" +``` + +10. Obtain a copy of the NXRM 3 SAML Metadata by opening the Entity ID URI i.e. /service/rest/v1/security/saml/metadata and saving the XML to file + +## Configure Keycloak - Client Config and Attribute Mapping +11. Further to configuring the NXRM/IQ side, to import the NXRM or IQ SAML metadata into Keycloak, via the Keycloak Admin Console select Clients from the left-side menu, then click *Create*. +12. In the Add Client screen, click *Select file* from the Import field, upload the NXRM or IQ SAML metadata that was obtained when configuring the NXRM/IQ side and click *Save*. +13. After saving, in the next screen, for the Client SAML Endpoint field, enter the Nexus instance*s Assertion Consumer Service (ACS) URL i.e. /saml for NXRM 3 or /saml for Nexus IQ Server and click *Save*. +14. If in the Configure Nexus Applications section, the *Validate Response Signature* and *Validate Assertion Signature* fields are set to "Default" or "True", then in the Clients → Settings tab ensure that the *Sign Documents* and *Sign Assertions* fields are enabled. + +Once the client has been created and the Client SAML Endpoint has been set, an attribute for each of the mappable fields that were configured in the Configure Nexus Applications section i.e. username, firstName, lastName, email and groups, will need to be created. + +15. To map an attribute, select the Mappers tab and then click on 'Create'. +16. Create a mapper for each of the mappable attributes with the values shown here: + + | Name | Mapper Type | Property | Friendly Name | SAML Attribute Name | SAML Attribute NameFormat | + |-------------|---------------|-----------|---------------|---------------------|---------------------------| + | username | User Property | username | username | username | Basic | + | First Name | User Property | firstName | firstName | firstName | Basic | + | Last Name | User Property | lastName | lastName | lastName | Basic | + | Email | User Property | email | email | email | Basic | + | Groups | Group list | groups | groups | *N/A* | Basic | +