diff --git a/docs/cli/ory-proxy.md b/docs/cli/ory-proxy.md index 8023564d9..efa2d954a 100644 --- a/docs/cli/ory-proxy.md +++ b/docs/cli/ory-proxy.md @@ -15,126 +15,122 @@ Run your app and Ory on the same domain using a reverse proxy ### Synopsis -Allows running your app and Ory on the same domain by starting a reverse proxy that runs in front of your application. +The Ory Proxy allows your application and Ory to run on the same domain by acting as a reverse proxy. It forwards all traffic to your application, ensuring that features like cookies and CORS function correctly during local development. -The first argument `` points to the location of your application. The Ory Proxy -will pass all traffic through to this URL. +The first argument, `application-url`, points to the location of your application. The Ory Proxy will pass all traffic through to this URL. - $ ory proxy --project https://www.example.org - $ ORY_PROJECT= ory proxy proxy http://localhost:3000 +Example usage: + + $ ory proxy --project https://www.example.org + $ ORY_PROJECT= ory proxy proxy http://localhost:3000 ### Connecting to Ory -Before you start, you need to have an Ory Network project. You can create one with the following command: +Before using the Ory Proxy, you need to have an Ory Network project. You can create a new project with the following command: + + $ ory create project --name "Command Line Project" + +Once your project is ready, pass the project’s slug to the proxy command: + + $ ory proxy --project ... + +### Local development + +For local development, use the `--dev` flag to apply a relaxed security setting: - $ ory create project --name "Command Line Project" --use - $ ory proxy ... + $ ory proxy --dev --project http://localhost:3000 -### Developing Locally +The first argument, `application-url`, points to your application's location. If running both the proxy and your app on the same host, this could be `localhost`. All traffic sent to the Ory Proxy will be forwarded to this URL. -When developing locally we recommend to use the `--dev` flag, which uses a lax security setting: +The second argument, `publish-url`, is optional and only necessary for production scenarios. It specifies the public URL of your application (e.g., `https://www.example.org`). If `publish-url` is not set, it defaults to the host and port the proxy listens on. - $ ory proxy --dev \ - --project \ - http://localhost:3000 +**Important**: The Ory Proxy is intended for development use only and should not be used in production environments. -The first argument `` points to the location of your application. If you are -running the proxy and your app on the same host, this could be localhost. All traffic arriving at the -Ory Proxy will be passed through to this URL. +### Connecting in automated environments -The second argument `` is optional and only needed when going to production. -It refers to the public URL of your application (e.g. https://www.example.org). +To connect the Ory Tunnel in automated environments, create a Project API Key for your project and set it as an environment variable: -If `` is not set, it will default to the -host and port the proxy listens on. + $ %[2]s= ory proxy tunnel ... -### Running behind a Gateway +This will prevent the browser window from opening. -To go to production set up a custom domain (CNAME) for Ory. +### Running behind a gateway (development only) -You must set the `` if you are using the Ory Proxy behind a gateway: +If you are using the Ory Proxy behind a gateway during development, you must set the `publish-url` argument: - $ ory proxy \ - --project \ - http://localhost:3000 \ - https://gateway.local:5000 + $ ory proxy --project \ + http://localhost:3000 \ + https://gateway.local:5000 -Please note that you can not set a path in the ``! +Note: You cannot set a path in the `publish-url`. ### Ports -Per default, the proxy listens on port 4000. If you want to listen on another port, use the -port flag: +By default, the proxy listens on port 4000. To change this, use the `--port` flag: - $ ory proxy --port 8080 --project \ - http://localhost:3000 + $ ory proxy --port 8080 --project http://localhost:3000 -### Multiple Domains +### Multiple domains -If the proxy runs on a subdomain, and you want Ory's cookies (e.g. the session cookie) to -be available on all of your domain, you can use the `--cookie-domain` flag to customize the cookie -domain. You will also need to allow your subdomains in the CORS headers: +If the proxy runs on a subdomain and you want Ory’s cookies (e.g., session cookies) to be accessible across all your domains, use the `--cookie-domain` flag to customize the cookie domain. Additionally, allow your subdomains in the CORS headers: - $ ory proxy --project \ - --cookie-domain gateway.local \ - --allowed-cors-origins https://www.gateway.local \ - --allowed-cors-origins https://api.gateway.local \ - http://127.0.0.1:3000 \ - https://ory.gateway.local + $ ory proxy --project \ + --cookie-domain gateway.local \ + --allowed-cors-origins https://www.gateway.local \ + --allowed-cors-origins https://api.gateway.local \ + http://127.0.0.1:3000 \ + https://ory.gateway.local ### Redirects -Per default all default redirects will go to to `[]`. You can change this behavior using -the `--default-redirect-url` flag: +By default, all redirects will point to `publish-url`. You can customize this behavior using the `--default-redirect-url` flag: - $ ory proxy --project \ - --default-redirect-url /welcome \ - http://127.0.0.1:3000 \ - https://ory.example.org + $ ory proxy --project \ + --default-redirect-url /welcome \ + http://127.0.0.1:3000 \ + https://ory.example.org -Now, all redirects happening e.g. after login will point to `/welcome` instead of `/` unless you -have specified custom redirects in your Ory configuration or in the flow's `?return_to=` query parameter. +This ensures that all redirects (e.g., after login) go to `/welcome` instead of `/`, unless you’ve specified custom redirects in your Ory configuration or via the flow’s `?return_to=` query parameter. ### JSON Web Token -If the request is not authenticated, the HTTP Authorization Header will be empty: +When a request is not authenticated, the HTTP `Authorization` header will be empty: - GET / HTTP/1.1 - Host: localhost:3000 + GET / HTTP/1.1 + Host: localhost:3000 -If the request was authenticated, a JSON Web Token can be sent in the HTTP Authorization Header containing the -Ory Session: +If the request is authenticated, a JSON Web Token (JWT) containing the Ory session will be sent in the HTTP `Authorization` header: - GET / HTTP/1.1 - Host: localhost:3000 - Authorization: Bearer the-json-web-token + GET / HTTP/1.1 + Host: localhost:3000 + Authorization: Bearer the-json-web-token -The JSON Web Token claims contain: +The JWT claims contain: +- The `sub` field, which is set to the Ory Identity ID. +- The `session` field, which contains the full Ory Session. -* The "sub" field which is set to the Ory Identity ID. -* The "session" field which contains the full Ory Session. +The JWT is signed using the ES256 algorithm. You can fetch the public key by querying the `/ory/jwks.json` endpoint, for example: -The JSON Web Token is signed using the ES256 algorithm. The public key can be found by fetching the /.ory/jwks.json path -when calling the proxy - for example: `http://127.0.0.1:4000/.ory/jwks.json` +http://127.0.0.1:4000/.ory/jwks.json -An example payload of the JSON Web Token is: +An example JWT payload: - { - "id": "821f5a53-a0b3-41fa-9c62-764560fa4406", - "active": true, - "expires_at": "2021-02-25T09:25:37.929792Z", - "authenticated_at": "2021-02-24T09:25:37.931774Z", - "issued_at": "2021-02-24T09:25:37.929813Z", - "identity": { - "id": "18aafd3e-b00c-4b19-81c8-351e38705126", - "schema_id": "default", - "schema_url": "https://example.projects.oryapis.com/api/kratos/public/schemas/default", - "traits": { - "email": "foo@bar", - // ... your other identity traits + { + "id": "821f5a53-a0b3-41fa-9c62-764560fa4406", + "active": true, + "expires_at": "2021-02-25T09:25:37.929792Z", + "authenticated_at": "2021-02-24T09:25:37.931774Z", + "issued_at": "2021-02-24T09:25:37.929813Z", + "identity": { + "id": "18aafd3e-b00c-4b19-81c8-351e38705126", + "schema_id": "default", + "schema_url": "https://example.projects.oryapis.com/api/kratos/public/schemas/default", + "traits": { + "email": "foo@bar" + // ... other identity traits + } + } } - } - } ``` diff --git a/docs/cli/ory-tunnel.md b/docs/cli/ory-tunnel.md index 7278cec39..84e885fe0 100644 --- a/docs/cli/ory-tunnel.md +++ b/docs/cli/ory-tunnel.md @@ -1,7 +1,7 @@ --- id: ory-tunnel title: ory tunnel -description: ory tunnel Tunnel Ory on a subdomain of your app or a separate port your app's domain +description: ory tunnel Mirror Ory APIs on your local machine for local development and testing --- ## ory tunnel -Tunnel Ory on a subdomain of your app or a separate port your app's domain +Mirror Ory APIs on your local machine for local development and testing ### Synopsis -Tunnels Ory APIs on a subdomain or separate port of your app. This command runs an HTTP Server which is connected to Ory's APIs, in order for your application and Ory's -APIs to run on the same top level domain (for example yourapp.com, localhost). Having Ory on your domain -is required for cookies to work. +The Ory Tunnel mirrors Ory APIs on your local machine, allowing seamless development and testing. This setup is required for features such as CORS and cookie support, making it possible for Ory and your application to share the same top-level domain during development. To use the tunnel, authentication via `ORY_PROJECT_API_KEY` or browser-based sign-in is required. -The first argument `application-url` points to the location of your application. This location -will be used as the default redirect URL for the tunnel, for example after a successful login. +The Ory Tunnel command connects your application and Ory's APIs through a local HTTP server. This enables both to run on the same domain or subdomain (for example, yourapp.com, localhost), which is required for cookies to function correctly. -$ ory tunnel --project https://www.example.org -$ ORY_PROJECT= ory tunnel http://localhost:3000 +The first argument, `application-url`, points to the location of your application and will be used as the default redirect URL after successful operations like login. + +Example usage: + + $ ory tunnel --project https://www.example.org + $ ORY_PROJECT= ory tunnel http://localhost:3000 ### Connecting to Ory -Before you start, you need to have a running Ory Network project. You can create one with the following command: +Before using the Ory Tunnel, ensure that you have a running Ory Network project. You can create a new project with the following command: + + $ ory create project --name "Command Line Project" + +Once your project is ready, pass the project's slug to the tunnel command: - $ ory create project --name "Command Line Project" + $ ory tunnel --project ... + $ ORY_PROJECT= ory tunnel tunnel ... -Pass the project's slug as a flag to the tunnel command: +### Connecting in automated environments - $ ory tunnel --project ... - $ ORY_PROJECT= ory tunnel tunnel ... +To connect the Ory Tunnel in automated environments, create a Project API Key for your project and set it as an environment variable: -### Developing Locally + $ ORY_PROJECT_API_KEY= ory tunnel tunnel ... -When developing locally we recommend to use the `--dev` flag, which uses a lax security setting: +This will prevent the browser window from opening. - $ ory tunnel --dev --project \ - http://localhost:3000 +### Local development -### Running behind a Gateway +When developing locally, use the --dev flag to enable a more relaxed security configuration: -To go to production set up a custom domain (CNAME) for Ory. + $ ory tunnel --dev --project http://localhost:3000 -If you need to run the tunnel behind a gateway, you have to set the optional second argument `tunnel-url`. It tells the Ory Tunnel -on which domain it will run (for example https://ory.example.org). +Running behind a gateway (development only) +Important: The Ory Tunnel is designed for development purposes only and should not be used in production environments. - $ ory tunnel --project \ - https://www.example.org \ - https://auth.example.org \ - --cookie-domain example.org \ - --allowed-cors-origins https://www.example.org \ - --allowed-cors-origins https://api.example.org +If you need to run the tunnel behind a gateway during development, you can specify the optional second argument, tunnel-url, to define the domain where the Ory Tunnel will run (for example, https://ory.example.org). -Please note that you can not set a path in the `[tunnel-url]`! +Example: + + $ ory tunnel --project \ + https://www.example.org \ + https://auth.example.org \ + --cookie-domain example.org \ + --allowed-cors-origins https://www.example.org \ + --allowed-cors-origins https://api.example.org + +Note: You cannot set a path in the `tunnel-url`. ### Ports -Per default, the tunnel listens on port 4000. If you want to listen on another port, use the -port flag: +By default, the tunnel listens on port 4000. To change the port, use the --port flag: - $ ory tunnel --port 8080 --project \ - https://www.example.org + $ ory tunnel --port 8080 --project https://www.example.org -If your application URL is available on a non-standard HTTP/HTTPS port, you can set that port in the `application-url`: +If your application runs on a non-standard HTTP or HTTPS port, include the port in the `application-url`: - $ ory tunnel --project \ - https://example.org:1234 + $ ory tunnel --project https://example.org:1234 ### Cookies -We recommend setting the `--cookie-domain` value to your top level domain: +For cookie support, set the `--cookie-domain` flag to your top-level domain: - $ ory tunnel --project \ - --cookie-domain example.org \ - https://www.example.org \ - https://auth.example.org + $ ory tunnel --project \ + --cookie-domain example.org \ + https://www.example.org \ + https://auth.example.org ### Redirects -To use a different default redirect URL, use the `--default-redirect-url` flag: - - $ ory tunnel tunnel --project \ - --default-redirect-url /welcome \ - https://www.example.org +To specify a custom redirect URL, use the `--default-redirect-url` flag: +$ ory tunnel tunnel --project \ + --default-redirect-url /welcome \ + https://www.example.org ``` ory tunnel [] [flags] diff --git a/docs/cli/ory.md b/docs/cli/ory.md index 29c6b4fae..4ee0275ff 100644 --- a/docs/cli/ory.md +++ b/docs/cli/ory.md @@ -37,7 +37,7 @@ The Ory CLI * [ory perform](ory-perform) - Perform a flow * [ory proxy](ory-proxy) - Run your app and Ory on the same domain using a reverse proxy * [ory revoke](ory-revoke) - Revoke resources -* [ory tunnel](ory-tunnel) - Tunnel Ory on a subdomain of your app or a separate port your app's domain +* [ory tunnel](ory-tunnel) - Mirror Ory APIs on your local machine for local development and testing * [ory update](ory-update) - Update resources * [ory use](ory-use) - Use a resource * [ory validate](ory-validate) - Validate resources