Skip to content

Commit 8a1a03e

Browse files
authored
Remove jargon from the credential management page
Users will need to follow this procedure when getting a namespace in the OSDF. De-jargon this to make it sound less imposing.
1 parent fc194ec commit 8a1a03e

File tree

1 file changed

+46
-11
lines changed

1 file changed

+46
-11
lines changed

docs/pages/advanced-usage/server.mdx

Lines changed: 46 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,28 @@
1-
# Advanced Usage - Servers
1+
# Managing Administrator Credentials
22

3-
This page documents advanced usage of Pelican servers. Features listed below are for server admins familiar with Pelican Servers.
3+
Pelican services maintain multiple types of credentials:
4+
- The *admin password* provides access to the server's web interface.
5+
- The *namespace private key* can create arbitrary new credentials (user tokens) for a portion of the federation's namespace.
46

5-
## Pre-generate Server Credentials
7+
This page covers various topics in managing these credentials.
68

7-
### Server Private Key
9+
## Pre-generate Credentials
810

9-
> **Note**: The server private key should be treated as a **secret** and never shared with the public.
11+
### Namespace Private Key
1012

11-
Pelican servers rely on an ECDSA key-pair for signing and verifying tokens used in API requests and object accesses. Pelican servers automatically generate a private key in ECDSA form at the server start, and provide the public key through the OIDC-style discovery endpoint at `/.well-known/openid-configuration`. The public key is useful for various things including Origin namespace prefix registration at the registry (see details [here](../federating-your-data.mdx#obtain-the-public-key-of-the-origin)).
13+
> **Note**: The namespace private key is a **powerful secret** and should never be shared with others. With the private key, one can create user credentials the can arbitrary read or write into your namespace.
1214
13-
In deployment, it can be convenient to generate the key-pair in advance and mount the private key file to the Pelican server via configuration variable, especially in a container environment. The Pelican CLI comes with a command `pelican generate keygen` for generating private/public key pairs:
15+
Pelican services rely on a private/public key pair for creating (signing) and verifying the user credentials (tokens) used to read or write objects. When a new prefix in the data federation is created, an associated public key must be provided; the corresponding private key can generate any arbitrary permissions (including delete!) within the namespace. For more information about namespace registration, see details [here](../federating-your-data.mdx#obtain-the-public-key-of-the-origin).
16+
17+
When a Pelican origin or other service is started, the server automatically generates a new private key if one is not present. However, if someone is running the origin on your behalf, you will need to generate the keypair on your own and send the public portion to the operator. If you're doing the deployment, it can also be convenient to generate the key-pair in advance and mount the private key file to the Pelican server via configuration variable, especially in a container environment.
18+
19+
The Pelican binary ships with a `pelican generate keygen` for generating a private/public key pairs:
1420

1521
```bash copy
1622
pelican generate keygen
1723
```
1824

19-
and Pelican will generate both the private key and the public key under the current working directory:
25+
Pelican will generate both the private key and the public key under the current working directory:
2026

2127
```console
2228
Successfully generated keys at:
@@ -31,17 +37,46 @@ You can change the location of the generated keys by passing in arguments `priv
3137
pelican generate keygen --private-key /tmp/foo --public-key /tmp/bar
3238
```
3339

34-
The generated *private key* can be passed to a Pelican server via `IssuerKey` configuration parameter so that the server will take advantage of the generated key instead of generating a new key.
40+
For operators, the generated *private key* can be specified in the a Pelican server configuration via the `IssuerKey` parameter so that the server will use the newly-generated key:
3541

3642

3743
```yaml filename="pelican.yaml" copy
3844
IssuerKey: /path/to/generated/issuer.jwk
3945
```
4046
47+
If there is a remote operator for your origin, email them the **public key** portion. Never send anyone your private key. A sample public key looks like the following:
48+
49+
```bash
50+
$ cat issuer-pub.jwks
51+
{
52+
"keys": [
53+
{
54+
"alg": "ES256",
55+
"crv": "P-256",
56+
"kid": "NDTks9H79ndG7bdzjjlQzV-fwwCrnXd_mcd_2D5ZvYE",
57+
"kty": "EC",
58+
"x": "9IIkGEzyWywecBsIisrJsH-_XqMal-U25dthHewUC5w",
59+
"y": "h_1DUotM2qnLPPRia6hGXNKZdpi92VJ5u_NSrZ-pd0c"
60+
}
61+
]
62+
}
63+
```
64+
65+
A sample private key has the following format:
66+
```bash
67+
$ cat issuer.jwk
68+
-----BEGIN PRIVATE KEY-----
69+
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgzeomqIyJvek0fg2Z
70+
g+NY6qklGz4ZjVlrRgTDT9hk5EShRANCAAT0giQYTPJbLB5wGwiKysmwf79eoxqX
71+
5Tbl22Ed7BQLnIf9Q1KLTNqpyzz0YmuoRlzSmXaYvdlSebvzUq2fqXdH
72+
-----END PRIVATE KEY-----
73+
```
74+
75+
### Web Interface Administrator Password
4176

42-
### Admin Website Password
77+
By default, Pelican's administrator web interface requires a username/password to be setup to access. This password can be enabled by a one-time passcode the server writes into the log file. However, by pre-generating the credential, Pelican server administrators can skip the initial setup and automate installation.
4378

44-
The `pelican generate` command generates the [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) password file for storing the admin website login password. By pre-generating the htpasswd file, Pelican server admin can skip the initial website setup with the one-time passcode. To generate a password file, run:
79+
The `pelican generate` command generates the [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html)-formatted password file for storing the web interface administrator login password. To generate a password file, run:
4580

4681
```bash copy
4782
pelican generate password

0 commit comments

Comments
 (0)