Nameservice

Enhanced Advanced

The Connect Nameservice enables current user execution for Connect installations using OAuth2, SAML, or LDAP authentication providers. It acts as a bridge between your existing Connect users and the Linux user by acting as a Name Service Switch (NSS) module. This module allows Linux to retrieve user and group information from Connect instead of relying on the traditional /etc/passwd and /etc/group files. By default, when the EarlyAccess.RunAsCurrentUserSSO setting is enabled, Connect will automatically create a unique Linux user for each Connect user upon login. Optionally, you can associate existing Linux users with Connect users through your authentication provider mappings.

Use cases

  • Application process isolation: Each user’s content runs under their own Linux account.
  • Automatic Linux user provisioning: When enabled, Connect creates and manages Linux users based on your authentication provider information.

Requirements

Authentication requirements

The nameservice requires one of the following federated authentication provider configurations:

  • OAuth 2.0

    /etc/rstudio-connect/rstudio-connect.gcfg
    [Authentication]
Provider = oauth2

  • Security Assertion Markup Language (SAML)

    /etc/rstudio-connect/rstudio-connect.gcfg
    [Authentication]
Provider = saml

  • Lightweight Directory Access Protocol (LDAP)

    /etc/rstudio-connect/rstudio-connect.gcfg
    [Authentication]
Provider = ldap

The nameservice is not required for PAM authentication. See the Process Management guide for additional information.

  • Linux Pluggable Authentication Modules (PAM)

    /etc/rstudio-connect/rstudio-connect.gcfg
    [Authentication]
Provider = pam

Current user execution is not supported with the following authentication providers:

  • Proxied Authentication

    /etc/rstudio-connect/rstudio-connect.gcfg
    [Authentication]
Provider = proxy

  • Password Authentication

    /etc/rstudio-connect/rstudio-connect.gcfg
    [Authentication]
Provider = password

Installation

Choose the installation method that matches your Connect deployment:

Local execution installation

Complete these steps on your Linux server. If you are using a load-balanced configuration, repeat them on each server in the cluster.

Step 1: Install the nameservice module

Your Connect distribution package contains the nameservice module and an installation script.

We recommend first examining the script to understand its actions:

Terminal
cat /opt/rstudio-connect/extras/nameservice/activate-nameservice.sh

Once you’ve reviewed the script, run it as root to install the nameservice module:

Terminal
sudo /opt/rstudio-connect/extras/nameservice/activate-nameservice.sh

Step 2: Configure the nameservice

Create authentication credentials

The nameservice requires authentication to access the Connect API. You have two options:

Option 2: Viewer API key (deprecated)
Warning

Viewer API key support in the nameservice is deprecated and will be removed in a future release. Migrate to service tokens (Option 1).

Warning

All processes on the system utilize the Name Service Switch (NSS) module. Since these processes can run under any user, the configuration file must have world-readable permissions (e.g., 0644). As a result, every Linux user will have read access to the configuration file that contains the API key.

To minimize risk, the API key should be limited to viewer permissions only. The Connect server will reject any API key with publisher or administrator rights.

We strongly recommend creating a dedicated, non-admin “viewer” account for the Name Service. This account should have no permissions beyond read-only access.

  1. Sign into Connect as the user you intend to own the nameservice API key.
  2. Click on your user profile in the header and select Manage Your API keys.
  3. Click the New API Key button.
  4. Choose a name. We recommend using “Connect Nameservice”.
  5. Select Viewer permissions. The nameservice will not work with any other permission level.
  6. Copy the generated key to the CONNECT_API_KEY setting below.

Create the configuration file

Then create a configuration file at /etc/libnss_connect.conf with the following contents:

/etc/libnss_connect.conf
# The key used to authenticate with the Connect nameservice API.
# Use a service token with nameservice:read scope (recommended) or a Viewer API key.
CONNECT_API_KEY=your-api-key-here

# The Connect server URL
# Replace with your Connect server URL
CONNECT_SERVER=https://your-connect-server.com

Set appropriate permissions for the configuration file so all users on the system can read it:

Terminal
sudo chmod 644 /etc/libnss_connect.conf

Step 3: Update NSS configuration

Edit the Name Service Switch configuration file:

