Restore administrator access

If no one can sign in to Posit Connect as an administrator, you can make an existing user an administrator from the Connect host. This usually happens if every administrator leaves the organization, or when a change of authentication provider leaves the old administrator accounts unusable.

You need root or sudo access on a Connect host. You do not need to stop Connect.

Which procedure to use depends on where user roles come from:

Note

If you are not sure which case applies, start with restore-admin. When your identity provider manages roles, the command unlocks and confirms the account, but it does not change the role. It then tells you which role setting to check.

Restore a user

  1. Make sure the user has a Connect account.

    The command changes an existing account and cannot create one. Connect creates the account at the first sign-in.

  2. Find the user’s account:

    Terminal
    sudo /opt/rstudio-connect/bin/connect restore-admin --find alice

    You can search by username or by email address. The output lists every account that matches:

    Authentication provider: ldap

GUID                                  USERNAME  EMAIL              ROLE    LOCKED  CONFIRMED  LAST ACTIVE
6f300623-1e0c-48e6-a473-ddf630c0c0c3  alice     alice@example.com  viewer  no      yes        2026-09-28T09:21:07Z
b2a4e1f0-5c1d-4d59-9b4e-2f0e6a1c7d88  alice     alice@old.example  viewer  yes     yes        2024-02-11T16:05:44Z

    Some authentication providers allow two accounts with the same username. Use the email address and the last active time to pick the right one. In this example, the first account belongs to the current user, and the second is an old, locked account.

  3. Restore the account. Copy its globally unique identifier (GUID) from the first column, and pass it to --user-guid:

    Terminal
    sudo /opt/rstudio-connect/bin/connect restore-admin --user-guid 6f300623-1e0c-48e6-a473-ddf630c0c0c3

    The command takes a GUID, not a username, so it never changes the wrong account when two accounts share a username. It makes three changes to the account:

    • It sets the role to administrator.
    • It unlocks the account, so the user can sign in.
    • It confirms the account, because Connect rejects most requests from accounts that are not confirmed.

  4. Wait up to 30 seconds for Connect to reload its role-based access control policy, and then ask the user to reload Connect in the browser.

    The user does not need to sign out, and you do not need to restart Connect. If the role still does not apply, restart Connect.

    Each API key keeps the role that it had when the user created it. If a key has a role lower than administrator, the user must create a new key to call the API as an administrator.

Users with password authentication

If the user signs in with password authentication, the command also prints a link to set a new password. This helps when the user forgot the password and Connect cannot send email:

Password reset link: https://connect.example.com/__login__?passwordreset=1&user=alice&utoken=...

Send the link to the user over a secure channel. The link works for 24 hours. Connect prints the link to your terminal only and does not write it to any log file.

The command builds the link from the Server.Address setting. If Server.Address is empty, the command still restores the account, but it cannot print a link. Set Server.Address, and then run the command again to get the link.

Use a different configuration file

The command reads the same configuration file as the Connect server, /etc/rstudio-connect/rstudio-connect.gcfg. If your server uses a different file, pass it with --config:

Terminal
sudo /opt/rstudio-connect/bin/connect restore-admin --config /path/to/rstudio-connect.gcfg --find alice

Audit records

The command records each change in the audit log. If you configure an audit log file, the command also writes each change to that file. If you set Logging.AuditLog to STDOUT or STDERR, the command writes each change to the terminal where it runs, not to the log of the Connect server. These entries show that the change came from host recovery, so you can tell them apart from changes that an administrator made in Connect.

If the command reports a schema version mismatch

The command never changes the structure of the database. It stops with an error if the database does not match the installed version of Connect. This happens after an upgrade if Connect did not start on the new version yet. Start Connect one time so that it updates the database, and then run the command again.

Roles from the identity provider

If your identity provider sets user roles, restore-admin does not change the role. Your identity provider sets roles if you use LDAP, SAML, OAuth2, or proxied authentication, and you configure one of these settings:

The command still unlocks and confirms the account, and it prints the setting that controls the role.

To restore access, give the user the administrator role in the identity provider. For example, add the user to the group that maps to the administrator role. If the account is locked in Connect, also run restore-admin --user-guid for the account, as in Restore a user. Then ask the user to sign in again, so that Connect applies the new role. With LDAP, Connect caches group membership for LDAP.CacheTTL. If the user still has the old role, wait for that time or restart Connect, and then ask the user to sign in again.

To learn how Connect maps roles, see the section about automatic user role mapping for your authentication provider:

Connect has no users

If Connect has no users, the first user to sign in becomes an administrator. You do not need restore-admin.

If you want an administrator API key before anyone signs in, use the bootstrap process in Programmatic provisioning.