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, 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: Connect creates and manages Linux users based on your authentication provider information.

Requirements

System requirements

• Connect server running in local execution mode (the nameservice is not supported with off-host execution)

Authentication requirements

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

• OAuth 2.0

  [Authentication]
  Provider = oauth2

• Security Assertion Markup Language (SAML)

  [Authentication]
  Provider = saml

• Lightweight Directory Access Protocol (LDAP)

  [Authentication]
  Provider = ldap

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

• Linux Pluggable Authentication Modules (PAM)

  [Authentication]
  Provider = pam

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

• Proxied Authentication

  [Authentication]
  Provider = proxy

• Password Authentication

  [Authentication]
  Provider = password

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:

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

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

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

Step 2: Configure the nameservice

Create an API key

First create an API key with viewer permissions.

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.

We are currently exploring designs that will eliminate the need for a dedicated account and the requirement for world-readable configuration files in future versions.

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:

# The key used to authenticate with the Connect nameservice API.
# The key MUST have Viewer permissions.
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:

sudo chmod 644 /etc/libnss_connect.conf

Step 3: Update NSS configuration

Edit the Name Service Switch configuration file:

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

Add the connect module to the passwd, group and shadow 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
shadow:         files connect
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.

Automatic user assignment (default)

When a user logs into Connect after you enable the nameservice, Connect:

• Uses the Connect username as the base for the Linux username, and sanitizes it for Linux compatibility if needed, and appends a hyphen followed by a unique hash (e.g., jsmith-a1b2c3) to ensure uniqueness
• Automatically generates a unique UID within your configured range (1001-65533)
• 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 hash
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:

• OAuth2: OAuth2.PosixUsernameClaim and OAuth2.PosixUIDClaim
• SAML: SAML.PosixUsernameAttribute and SAML.PosixUIDAttribute
• LDAP: LDAP.PosixUsernameAttribute and LDAP.PosixUIDAttribute

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

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

Next, test the nameservice is properly configured. Login again with your Connect user. This can be any user. It does not have to be the user used for the dedicated API key, although it can be. After logging in successfully, run the following shell command on the Linux host.

# 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.

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:

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.

Solution: Update the CONNECT_API_KEY setting in /etc/libnss_connect.conf to use an API key with Viewer permissions.

Access forbidden (403). Your CONNECT_API_KEY must have Viewer permissions.

Cause: Your API key has invalid permissions. The nameservice requires an API key with Viewer permissions.

Solution: Update the CONNECT_API_KEY setting in /etc/libnss_connect.conf to use an API key with Viewer permissions.

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 username exists in Connect
2. Make sure the user has logged into Connect at least once since you enabled the nameservice
3. 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:

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

   For Red Hat-based systems:

   sudo rm /lib64/libnss_connect.so.2

3. Remove the configuration file:

   sudo rm /etc/libnss_connect.conf