Terminal
sudo cp /etc/nsswitch.conf /etc/nsswitch.conf.bak
sudo nano /etc/nsswitch.conf

Add the connect module to the passwd, group, and initgroups databases. Your configuration file may look different and contain additional fields. Always place connect after files. In most cases, add connect as the last entry in the list.

/etc/nsswitch.conf
#
# Example configuration of GNU Name Service Switch functionality.
# If you have the `glibc-doc-reference' and `info' packages installed, try:
# `info libc "Name Service Switch"' for information about this file.

passwd:         files connect
group:          files connect
initgroups:     files connect
shadow:         files
gshadow:        files

hosts:          files dns
networks:       files

protocols:      db files
services:       db files
ethers:         db files
rpc:            db files

netgroup:       nis

(Optional) Step 4: Configure user mappings

If your authentication provider supports it, you can configure attributes that map Connect users to specific Linux users. If your provider doesn’t support custom user attributes, or you choose not to configure them, Connect will automatically create a unique Linux user for each Connect user once the EarlyAccess.RunAsCurrentUserSSO setting is enabled (see Step 5).

Automatic user assignment (default)

When a user logs into Connect after you enable the EarlyAccess.RunAsCurrentUserSSO setting, Connect:

  • Uses the Connect username as the base for the Linux username, sanitizes it for Linux compatibility if needed, and appends a hyphen followed by the generated UID (e.g., jsmith-29007) to ensure uniqueness. If that username is already taken, it appends the Connect user ID as well (e.g., jsmith-29007-123)
  • Automatically generates a unique UID within your configured range (see Nameservice.MinUID and Nameservice.MaxUID)
  • Applies the GID from your Applications.SharedRunAsUnixGroup setting

Custom user mappings via authentication provider

For environments that require predefined usernames for Connect users, you must configure custom user attributes in your authentication provider. These attributes let you map specific Linux usernames and UIDs to Connect users.

All supported authentication providers (OAuth2, SAML, and LDAP) use these standard attribute/claim names:

Attribute Purpose Required Default Behavior (when attribute is missing)
posix_username Linux username to use No Uses sanitized Connect username with appended UID
posix_uid Linux UID to assign No Auto assigns a unique UID within configured range

You can customize these attribute/claim names in your Connect configuration if needed:

Important

UID Conflicts: When you specify posix_uid values, make sure they remain unique across all users and stay within the configured Nameservice.MinUID to Nameservice.MaxUID range. Duplicate UIDs cause authentication failures and prevent users from accessing their content.

Step 5: Enable current user execution

Important

Required for user creation: The nameservice will not create Linux users until you enable the EarlyAccess.RunAsCurrentUserSSO setting. Installing the nameservice module (Steps 1-3) alone is not sufficient - this configuration setting must be enabled for automatic user provisioning to work.

Set the required configuration options to enable current user execution with the nameservice:

/etc/rstudio-connect/rstudio-connect.gcfg
[EarlyAccess]
RunAsCurrentUserSSO = true

[Applications]
RunAsCurrentUser = true

You must enable the EarlyAccess.RunAsCurrentUserSSO setting to use current user execution with OAuth2, SAML, or LDAP authentication providers.

After configuration, restart Connect.

Step 6: Verification

After restarting Connect with the EarlyAccess.RunAsCurrentUserSSO setting enabled, test that the nameservice is properly configured. Login with your Connect user (this can be any user - it does not have to be the user used for the dedicated API key). After logging in successfully, run the following shell command on the Linux host.

Terminal
# Test user lookup by username
getent passwd username

A successful lookup returns your user information in standard passwd format:

username:x:1000:1000:Full Name:/home/username:/bin/bash

If the lookup is not successful, proceed to the Troubleshooting section.

The Connect nameservice is now properly configured. You can now configure content to run using current user execution. See the User Guide for additional information.

Off-host (Kubernetes) installation

When running Connect with off-host execution on Kubernetes, the Connect Helm chart handles nameservice configuration automatically. The Helm chart configures /etc/nsswitch.conf and /etc/libnss_connect.conf in the Connect container.

Step 1: Create authentication credentials

Create a service token or API key following the same instructions as for local execution.

Step 2: Configure the Helm chart

Add the following to your values.yaml file:

