mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-08 05:56:45 +00:00
53 lines
2.7 KiB
Plaintext
53 lines
2.7 KiB
Plaintext
---
|
|
title: "Client Credentials"
|
|
description: "Understanding how client credentials work and how they can be rotated & regenerated"
|
|
---
|
|
|
|
## Understanding Credentials
|
|
|
|
Every machine client is provisioned with a unique identifier (ID), secret, and endpoint. The client uses the combination of these three to establish a secure, encrypted connection to the server.
|
|
|
|
User devices use a special combination of credentials and temporary session tokens tied to the user account. Therefore, these credentials are obscured and can not be regenerated for user devices. To invalidate a user device, the user should logout via the client of choice.
|
|
|
|
### 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 only feature.
|
|
</Note>
|
|
|
|
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.
|