Nameservice

Enhanced Advanced

The Connect Nameservice enables current user execution for Connect installations using OAuth2, SAML, or LDAP authentication providers 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 /etc/passwd and /etc/group files. By default, when the Applications.RunAsCurrentUser setting is enabled, Connect will automatically create a unique Unix account for each Connect user upon login. Optionally, you can associate existing Unix accounts with Connect users through your authentication provider mappings.

For a step-by-step walkthrough of enabling current user execution end to end, see the Run content as the current user how-to guide.

Use case

The nameservice supports per-user data access. Each user’s content runs under their own Unix account, so you can control access to data on a shared filesystem using standard Unix filesystem permissions.

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 a service token to access the Connect API. Service tokens provide fine-grained access control and do not consume license seats. Use the Create service token API endpoint to create a service token with the nameservice:read scope. Copy the returned key value to the CONNECT_API_KEY setting below.

Connect stores this token in a world-readable configuration file. For the implications and how to limit the exposure, see Security considerations.

Create the configuration file

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

/etc/libnss_connect.conf
# The service token used to authenticate with the Connect nameservice API.
# Use a service token with the nameservice:read scope.
CONNECT_API_KEY=your-service-token-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 Unix accounts. If your provider doesn’t support custom user attributes, or you choose not to configure them, Connect will automatically create a unique Unix account for each Connect user once the Applications.RunAsCurrentUser setting is enabled (see Step 5).

Automatic user assignment (default)

When a user logs into Connect after you enable the Applications.RunAsCurrentUser setting, Connect:

  • Uses the Connect username as the base for the Unix username, sanitizes it for Unix 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 Unix 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 Unix username to use No Uses sanitized Connect username with appended UID
posix_uid Unix 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 Unix accounts until you enable the Applications.RunAsCurrentUser 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 option to enable current user execution with the nameservice:

/etc/rstudio-connect/rstudio-connect.gcfg
[Applications]
RunAsCurrentUser = true

You must enable the Applications.RunAsCurrentUser 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 Applications.RunAsCurrentUser setting enabled, test that the nameservice is properly configured. Login with your Connect user. This can be any user. 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 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>"

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:
  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 Unix 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 Unix supplementary group during current user execution. This allows content processes to access files owned by those Unix 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 service token.

Solution: Update the CONNECT_API_KEY setting in /etc/libnss_connect.conf to use a service token with the nameservice:read scope.

Access forbidden (403). Your CONNECT_API_KEY must be a service token with the nameservice:read scope.

Cause: Your service token has invalid permissions.

Solution: Update the CONNECT_API_KEY setting in /etc/libnss_connect.conf to use a service token with the nameservice:read scope.

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 Applications.RunAsCurrentUser 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 Applications.RunAsCurrentUser setting and restarted Connect
  4. Check that you’re using the correct Unix username (which may differ from the Connect username)

Security considerations

  • The nameservice configuration file must be world-readable, for example mode 0644. Every process on the system uses the Name Service Switch (NSS) module, and these processes can run under any user, so they all need read access. As a result, every user on the system can read the service token that the file contains.
  • To limit this exposure, scope the service token to the nameservice:read scope only, monitor its usage through Connect’s audit logs, and rotate it regularly 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