values.yaml
nameservice:
  enabled: true
  apiKey: "<your-service-token-or-api-key>"

Alternatively, you can provide an existing Kubernetes secret containing the libnss_connect.conf file instead of specifying the API key directly. First, create the secret in the same namespace as your Connect deployment:

Terminal
kubectl create secret generic my-nameservice-secret \
  --from-file=libnss_connect.conf=/path/to/libnss_connect.conf \
  --namespace <your-connect-namespace>

Then reference the secret in your values.yaml:

values.yaml
nameservice:
  enabled: true
  secretName: "my-nameservice-secret"

Step 3: Enable current user execution

Add the Connect configuration settings to enable current user execution:

values.yaml
config:
  EarlyAccess:
    RunAsCurrentUserSSO: true
  Applications:
    RunAsCurrentUser: true

Step 4: Deploy

Deploy or upgrade your Helm release with the updated values:

Terminal
helm upgrade --install connect rstudio/rstudio-connect \
  --namespace <your-connect-namespace> \
  -f values.yaml

Configuring supplementary groups

Connect group memberships determine Linux supplementary group memberships. When you assign a POSIX Group ID (GID) to a Connect group, all members of that group inherit the GID as a Linux supplementary group during current user execution. This allows content processes to access files owned by those Linux groups.

Administrators can assign GIDs to groups using the PATCH /v1/groups/{guid} API endpoint.

Nameservice configuration options

Please refer to the Nameservice Configuration section for additional details.

Troubleshooting

Enable debug logging

Enable debug logging for the nameservice module to diagnose issues:

Terminal
export RUST_LOG='nss_connect=debug'

After setting this environment variable, all calls to the nameservice (like getent passwd username) will output detailed messages to stderr. The system shows error-level logs by default, use this setting to see more detailed logs.

Errors

Authentication

Authentication failed (401). Your CONNECT_API_KEY may be empty or invalid.

Cause: You have a missing or invalid API key or service token.

Solution: Update the CONNECT_API_KEY setting in /etc/libnss_connect.conf to use a service token with nameservice:read scope (recommended) or a Viewer API key.

Access forbidden (403). Your CONNECT_API_KEY must be a user API key with Viewer permissions or a service token with nameservice:read scope.

Cause: Your API key or service token has invalid permissions.

Solution: Update the CONNECT_API_KEY setting in /etc/libnss_connect.conf to use a service token with nameservice:read scope (recommended) or a Viewer API key.

Connection

Request failed: io: Connection refused. Please check your network connectivity and CONNECT_SERVER configuration.

Cause: The nameservice module cannot connect to your Connect server.

Solution:

  1. Check that your CONNECT_SERVER URL in /etc/libnss_connect.conf is correct
  2. Verify that your Connect server is running and accessible
  3. Check for network/firewall issues blocking communication

User lookup

Not found (404). The requested user or group does not exist.

Cause: The nameservice module tried to look up a user or group that doesn’t exist in Connect’s nameservice database.

Solution:

  1. Verify that the EarlyAccess.RunAsCurrentUserSSO setting is enabled in your Connect configuration
  2. Verify that the username exists in Connect
  3. Make sure the user has logged into Connect at least once after you enabled the EarlyAccess.RunAsCurrentUserSSO setting and restarted Connect
  4. Check that you’re using the correct Linux username (which may differ from the Connect username)

Security considerations

  • The nameservice configuration file contains sensitive API credentials
  • Monitor API key usage through Connect’s audit logs
  • Regularly rotate API keys according to your security policies
  • You cannot use the nameservice with the Authorization.ViewersCanOnlySeeThemselves setting. Connect will fail to start if you enable both. This creates a security conflict: the nameservice must expose user information for SSO current user execution, which contradicts how ViewersCanOnlySeeThemselves restricts viewers from seeing other users.

Uninstalling

To remove the nameservice:

  1. Remove connect from /etc/nsswitch.conf

  2. Remove the symbolic link:

    For Debian-based systems:

    Terminal
    sudo rm /lib/x86_64-linux-gnu/libnss_connect.so.2

    For Red Hat-based systems:

    Terminal
    sudo rm /lib64/libnss_connect.so.2

  3. Remove the configuration file:

    Terminal
    sudo rm /etc/libnss_connect.conf