mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-10-21 20:19:11 +02:00
add machine client roles
This commit is contained in:
miloschwartz
@@ -138,7 +138,7 @@ Roles group people for RBAC. You assign roles on each resource, so access follow
|
||||
|
||||
Clients are software components installed on user devices or machines. They let users and automated systems connect directly to sites to access [private resources](/manage/resources/understanding-resources#private-resource-types) through a secure tunnel. Clients also enforce access control and security at the edge.
|
||||
|
||||
Users authenticate through the client with their [user credentials](/manage/access-control/create-user) in a web login flow. [Machines](/manage/clients/credentials) connect with machine client credentials. Once connected, users can reach all resources their account has access to. The client handles [routing](/manage/clients/nat-traversal) decisions and establishes encrypted tunnels to the appropriate [sites](/manage/sites/understanding-sites).
|
||||
Users authenticate through the client with their [user credentials](/manage/access-control/create-user) in a web login flow. [Machines](/manage/clients/machine-clients) connect with machine client credentials. Once connected, users can reach all resources their account has access to. The client handles [routing](/manage/clients/nat-traversal) decisions and establishes encrypted tunnels to the appropriate [sites](/manage/sites/understanding-sites).
|
||||
|
||||
<Frame caption="User devices in the dashboard, with identity provider, connection status, and client version.">
|
||||
<img src="/images/user-devices.png" alt="User Devices page in the Pangolin dashboard"/>
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: "Machine Client Credentials"
|
||||
description: "How machine clients authenticate with an ID and secret, and how to rotate or regenerate those credentials"
|
||||
---
|
||||
## Understanding Credentials
|
||||
|
||||
Machine client credentials are only for [machine clients](/manage/clients/understanding-clients#machines): servers and automated systems that connect without a person present. Each machine client is provisioned with a unique identifier (ID), secret, and endpoint. The client uses those three values to establish a secure, encrypted connection to the server. **Machine client credentials can not be shared across different clients**.
|
||||
|
||||
User devices do not use machine client credentials. A person logs in with their Pangolin user credentials, or with an external identity provider, through the web login flow in the client. That login creates a session tied to their account. The session is not shown in the dashboard and cannot be regenerated. To disconnect a user device, have the user log out in the client.
|
||||
|
||||
### ID
|
||||
|
||||
Example: `ln8yqs6w85la5zg`
|
||||
|
||||
The ID represents the client connection in the system. Every machine client has an ID.
|
||||
|
||||
This value is not a secret and it is okay if made publically available.
|
||||
|
||||
### Secret
|
||||
|
||||
Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to`
|
||||
|
||||
The secret represents the "password" of the client. This secret must match the secret hashed in the system for the relevant ID.
|
||||
|
||||
<Note>
|
||||
This is a _secret_! Only share it with trusted people and be sure to store it safely and securely.
|
||||
</Note>
|
||||
|
||||
When the client connects, it uses this secret as a first handshake with the server. The server then passes temporary session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is established, ephemeral keys are used to establish tunnels using WireGuard.
|
||||
|
||||
### Endpoint
|
||||
|
||||
Example: `https://app.pangolin.net` or `https://pangolin.my-server.com`
|
||||
|
||||
The endpoint is how the client knows which server to connect to. This is the fully qualified hostname of the Pangolin server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The client uses this endpoint ot establish a websocket connection and receive control messages from the server.
|
||||
|
||||
## Rotating and Regenerating Credentials
|
||||
|
||||
<Note>
|
||||
This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
|
||||
</Note>
|
||||
|
||||
Machine client credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret. Use this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on a regular basis for extra security.
|
||||
|
||||
To regenerate credentials, visit Clients > Machines > Your Client > Credentials in the Pangolin admin dashboard.
|
||||
|
||||
### Regenerate vs. Regenerate and Disconnect
|
||||
|
||||
Regenerate simply recreates the credentials and invalidates the old ones. The client will remain connected until you restart it with the new credentials.
|
||||
|
||||
Regenerate and Disconnect recreates the credentials and invalides the old ones. The client will instantly disconnect and will require you to restart it with the new credentials.
|
||||
@@ -120,7 +120,7 @@ Each Pod running the sidecar connects as the same machine client. If you scale a
|
||||
<Card title="Platforms" href="/manage/clients/platforms" icon="sliders">
|
||||
Shared client preferences for DNS and routing.
|
||||
</Card>
|
||||
<Card title="Machine Client Credentials" href="/manage/clients/credentials" icon="key">
|
||||
Rotate and regenerate the ID and secret used by a machine client.
|
||||
<Card title="Machine Clients" href="/manage/clients/machine-clients" icon="server">
|
||||
Create machine clients, assign roles, and rotate credentials.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: "Machine Clients"
|
||||
description: "Connect servers and automation to private resources with ID and secret credentials, and assign roles for access"
|
||||
---
|
||||
|
||||
Machine clients are for servers and automated systems that are not tied to a person. Unlike [user devices](/manage/clients/understanding-clients#user-devices), they do not log in through a web flow. They authenticate with an ID, secret, and endpoint, then reach the [private resources](/manage/resources/understanding-resources#private-resource-types) you grant them.
|
||||
|
||||
Use a machine client when a long-running process or job needs network access, for example:
|
||||
|
||||
- A CI/CD runner that deploys against an internal database
|
||||
- A VPS that must reach a service on another site
|
||||
- A [subnet router](/manage/clients/subnet-router) that shares access with devices behind it
|
||||
- A [Kubernetes sidecar](/manage/clients/kubernetes/deployment) that brings a pod onto the network
|
||||
|
||||
Run machine clients with [Pangolin CLI](/manage/clients/platforms/cli#machine-clients).
|
||||
|
||||
## Create a Machine Client
|
||||
|
||||
1. In the dashboard, go to **Clients → Machines**.
|
||||
2. Create a machine client and give it a name.
|
||||
3. Copy the ID, secret, and endpoint shown at creation. You need all three to start the client.
|
||||
|
||||
## Grant Access to Private Resources
|
||||
|
||||
A connected machine client has no private resource access until you grant it. You can do that in two ways:
|
||||
|
||||
| Method | Where | When to use it |
|
||||
| --- | --- | --- |
|
||||
| **Direct** | On the private resource under **Access**, assign the machine client | One-off access for a single machine |
|
||||
| **Roles** | On the machine client under **General**, assign one or more [roles](/manage/access-control/create-user#roles) | The machine should share the same private-resource set as a group of users |
|
||||
|
||||
When you assign a role to a machine client, the client gains access to every private resource that role is allowed to reach. Access is the union of direct grants and all assigned roles.
|
||||
|
||||
User devices cannot be assigned roles on the client itself. They inherit roles from the signed-in user.
|
||||
|
||||
Unlike users, a machine client is not required to keep at least one role. You can remove every role and leave only direct grants, or leave the client with no access at all.
|
||||
|
||||
To assign roles on a machine client:
|
||||
|
||||
1. Open **Clients → Machines →** your client → **General**.
|
||||
2. Select the roles the client should belong to.
|
||||
3. Save.
|
||||
|
||||
After you change roles or resource grants, the client updates its tunnels automatically. Removing access tears down tunnels to sites that no longer have any reachable resources.
|
||||
|
||||
<Note>
|
||||
Assigning roles to machine clients is only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) or self-hosted [Enterprise Edition](/self-host/enterprise-edition). Direct assignment of a machine client on a private resource does not require that feature.
|
||||
</Note>
|
||||
|
||||
## Credentials
|
||||
|
||||
Machine client credentials are only for machine clients. Each machine client is provisioned with a unique identifier (ID), secret, and endpoint. The client uses those three values to establish a secure, encrypted connection to the server. **Machine client credentials can not be shared across different clients**.
|
||||
|
||||
User devices do not use machine client credentials. A person logs in with their Pangolin user credentials, or with an external identity provider, through the web login flow in the client. That login creates a session tied to their account. The session is not shown in the dashboard and cannot be regenerated. To disconnect a user device, have the user log out in the client.
|
||||
|
||||
### ID
|
||||
|
||||
Example: `ln8yqs6w85la5zg`
|
||||
|
||||
The ID represents the client connection in the system. Every machine client has an ID.
|
||||
|
||||
This value is not a secret and it is okay if made publically available.
|
||||
|
||||
### Secret
|
||||
|
||||
Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to`
|
||||
|
||||
The secret represents the "password" of the client. This secret must match the secret hashed in the system for the relevant ID.
|
||||
|
||||
<Note>
|
||||
This is a _secret_! Only share it with trusted people and be sure to store it safely and securely.
|
||||
</Note>
|
||||
|
||||
When the client connects, it uses this secret as a first handshake with the server. The server then passes temporary session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is established, ephemeral keys are used to establish tunnels using WireGuard.
|
||||
|
||||
### Endpoint
|
||||
|
||||
Example: `https://app.pangolin.net` or `https://pangolin.my-server.com`
|
||||
|
||||
The endpoint is how the client knows which server to connect to. This is the fully qualified hostname of the Pangolin server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The client uses this endpoint ot establish a websocket connection and receive control messages from the server.
|
||||
|
||||
## Rotating and Regenerating Credentials
|
||||
|
||||
<Note>
|
||||
This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
|
||||
</Note>
|
||||
|
||||
Machine client credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret. Use this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on a regular basis for extra security.
|
||||
|
||||
To regenerate credentials, visit Clients > Machines > Your Client > Credentials in the Pangolin admin dashboard.
|
||||
|
||||
### Regenerate vs. Regenerate and Disconnect
|
||||
|
||||
Regenerate simply recreates the credentials and invalidates the old ones. The client will remain connected until you restart it with the new credentials.
|
||||
|
||||
Regenerate and Disconnect recreates the credentials and invalides the old ones. The client will instantly disconnect and will require you to restart it with the new credentials.
|
||||
@@ -77,7 +77,7 @@ Restart Docker after changing this file. For background on running Docker on a r
|
||||
|
||||
### Log in or create a machine client
|
||||
|
||||
A machine client is the usual choice for a router, since it isn't tied to a user account. In the dashboard, go to Clients > Machines and create one. Copy its ID, secret, and endpoint. See [Machine Client Credentials](/manage/clients/credentials).
|
||||
A machine client is the usual choice for a router, since it isn't tied to a user account. In the dashboard, go to Clients > Machines and create one. Copy its ID, secret, and endpoint. See [Machine Clients](/manage/clients/machine-clients).
|
||||
|
||||
You can also log in as a user with `pangolin login` and run `pangolin up`, but a machine client is better suited to a long-running service.
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ A client is a way to access resources on sites remotely and privately via a virt
|
||||
|
||||
By default a client does not have access to any hosts on the local network of the site. Admins must explicitly define resources on the site and give specific users and roles access to the resources.
|
||||
|
||||
Users must log in and connect from a Pangolin client available on [Windows, Mac, Linux, iOS/iPadOS, and Android](/manage/clients/platforms). They sign in with their user credentials through a web login flow. Machines (automated systems and servers) connect with [machine client credentials](/manage/clients/credentials): an ID, secret, and endpoint.
|
||||
Users must log in and connect from a Pangolin client available on [Windows, Mac, Linux, iOS/iPadOS, and Android](/manage/clients/platforms). They sign in with their user credentials through a web login flow. Machines (automated systems and servers) connect with [machine client credentials](/manage/clients/machine-clients#credentials): an ID, secret, and endpoint.
|
||||
|
||||
## Client Types
|
||||
|
||||
@@ -19,9 +19,10 @@ There are two types of clients: user devices and machines.
|
||||
- Available for download on Mac, Windows, and Linux
|
||||
</Card>
|
||||
|
||||
<Card title="Machines">
|
||||
<Card title="Machines" href="/manage/clients/machine-clients">
|
||||
- Represent a server or automated system instead of a user
|
||||
- Connect with machine client credentials (ID and secret)
|
||||
- Can be assigned roles for private resource access
|
||||
- Available in CLI form with Pangolin CLI
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -48,7 +49,7 @@ Examples include:
|
||||
|
||||
Though you may connect a server via a user account using a CLI client, we recommend you specifically use a machine client.
|
||||
|
||||
Machine clients authenticate with [machine client credentials](/manage/clients/credentials): an ID and secret. These are passed as arguments to the Pangolin CLI. They can be revoked and rotated. User devices never use these credentials.
|
||||
Machine clients authenticate with [machine client credentials](/manage/clients/machine-clients#credentials): an ID and secret. These are passed as arguments to the Pangolin CLI. They can be revoked and rotated. User devices never use these credentials. You can also assign [roles](/manage/clients/machine-clients#grant-access-to-private-resources) to a machine client so it inherits private-resource access from those roles.
|
||||
|
||||
## Client Modalities
|
||||
|
||||
|
||||
@@ -6,8 +6,8 @@ When a client connects into an organization they will NOT have access to any res
|
||||
|
||||
Access can be granted in several ways:
|
||||
|
||||
* **Roles:** Assign access to resources to specific roles. Any user with that role will gain access to the resource when they connect.
|
||||
* **Roles:** Assign access to resources to specific roles. Any user with that role, and any [machine client](/manage/clients/machine-clients) assigned that role, gains access to the resource when they connect.
|
||||
* **Users:** Assign access to resources to specific users. Only those users will gain access to the resource when they connect.
|
||||
* **Machines:** Assign access to resources to specific machines. Only those machine clients will gain access to the resource when they connect. Note that machines can not be put into roles.
|
||||
* **Machines:** Assign access to resources to specific machine clients. Only those machine clients will gain access to the resource when they connect. You can also put machine clients into roles so they inherit the same private-resource access as that role; see [Machine Clients](/manage/clients/machine-clients#grant-access-to-private-resources) and [Users and Roles](/manage/access-control/create-user#machine-clients-and-roles).
|
||||
|
||||
When removing access to a resource, the client will automatically tear down the tunnel to that resource if there are no other resources accessible on that site.
|
||||
|
||||
Reference in New Issue
Block a user