From 7d8821aa25b8270d80507e24cb0ca506ec266c09 Mon Sep 17 00:00:00 2001 From: Gao Sun Date: Tue, 3 May 2022 00:34:31 +0800 Subject: [PATCH 1/3] docs: init introduction --- .vscode/settings.json | 7 +++++- packages/docs/docs/tutorial/README.md | 32 ++++++++++++++++++++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index a039625bf..53445938c 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -19,5 +19,10 @@ ], "editor.codeActionsOnSave": { "source.fixAll.eslint": true, - } + }, + "cSpell.words": [ + "Alipay", + "Logto", + "Passwordless" + ] } diff --git a/packages/docs/docs/tutorial/README.md b/packages/docs/docs/tutorial/README.md index 93e6fee7d..d62d1faef 100644 --- a/packages/docs/docs/tutorial/README.md +++ b/packages/docs/docs/tutorial/README.md @@ -4,4 +4,34 @@ sidebar_position: 1 # Introduction -🤘 Logto is an open-source customer identity solution. +🤘 Logto helps you quickly focus on everything after signing in with the following components: + +- All-platform user sign-in / sign-up experience with SDK support (SPA, iOS and Android) +- Passwordless (SMS / Email) support +- Out-of-box social sign in support (GitHub, Google, WeChat, Alipay, etc.) +- A web UI to control all above (Admin Console) +- Extendable multi-language support +- Easy deployment + +Boringly, we call it "[customer identity access management](https://en.wikipedia.org/wiki/Customer_identity_access_management)" or "customer identity solution". + +# Get Started + +## Prerequisites + +- NodeJS >= 16.0.0 +- PostgreSQL >= 14.0.0 + +It's okay that your PostgreSQL instance is not in the same machine as NodeJS (e.g. containers + remote database environment). + +## Run Logto + +### Download Script + +In your terminal: + +```bash +node -e "$(printf "%s" "$(curl -fsSL https://raw.githubusercontent.com/logto-io/logto/master/install.js)")" +``` + +The script will download Logto and create a directory `logto` in the location you ran it. From 4400d8d25eebf0a2d9e7c5c91e82e804d3314493 Mon Sep 17 00:00:00 2001 From: Gao Sun Date: Thu, 5 May 2022 15:16:11 +0800 Subject: [PATCH 2/3] docs: init configuration --- .vscode/settings.json | 6 +++- .../core/src/env-set/create-pool-by-env.ts | 2 +- packages/docs/docs/tutorial/README.md | 30 ++++++++++++---- packages/docs/docs/tutorial/configuration.md | 36 +++++++++++++++++++ 4 files changed, 66 insertions(+), 8 deletions(-) create mode 100644 packages/docs/docs/tutorial/configuration.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 53445938c..2da82185a 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -22,7 +22,11 @@ }, "cSpell.words": [ "Alipay", + "CIAM", "Logto", - "Passwordless" + "oidc", + "Passwordless", + "silverhand", + "slonik" ] } diff --git a/packages/core/src/env-set/create-pool-by-env.ts b/packages/core/src/env-set/create-pool-by-env.ts index 3676799e1..2a9fa6a8b 100644 --- a/packages/core/src/env-set/create-pool-by-env.ts +++ b/packages/core/src/env-set/create-pool-by-env.ts @@ -32,7 +32,7 @@ const inquireForLogtoDsn = async (key: string): Promise<[Optional, boole type: 'confirm', name: 'value', default: false, - message: 'Do you have an empty databse for Logto?', + message: 'Do you have an empty database for Logto?', }); const dsnAnswer = await inquirer.prompt({ diff --git a/packages/docs/docs/tutorial/README.md b/packages/docs/docs/tutorial/README.md index d62d1faef..482670d4b 100644 --- a/packages/docs/docs/tutorial/README.md +++ b/packages/docs/docs/tutorial/README.md @@ -13,20 +13,24 @@ sidebar_position: 1 - Extendable multi-language support - Easy deployment -Boringly, we call it "[customer identity access management](https://en.wikipedia.org/wiki/Customer_identity_access_management)" or "customer identity solution". +Boringly, we call it "[customer identity access management](https://en.wikipedia.org/wiki/Customer_identity_access_management)" (CIAM) or "customer identity solution." -# Get Started +## Get Started -## Prerequisites +### Prerequisites - NodeJS >= 16.0.0 - PostgreSQL >= 14.0.0 +We recommend using a new empty database which is dedicated for Logto, while it's not a hard requirement. + +:::tip It's okay that your PostgreSQL instance is not in the same machine as NodeJS (e.g. containers + remote database environment). +::: -## Run Logto +### Run a Logto Instance -### Download Script +#### Download Script In your terminal: @@ -34,4 +38,18 @@ In your terminal: node -e "$(printf "%s" "$(curl -fsSL https://raw.githubusercontent.com/logto-io/logto/master/install.js)")" ``` -The script will download Logto and create a directory `logto` in the location you ran it. +The script will download Logto and create a directory `logto` in the location you ran it. After answering [several simple questions](./configuration#questions), you will see the text: + +```bash +Server is listening to port 3001 +``` + +Heading to http://localhost:3001 to continue the Logto journey. Enjoy! + +#### Docker + +TBD + +### Configuration + +Logto uses environment variables for configuration, along with `.env` file support. See [Configuration](./configuration) for detailed usage and full option list. diff --git a/packages/docs/docs/tutorial/configuration.md b/packages/docs/docs/tutorial/configuration.md new file mode 100644 index 000000000..3f05b5e33 --- /dev/null +++ b/packages/docs/docs/tutorial/configuration.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 2 +--- + +# Configuration + +## Usage + +Logto handles environment variables with the following order: + +- The `.env` file in the project root +- System environment variable + +Thus if the system environment variable will override the value in `.env`. + +## First-time Setup Questions {#questions} + +For the first time you start Logto with no related environment variable, unless `--no-inquiry` is specified, it'll ask several questions for a smooth experience to fulfill the minimum requirements: + +- If you'd like to generate a set of password peppers +- If you'd like to generate a private key for OIDC provider +- If you'd like to set up a new Logto database +- Enter the [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) +- Finally the domain for Logto + +Most of them are just simple yes / no questions or you can use the default value, except the [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6). + +The generated private key for OIDC provider will locate on `./oidc-private-key.pem`, while other values will append to `./.env`. + +:::note +The `--no-inquiry` parameter is appended by default in the Docker image. +::: + +## Variable List + +TBF in the next PR From 9ca2815452f9160ce21b35c5b1d28af52ce5930d Mon Sep 17 00:00:00 2001 From: Gao Sun Date: Thu, 5 May 2022 22:39:28 +0800 Subject: [PATCH 3/3] docs: configuration --- packages/core/src/env-set/index.ts | 8 +-- packages/core/src/env-set/oidc.ts | 2 +- packages/core/src/index.ts | 2 +- packages/docs/docs/tutorial/README.md | 4 +- packages/docs/docs/tutorial/configuration.md | 60 +++++++++++++++++--- 5 files changed, 59 insertions(+), 17 deletions(-) diff --git a/packages/core/src/env-set/index.ts b/packages/core/src/env-set/index.ts index 0f1fa7ae6..2c3dea6cd 100644 --- a/packages/core/src/env-set/index.ts +++ b/packages/core/src/env-set/index.ts @@ -19,12 +19,12 @@ const loadEnvValues = async () => { return Object.freeze({ isTest, isProduction, - isHttpsEnabled: Boolean(process.env.HTTPS_CERT && process.env.HTTPS_KEY), - httpsCert: process.env.HTTPS_CERT, - httpsKey: process.env.HTTPS_KEY, + isHttpsEnabled: Boolean(process.env.HTTPS_CERT_PATH && process.env.HTTPS_KEY_PATH), + httpsCert: process.env.HTTPS_CERT_PATH, + httpsKey: process.env.HTTPS_KEY_PATH, port, developmentUserId: getEnv('DEVELOPMENT_USER_ID'), - trustingTlsOffloadingProxies: getEnv('TRUSTING_TLS_OFFLOADING_PROXIES') === 'true', + trustProxyHeader: getEnv('TRUST_PROXY_HEADER') === 'true', password: await loadPasswordValues(isTest), oidc: await loadOidcValues(port), }); diff --git a/packages/core/src/env-set/oidc.ts b/packages/core/src/env-set/oidc.ts index 54469c156..66ae3eb04 100644 --- a/packages/core/src/env-set/oidc.ts +++ b/packages/core/src/env-set/oidc.ts @@ -24,7 +24,7 @@ const readPrivateKey = async (): Promise => { return privateKey; } - const privateKeyPath = getEnv('OIDC_PRIVATE_KEY_PATH', 'oidc-private-key.pem'); + const privateKeyPath = getEnv('OIDC_PRIVATE_KEY_PATH', './oidc-private-key.pem'); try { return readFileSync(privateKeyPath, 'utf-8'); diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index f55666784..2f27735eb 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -18,7 +18,7 @@ import initI18n from './i18n/init'; try { await envSet.load(); const app = new Koa({ - proxy: envSet.values.trustingTlsOffloadingProxies, + proxy: envSet.values.trustProxyHeader, }); await initConnectors(); await initI18n(); diff --git a/packages/docs/docs/tutorial/README.md b/packages/docs/docs/tutorial/README.md index 482670d4b..80de334b4 100644 --- a/packages/docs/docs/tutorial/README.md +++ b/packages/docs/docs/tutorial/README.md @@ -38,7 +38,7 @@ In your terminal: node -e "$(printf "%s" "$(curl -fsSL https://raw.githubusercontent.com/logto-io/logto/master/install.js)")" ``` -The script will download Logto and create a directory `logto` in the location you ran it. After answering [several simple questions](./configuration#questions), you will see the text: +The script will download Logto and create a directory `logto` in the location you ran it. After answering [several simple questions](./configuration#questions), you will see the message like: ```bash Server is listening to port 3001 @@ -52,4 +52,4 @@ TBD ### Configuration -Logto uses environment variables for configuration, along with `.env` file support. See [Configuration](./configuration) for detailed usage and full option list. +Logto uses environment variables for configuration, along with `.env` file support. See [Configuration](./configuration) for detailed usage and full variable list. diff --git a/packages/docs/docs/tutorial/configuration.md b/packages/docs/docs/tutorial/configuration.md index 3f05b5e33..e64f91acc 100644 --- a/packages/docs/docs/tutorial/configuration.md +++ b/packages/docs/docs/tutorial/configuration.md @@ -6,26 +6,24 @@ sidebar_position: 2 ## Usage -Logto handles environment variables with the following order: +Logto handles environment variables in the following order: -- The `.env` file in the project root +- The `.env` file in the project root, which conforms with [dotenv](https://github.com/motdotla/dotenv#readme) format - System environment variable -Thus if the system environment variable will override the value in `.env`. +Thus the system environment variable will override the value in `.env`. ## First-time Setup Questions {#questions} For the first time you start Logto with no related environment variable, unless `--no-inquiry` is specified, it'll ask several questions for a smooth experience to fulfill the minimum requirements: -- If you'd like to generate a set of password peppers -- If you'd like to generate a private key for OIDC provider +- If you'd like to generate a private key for the OIDC provider - If you'd like to set up a new Logto database - Enter the [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) -- Finally the domain for Logto -Most of them are just simple yes / no questions or you can use the default value, except the [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6). +Most of them are simple yes / no questions, or you can just go with the default value, except the [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6). -The generated private key for OIDC provider will locate on `./oidc-private-key.pem`, while other values will append to `./.env`. +The generated private key for the OIDC provider will locate on `./oidc-private-key.pem`, while other values will append to `./.env`. :::note The `--no-inquiry` parameter is appended by default in the Docker image. @@ -33,4 +31,48 @@ The `--no-inquiry` parameter is appended by default in the Docker image. ## Variable List -TBF in the next PR +### General + +| Key | Default Value | Type | Description | +| ------------------ | ------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| NODE_ENV | `undefined` | 'production' | 'test' | undefined | What kind of environment that Logto runs in. If you run Logto via `npm start`, the value will always be `production`. | +| PORT | `3001` | `number` | The local port that Logto listens. | +| DB_URL | N/A | `string` | The [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) for Logto database. | +| HTTPS_CERT_PATH | `undefined` | string | undefined | See [Enabling HTTPS](#enabling-https) for details. | +| HTTPS_KEY_PATH | `undefined` | string | undefined | Ditto. | +| TRUST_PROXY_HEADER | `false` | `boolean` | Ditto. | +| ADMIN_RESOURCE | `'https://api.logto.io'` | `string` | The resource indicator for Logto management APIs. | + +### OIDC + +| Key | Default Value | Type | Description | +| --------------------- | ------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OIDC_PRIVATE_KEY | N/A | string | undefined | The content of private key for [OIDC JWT signing](https://openid.net/specs/openid-connect-core-1_0.html#Signing).
If you'd like to set this in `.env`, you can leverage [multiline values](https://github.com/motdotla/dotenv#multiline-values) support. | +| OIDC_PRIVATE_KEY_PATH | `'./oidc-private-key.pem'` | string | undefined | The path to the private key file for [OIDC JWT signing](https://openid.net/specs/openid-connect-core-1_0.html#Signing).
Note Logto will *ignore* this value if `OIDC_PRIVATE_KEY` is not empty. | +| OIDC_ISSUER | `'http://localhost:$PORT/oidc'` | `string` | The [issuer identifier](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) for OIDC. Usually it's the URL to your OIDC provider. | + +#### Supported Key Types + +- RSA +- OKP (Ed25519, Ed448, X25519, X448 sub types) +- EC (P-256, secp256k1, P-384, and P-521 curves) + +:::note +Logto mounts OIDC provider under path `/oidc`. That means if you mount Logto under `https://your.domain.com/logto`, the value of `OIDC_ISSUER` should be `https://your.domain.com/logto/oidc`. +::: + +## Enabling HTTPS + +### Using Node + +Node natively supports HTTPS. Provide **BOTH** `HTTPS_CERT_PATH` and `HTTPS_KEY_PATH` to enable HTTPS via Node. + +`HTTPS_CERT_PATH` implies the path to your HTTPS certificate, while `HTTPS_KEY_PATH` implies the path to your HTTPS key. + +### Using a HTTPS Proxy + +Another common practice is to have a HTTPS proxy in front of Node. + +In this case, you're likely want to set `TRUST_PROXY_HEADER` to `true` which indicates if proxy header fields should be trusted. Logto will pass the value to [Koa app settings](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings). + +See [Trusting TLS offloading proxies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) for when to configure this field.