|
| 1 | +{/* Due to a bug in prettier formatting (https://github.com/prettier/prettier/issues/17700) we can't retain multi-line comments with empty lines. */} |
| 2 | +{/* So instead, just store this edition of this component in a separate file until we get to update. */} |
| 3 | +{/* Replace `basic-authentication.mdx` with this when we switch from using `atob()` here https://github.com/HarperFast/harper/blob/main/security/auth.ts#L181 potentially in v5 */} |
| 4 | + |
| 5 | +<details> |
| 6 | + <summary>Basic Authentication</summary> |
| 7 | + |
| 8 | +The simplest authorization scheme is [Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication#basic_authentication_scheme) which transmits credentials as username/password pairs encoded using base64. Importantly, this scheme does not encrypt credentials. If used over an insecure connection, such as HTTP, they are susceptible to being compromised. Only ever use Basic Authentication over secured connections, such as HTTPS. Even then, its better to upgrade to an encryption based authentication scheme or certificates. Harper supports many different authentication mechanisms, and they will all be covered in later Learn guides. |
| 9 | + |
| 10 | +Use the username and password values from the previous [Install and Connect](/learn/getting-started/install-and-connect-harper) guide to generate an authorization value. The important part is to combine the `username` and `password` using a colon `:` character, encode that using base64, and then append the result to `"Basic "`. |
| 11 | + |
| 12 | +Here are some efficient methodologies: |
| 13 | + |
| 14 | +{/* Maybe consider using Tabs here with labels like "Node.js <=v24" and ("Web" or "Winter" or "W/MCA" if defined that abbreviation earlier somehow?) */} |
| 15 | + |
| 16 | +In Node.js v24 or earlier use the [`Buffer`](https://nodejs.org/docs/latest/api/buffer.html) API: |
| 17 | + |
| 18 | +```typescript |
| 19 | +// Ensure you replace these with your installation's values |
| 20 | +const username = 'HDB_ADMIN'; |
| 21 | +const password = 'abc123!'; |
| 22 | +const credentials = Buffer.from(`${username}:${password}`).toString('base64'); |
| 23 | +const authorizationValue = `Basic ${credentials}`; |
| 24 | +``` |
| 25 | + |
| 26 | +For Node.js v25 or later, most web browser consoles, and any WinterTC Minimum Common API compatible runtime use the [`Uint8Array.prototype.toBase64()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array/toBase64) API: |
| 27 | + |
| 28 | +```typescript |
| 29 | +// Ensure you replace these with your installation's values |
| 30 | +const username = 'HDB_ADMIN'; |
| 31 | +const password = 'abc123!'; |
| 32 | +const credentials = new TextEncoder().encode(`${username}:${password}`).toBase64(); |
| 33 | +const authorizationValue = `Basic ${credentials}`; |
| 34 | +``` |
| 35 | + |
| 36 | +> Both of these options are preferred over [`btoa()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/btoa) do to its limitation to Latin-1 character set. |
| 37 | +
|
| 38 | +You would use the `authorizationValue` as the value for the `Authorization` header such as: |
| 39 | + |
| 40 | +```typescript |
| 41 | +fetch('/', { |
| 42 | + // ... |
| 43 | + headers: { |
| 44 | + Authorization: authorizationValue, |
| 45 | + }, |
| 46 | + // ... |
| 47 | +}); |
| 48 | +``` |
| 49 | + |
| 50 | +</details> |
0 commit comments