Skip to content

Commit

Permalink
autogen(docs): generate cli docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ory-bot
ory-bot committed Oct 12, 2024
1 parent 97c158a commit e3ad11f
Show file tree
Hide file tree
Showing 3 changed files with 126 additions and 126 deletions.
154 changes: 75 additions & 79 deletions docs/cli/ory-proxy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<application-url>` 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 <project-id-or-slug> https://www.example.org
$ ORY_PROJECT=<project-id-or-slug> ory proxy proxy http://localhost:3000
Example usage:

$ ory proxy --project <project-id-or-slug> https://www.example.org
$ ORY_PROJECT=<project-id-or-slug> 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 <project-id-or-slug> ...

### 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 <project-id-or-slug> 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 <project-id-or-slug> \
http://localhost:3000
**Important**: The Ory Proxy is intended for development use only and should not be used in production environments.

The first argument `<application-url>` 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 `<publish-url>` 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 `<publish-url>` is not set, it will default to the
host and port the proxy listens on.
$ %[2]s=<project-api-key> 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 `<publish-url>` 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 <project-id-or-slug> \
http://localhost:3000 \
https://gateway.local:5000
$ ory proxy --project <project-id-or-slug> \
http://localhost:3000 \
https://gateway.local:5000

Please note that you can not set a path in the `<publish-url>`!
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 <project-id-or-slug> \
http://localhost:3000
$ ory proxy --port 8080 --project <project-id-or-slug> 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 <project-id-or-slug> \
--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 <project-id-or-slug> \
--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 `[<publish-url>]`. 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 <project-id-or-slug> \
--default-redirect-url /welcome \
http://127.0.0.1:3000 \
https://ory.example.org
$ ory proxy --project <project-id-or-slug> \
--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
}
}
}
}
}


```
Expand Down
96 changes: 50 additions & 46 deletions docs/cli/ory-tunnel.md
View file
Original file line number Diff line number Diff line change
@@ -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
---

<!--
Expand All @@ -11,84 +11,88 @@ To improve this file please make your change against the appropriate "./cmd/*.go
-->
## 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 <project-id-or-slug> https://www.example.org
$ ORY_PROJECT=<project-id-or-slug> 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 <project-id-or-slug> https://www.example.org
$ ORY_PROJECT=<project-id-or-slug> 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 <project-id-or-slug> ...
$ ORY_PROJECT=<project-id-or-slug> ory tunnel tunnel ...

Pass the project's slug as a flag to the tunnel command:
### Connecting in automated environments

$ ory tunnel --project <project-id-or-slug> ...
$ ORY_PROJECT=<project-id-or-slug> 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=<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 <project-id-or-slug> \
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 <project-id-or-slug> 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 <project-id-or-slug> \
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 <project-id-or-slug> \
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 <project-id-or-slug> \
https://www.example.org
$ ory tunnel --port 8080 --project <project-id-or-slug> 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 <project-id-or-slug> \
https://example.org:1234
$ ory tunnel --project <project-id-or-slug> 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 <project-id-or-slug> \
--cookie-domain example.org \
https://www.example.org \
https://auth.example.org
$ ory tunnel --project <project-id-or-slug> \
--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 <project-id-or-slug> \
--default-redirect-url /welcome \
https://www.example.org
To specify a custom redirect URL, use the `--default-redirect-url` flag:

$ ory tunnel tunnel --project <project-id-or-slug> \
--default-redirect-url /welcome \
https://www.example.org

```
ory tunnel <application-url> [<tunnel-url>] [flags]
Expand Down
2 changes: 1 addition & 1 deletion docs/cli/ory.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit e3ad11f

Please sign in to comment.