diff --git a/text/0000-private-registry-auth.md b/text/0000-private-registry-auth.md new file mode 100644 index 00000000000..fd368b061b1 --- /dev/null +++ b/text/0000-private-registry-auth.md @@ -0,0 +1,130 @@ +- Feature Name: N/A +- Start Date: 2019-07-05 +- RFC PR: [rust-lang/rfcs#2719](https://github.com/rust-lang/rfcs/pull/2719) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +The ability to authenticate for all requests on private registries is added. +This includes API requests, crate downloads, and index retrievals. +The global authentication is enabled in Cargo's configuration in a registry definition. + +# Motivation +[motivation]: #motivation + +Businesses with projects in Rust will need somewhere to keep their crates, and the current +implementation of custom registries only sends authentication at times when it is needed on +crates.io. There is no option to send the token when downloading crates or making other +API calls. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +If a custom registry is to be considered private, the registry can require +authentication on all requests. This can be enabled on the server side by +modifying the registry definition in the index: +```json +{ + "dl": "https://my-intranet.local/api/v1/crates", + "api": "https://my-intranet.local/", + "auth_required": true, + "token_url": "https://my-intranet.local/me" +} +``` + +This will cause Cargo to send the token obtained via `cargo login` to the +registry with all requests. If not specified, will default to `false`. +`cargo login` will prompt the user to obtain a token via the URL in `token_url` +if specified, otherwise the `api` URL plus `/me`. + +It is up to the registry to decide whether authentication should be required for +the Git index. If authentication is required, the registry should provide +instructions on how to authenticate with Git along with how to add the registry +to Cargo. + + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +The variable `auth_required` is a boolean that enables the sending of the token +in the `Authorization` header on all requests, including downloads and API +calls. This will be implemented with a check on any requests to the registry +that sends the header if this value is true. This value defaults to `false`. + +The `token_url` variable is used to tell Cargo where to direct the user to get +their token. If not specified, this will default to the value in `api` plus +`/me`. + + + +# Drawbacks +[drawbacks]: #drawbacks + +This is probably biased, but I know of no drawbacks. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +This design may not be the best design, so feedback is appreciated. + +Another considered design was to use a cargo plugin to proxy requests through a +local server that sends authentication with the server with requests. This +design was decided against due to concerns about battery life, and the +requirement to ensure the proxy is running whenever it is required, meaning +possibly requiring a system service to keep it running. + +The impact of not doing this would be that large organizations would be hesitant +to use Rust for internal/confidential projects, so there would not be as many +large organizations supporting the growth of Rust. + + + +# Prior art +[prior-art]: #prior-art + +Many other languages have package managers with support for private +repositories. Not all will be listed here, but a select few as examples. + +- Python (Pio) +- .NET (NuGet) +- Java (Maven) +- JavaScript (npm) +- PHP (Composer) + + + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +- Currently the `Authorization` header does not use an auth scheme. This is + against standards. [rust-lang/cargo#4989](https://github.com/rust-lang/cargo/issues/4989) + has been opened because of this. It is undecided whether to include a fix for + this in this RFC or another. This would be a breaking change if not + implemented right. + +# Future possibilities +[future-possibilities]: #future-possibilities + +Possibly allowing non-Git indices, but it appears to be a large amount of work, +so it is not vital to this RFC.