> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-6-0/access/user-management/initial-setup.md).

# Initial User Management Setup

Work through these steps in order to take a new installation from its default credentials to a secure, role-based access setup ready for your team.

## Prerequisites

* Connectware is installed and running.
* You have access to the default `admin` account, which is created automatically during installation.
* You have access to the `values.yaml` file (Kubernetes) or `.env` file (Docker) if you plan to configure SSO or MFA.

{% stepper %}
{% step %}

### Change the Default Admin Password

The default `admin` user is created with an initial password during installation. Change it before you do anything else.

{% hint style="warning" %}
On Docker, the default password is identical across all Connectware installations. Change it before the system goes live to prevent unauthorized access.
{% endhint %}

For instructions, see [Changing User Passwords](/2-6-0/access/user-management/users.md#changing-user-passwords).
{% endstep %}

{% step %}

### Define Your Roles

Before creating users, design the roles that reflect your organization's responsibilities. This is easier to do up front than to reorganize later.

For example:

| Role name  | Intended for                                     | Suggested permissions                       |
| ---------- | ------------------------------------------------ | ------------------------------------------- |
| `operator` | Production staff who need to monitor data        | Read access on relevant MQTT topics         |
| `engineer` | Engineers who configure services and connections | Read/write access on service-related topics |

{% hint style="info" %}
Connectware includes the built-in roles `connectware-admin` (full access) and `minimum-access` (read-only Admin UI access, no data permissions). You do not need to create these — assign them directly to users.
{% endhint %}

For how to create and configure roles, see [Roles](/2-6-0/access/user-management/roles.md). For permission syntax, see [Permissions](/2-6-0/access/user-management/permissions.md).
{% endstep %}

{% step %}

### Create Your Users

With roles defined, create a user account for each person who needs access. Assign roles rather than individual permissions. This keeps your access control consistent and easy to audit.

For how to create users and assign roles, see [Users](/2-6-0/access/user-management/users.md).
{% endstep %}

{% step %}

### Disable the Default Admin Account

Once you have at least one other user with the `connectware-admin` role, disable the default `admin` account to remove a known, predictable account name from your system.

{% hint style="warning" %}
Do not disable the default admin account until you have confirmed that at least one other user with the `connectware-admin` role can log in successfully. Recovering from a lockout requires direct access to the configuration files.
{% endhint %}

For instructions, see [Default Admin User](/2-6-0/access/user-management/users/default-admin-user.md).
{% endstep %}

{% step %}

### Choose Your Authentication Strategy

Decide how users authenticate. Your options are:

| Method                                    | Best for                                                                                           |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Local username/password                   | Small teams, isolated networks, or when no corporate directory is available                        |
| Single Sign-On (SSO) via Entra ID or LDAP | Organizations with an existing identity provider, where users log in with their corporate accounts |

These methods are not mutually exclusive. You can run local users alongside SSO users.

If your environment requires a second authentication factor, enable multi-factor authentication (MFA) on top of local or LDAP accounts. MFA does not replace your authentication method — it adds a one-time password step on top of it.

* To set up SSO, see [Single Sign-On](/2-6-0/access/user-management/single-sign-on-sso.md).
* To enable MFA, see [Multi-Factor Authentication](/2-6-0/access/user-management/multi-factor-authentication.md).
  {% endstep %}

{% step %}

### Configure Machine and Device Access

If machines or devices need to connect to Connectware over MQTT, do not create regular user accounts for them. Use one of these approaches instead:

* **Client Registry** — for managed device onboarding with controlled approval and certificate support. See [Client Registry](/2-6-0/access/client-registry.md).
* **MQTT client authentication** — for simpler setups where devices authenticate with username/password or mTLS certificates. See [MQTT Client Access](/2-6-0/access/user-management/mqtt-user-authentication.md).
  {% endstep %}
  {% endstepper %}

## What's Next

At this point, your Connectware installation has a secure user management baseline: the default credentials are changed, roles reflect your team's responsibilities, users have appropriate access, and machines connect without shared user accounts.

As your needs grow, explore these topics:

* [User Session Expiration](/2-6-0/access/user-management/users/user-session-expiration.md) — configure how long sessions stay active before requiring re-authentication.
* [Access Control for Admin UI](/2-6-0/access/user-management/access-permissions-for-admin-ui.md) — restrict which Admin UI features are visible to each role.
* [Adding an MQTT Publish Prefix](/2-6-0/access/user-management/mqtt-user-authentication/adding-an-mqtt-publish-prefix.md) — route MQTT traffic automatically for high-throughput clients.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-6-0/access/user-management/initial-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.