diff --git a/images/tutorials/self-host/token.png b/images/tutorials/self-host/token.png new file mode 100644 index 00000000..06e7cc9d Binary files /dev/null and b/images/tutorials/self-host/token.png differ diff --git a/installation/authentication-setup/development-tokens.mdx b/installation/authentication-setup/development-tokens.mdx index 13a6dced..152f28fd 100644 --- a/installation/authentication-setup/development-tokens.mdx +++ b/installation/authentication-setup/development-tokens.mdx @@ -37,6 +37,8 @@ For self-hosted [local development](/self-hosting/local-development), the [power node dist/bin.js generate-token --config path/to/powersync.yaml --sub test-user ``` +For more information on generating development tokens, see the [Generate development tokens tutorial](/tutorials/self-host/generate-dev-token) + ## Usage To use the temporary development token, update the `fetchCredentials()` function in your backend connector to return the generated token (see [Integrate with your Backend](/installation/client-side-setup/integrating-with-your-backend) for more information). diff --git a/mint.json b/mint.json index 8a48ebb2..00e02e99 100644 --- a/mint.json +++ b/mint.json @@ -406,7 +406,10 @@ }, { "group": "Self Host", - "pages": ["tutorials/self-host/overview"] + "pages": [ + "tutorials/self-host/overview", + "tutorials/self-host/generate-dev-token" + ] }, { "group": "Resources", diff --git a/tutorials/self-host/generate-dev-token.mdx b/tutorials/self-host/generate-dev-token.mdx new file mode 100644 index 00000000..ce0b5a1a --- /dev/null +++ b/tutorials/self-host/generate-dev-token.mdx @@ -0,0 +1,75 @@ +--- +title: "Generate a Development Token" +description: "In this tutorial we will show you how to generate a development token for the self-hosted [PowerSync Service](https://powersync.mintlify.app/architecture/powersync-service#powersync-service)." +--- + +# Introduction + +Development tokens are useful for: +- getting started quickly without implementing full auth config +- sanity checking your sync rules config (were they applied correctly) +- temporarily impersonating a specific user to debug specific issues + +# Use Case + +Development tokens can be used either with the +- [test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client), or +- [the diagnostics app](/resources/troubleshooting#diagnostics-app) + +# Generate a Development Token +Development tokens can be generated via either +- [PowerSync Cloud](/installation/authentication-setup/development-tokens/#PowerSync-Cloud-Dashboard), or +- locally with a self-hosted setup (described in this tutorial) + + + + To generate a SharedSecret, you can use this [Online JWS key generator](https://8gwifi.org/jwsgen.jsp): + + You don't need to edit the default payload in the [Online JWS key generator](https://8gwifi.org/jwsgen.jsp). + You simply need to obtain the generated `SharedSecret` value. + + - Click `Generate JWS Keys` + - Copy the `SharedSecret` value + + Using an online key generator for secrets in a production environment is not recommended. + + + + + Update the `k` value in the jwks keys in your `powersync.yaml` config file with the `SharedSecret` value copied in the previous step: + ```yaml powersync.yaml {8} + # Client (application end user) authentication settings + client_auth: + # JWKS URIs can be specified here + jwks_uri: !env PS_JWKS_URL + jwks: + keys: + - kty: 'oct' + k: 'YOUR_GENERATED_SHARED_SECRET' + alg: 'HS256' + ``` + + + + 1. If you have not done so already, clone the [powersync-service repo](https://github.com/powersync-ja/powersync-service/tree/main) + 2. Install the dependencies + - In the project root, run the following commands: + ```bash + pnpm install + pnpm build:packages + ``` + - In the `test-client` directory, run the following commands: + ```bash + pnpm build + ``` + 3. Generate a new token by running the following command in the `test-client` directory with your updated `powersync.yaml` config file: + ```bash + node dist/bin.js generate-token --config path/to/powersync.yaml --sub test-user + ``` + You should see an output similar to the following: + + + + + + diff --git a/tutorials/self-host/overview.mdx b/tutorials/self-host/overview.mdx index 6d6aaaa5..01cc8d86 100644 --- a/tutorials/self-host/overview.mdx +++ b/tutorials/self-host/overview.mdx @@ -1,3 +1,8 @@ --- -title: "Coming Soon..." ---- \ No newline at end of file +title: "Overview" +description: "A collection of tutorials related to self-hosting." +--- + + + + \ No newline at end of file