# Global configuration

URL: https://edu.chainguard.dev/chainguard/libraries/dotnet/global-configuration.md
Last Modified: September 30, 2026
Tags: Chainguard Libraries, .NET

Configuring Chainguard Libraries for .NET in your organization


.NET package consumption in a large organization is typically managed by a repository manager. The repository manager acts as a single point of access for developers and development tools to retrieve NuGet packages.

This page describes how to configure [JFrog Artifactory](https://jfrog.com/artifactory/) and [Sonatype Nexus Repository](https://www.sonatype.com/products/sonatype-nexus-repository) to proxy Chainguard Libraries for .NET. The instructions use Chainguard Repository's built-in upstream fallback, which is the recommended configuration.

With upstream fallback enabled, configure Artifactory with a single remote repository that points to the Chainguard NuGet v3 service index: `https://libraries.cgr.dev/dotnet/v3/index.json`.

Chainguard Repository handles upstream fallback and policy enforcement. Artifactory handles local caching, access control, and the endpoint used by your NuGet clients. Do not add a direct `nuget.org` remote to the virtual repository used by your builds unless you intentionally want to manage fallback yourself.

## Prerequisites

Before you begin, you need:

- An [entitlement to Chainguard Libraries for .NET](/chainguard/libraries/dotnet/migration/#create-an-entitlement)
- Administrator access to your repository manager instance
- A [pull token for Chainguard Libraries for .NET](/chainguard/libraries/dotnet/migration/#create-a-pull-token)

## JFrog Artifactory

JFrog Artifactory supports NuGet repositories for proxying packages and virtual repositories for combining repositories behind a single endpoint.

The following configuration uses the recommended upstream-fallback approach. A remote repository that points directly to nuget.org can bypass Chainguard Repository protections. Because Artifactory resolves packages through a virtual repository, a misplaced or incorrectly ordered remote can result in an unprotected package being served without an obvious build error.

### Initial configuration

Use the following steps to add Chainguard Libraries for .NET as an Artifactory remote repository:

1. Sign in to Artifactory as a user with administrator privileges.
1. Click **Administration** in the top navigation bar.
1. In the left navigation, click **Repositories**.
1. Click **Create a Repository**, then choose **Remote**.
1. Configure the remote repository with the following values:
    - **Package type**: NuGet
    - **Repository key**: `dotnet-chainguard`
    - **URL**: `https://libraries.cgr.dev/dotnet/v3/index.json`
    - **Username**: the username returned by `chainctl`
    - **Password**: the password returned by `chainctl`
1. Open the **Advanced configuration** tab and configure the following:
    - In the **Network** section, confirm that **Lenient Host Authentication** is unchecked. This prevents Artifactory from forwarding credentials across a redirect.
    - Optionally select **Enable Cookie Management**. JFrog recommends this for remote repositories that use redirects.
    - In the **Others** section, select **Bypass HEAD Requests** so that Artifactory retrieves package files with GET requests instead of probing with HEAD requests first.
    - In the **Others** section, uncheck **Block Mismatching Mime Types**.
    - Select **Disable URL Normalization** so that Artifactory does not rewrite a pre-signed redirect URL.
1. Click **Create Remote Repository**.

These settings are required because Chainguard Libraries stores artifacts behind redirects to pre-signed URLs. Without them, Artifactory may rewrite the redirect, forward credentials to the redirected host, or cache the redirect response instead of the NuGet package.

### Create a virtual repository

Create a virtual repository to give NuGet clients a single access point:

1. Click **Create a Repository**, then choose **Virtual**.
1. Configure the virtual repository with the following values:
    - **Package type**: NuGet
    - **Repository Key**: `dotnet-all`
    - **Repositories**: add `dotnet-chainguard`
1. Click **Create Virtual Repository**.

For the recommended configuration, `dotnet-chainguard` should be the only external upstream in `dotnet-all`. You can also add approved internal NuGet repositories to the virtual repository according to your organization's access-control requirements.

### Validate the remote repository

Validate the Artifactory remote before configuring developer workstations or CI/CD systems. The Artifactory **Test** button is not a reliable indicator of a working Chainguard configuration; a remote can pass the test but still be misconfigured for package retrieval.

- Confirm that the remote repository URL is `https://libraries.cgr.dev/dotnet/v3/index.json`.
- Confirm that the remote uses the current .NET pull-token username and password. Confirm that the token is not expired and was copied correctly.
- Confirm that the [Advanced configuration settings](#initial-configuration) are applied.
- Clear any previously cached test content from `dotnet-chainguard` if the repository was configured with different settings.
- Create or use a test .NET project that references a package available from Chainguard Libraries.
- Configure the test project to use the Artifactory virtual repository, then clear the NuGet HTTP cache:

```bash
 dotnet nuget locals all --clear
 ```

- Force a network restore:

 ```bash
 dotnet restore --force --no-cache --verbosity normal
```

- Inspect `obj/project.assets.json`. The `sources` entry must contain the Artifactory `dotnet-all` URL, and must not contain `nuget.org`.
- In Artifactory, confirm that the package is present in the `dotnet-chainguard` remote cache and that the request is available through the `dotnet-all` virtual repository.

### Configure build tools

After validation, configure each workstation and build server that restores .NET dependencies, including CI/CD infrastructure, to use the Artifactory virtual repository.

In Artifactory, select the `dotnet-all` virtual repository and use **Set Me Up** or **Generate Settings** to obtain the URL and authentication instructions for your Artifactory version. The URL commonly has the following form: `https://<artifactory-host>/artifactory/api/nuget/dotnet-all`

See [Configuring your build tool](/chainguard/libraries/dotnet/build-configuration/#repository-manager) for more information.

<a id="nexus"></a>

## Sonatype Nexus Repository

[Sonatype Nexus
Repository](https://www.sonatype.com/products/sonatype-nexus-repository) allows
for merging multiple remote repositories as a repository group. The following
instructions are based on the [Nexus documentation for
NuGet](https://help.sonatype.com/en/nuget-repositories.html).

The recommended approach is to rely on Chainguard Repository's [upstream
fallback](/chainguard/libraries/introduction/overview/#upstream-fallback-and-controls),
configuring a single proxy repository pointed at the Chainguard NuGet v3 service
index rather than adding a separate nuget.org proxy. A proxy that points
directly to nuget.org can bypass Chainguard Repository protections.

### Initial configuration

The following steps create a proxy repository for Chainguard Libraries for .NET
and a repository group that exposes it to your build tools.

First, log in to Sonatype Nexus as a user with administrator privileges and
access the **Server administration** and configuration section with the gear
icon in the top navigation bar.

Next, configure a proxy repository for the Chainguard Libraries for .NET
repository:

1. Select **Repository - Repositories** in the left hand navigation.
1. Click **Create repository**.
1. Select the **nuget (proxy)** recipe.
1. Configure the following:
    - **Name**: `dotnet-chainguard`
    - **Protocol Version**: `NuGet V3`
    - **Proxy - Remote storage**: Add the URL
   `https://libraries.cgr.dev/dotnet/v3/index.json`.
    - **HTTP - Authentication**: Select `Username` as the Authentication type,
   and provide the [username and password values as retrieved with
   chainctl](/chainguard/libraries/introduction/access/).
1. Click **Create repository**.

Create a repository group, or add to an existing repository group:

1. Select **Repository - Repositories** in the left hand navigation.
1. Click **Create repository**.
1. Select the **nuget (group)** recipe.
1. Configure the following:
    - **Name**: `dotnet-all`
    - Under **Group - Member repositories**, move the new repository
   `dotnet-chainguard` to the right to include it in the group. Position
   `dotnet-chainguard` at the top of the list using the arrow controls.

In a typical configuration, the Chainguard repository is placed first so that
packages are retrieved through Chainguard when available. If you are manually
managing fallback, you can configure an additional nuget.org proxy repository
and add it to the group after `dotnet-chainguard`.

### Build tool access

NuGet v3 clients access a Nexus group through its service index, which commonly
has the form `https://repo.example.com/repository/dotnet-all/index.json` (with
`repo.example.com` replaced with the hostname of your repository manager).

See [Configuring your build
tool](/chainguard/libraries/dotnet/build-configuration/#repository-manager) for
information on setting the package source and authenticating to your repository
manager.