Lab 4 – Setting up Authentication

Up until now, Connect was managing authentication itself by relying on user names and passwords. During this lab, we will configure Posit Connect to use an external service to deal with authentication. There are several solutions to do this, and here, we will use the OpenID Connect (OIDC) Authentication protocol. While OIDC extends the OAuth 2.0 protocol with identity information, in practice, the terms OAuth and OIDC are often used interchangeably.

OIDC is a single-sign protocol that helps you centralize user authentication and authorization across your organization’s applications. By integrating OIDC with Connect (or other Posit products), users will authenticate with their existing credentials, eliminating the need for separate usernames and passwords, maintaining security through industry-standard authentication flows. If your infrastructure uses a different type of authentication system, refer to the Admin Guide to check the exact steps you will need to take.

Typically, the identity provider (IdP) service runs on a different server and has a different URL from your Connect service. For this lab, both run on the same server, using the same URL but different ports. Connect uses the default :443 port, and the IdP uses the port :8443. Because :443 is the default port for HTTPS, it does not need to be specified in URL. However, for the IdP, the port number will need to be included in the URL.

To integrate the IdP you use with Connect, there are two things you need to configure, the authentication (checks the identity of the user) and the authorization (determines the level of access of the user):

  1. the authentication settings allow Connect and the IdP to share information during the login flow about the identity of the user logging in;
  2. the authorization settings will determine the role in Connect the user will assume and therefore their permission level.
NoteTimings for this chapter
  • Reading time: 15 minutes
  • Documentation reading time: 25-45 minutes
  • Hands-on exercise time: 15-30 minutes
TipRequired Reading

User Roles

Before diving into the configuration settings, it is important to have a good understanding of the roles users can have in Connect.

TipCheck your understanding
  • Based on your reading on the documentation, what are the three roles that logged in users can have?

Configuring the Identity Provider

To use OAuth2 for authentication, you will need to edit the configuration file for Connect (/etc/rstudio-connect/rstudio-connect.gcfg):

  1. In the [Authentication] section, change the Provider setting from password to oauth2.
  2. Create a new section, [OAuth2] and specify values for the OpenIDConnectIssuer, the ClientId, and the ClientSecret. Additionally, you will set to true both RequireUsernameClaim and Logging. The first setting ensures to always rely on the Identity Provider to get the user name (something that the IdP used in this lab does), and the second setting provides more verbose logging which is helpful for troubleshooting.

Your configuration file should look like this:

[Authentication]
Provider = "oauth2"

[OAuth2]
OpenIDConnectIssuer = "https://<your_instance_url>:8443/realms/tisop-realm"
ClientId = "tisop-oidc-client"
ClientSecret = "yoTSR3UoZn2qYXXwyHKW422OBpWY4yM5"
RequireUsernameClaim = true
Logging = true

As a reminder to get your instance URL, you can use the command:

echo https://$HOSTNAME.$_SANDBOX_ID.instruqt.io
TipEncrypting secrets in Connect configuration file

Some parameters in your Connect configuration file might be sensitive, such as the client secret needed for the authentication flow with OIDC. These parameters can be encrypted using a command line utility that is installed with Connect called rscadmin.

The encryption process uses a key that is, by default, generated and managed by your Connect installation. The Admin Guide has more information about this encryption key and how you can manage it.

If you want to encrypt the client secret, you can use the following command, piping the secret to the command line utility:

echo yoTSR3UoZn2qYXXwyHKW422OBpWY4yM5 | sudo /opt/rstudio-connect/bin/rscadmin encrypt-config-value

Mapping groups to roles

To facilitate user management and determine their role in Connect, you can configure Connect to automatically map user roles based on the group information included in the OIDC claim.

The identity provider we use for this lab contains the following users and their associated groups:

Group Username/Password
data-science-leadership elena.rodriguez
data-science-leadership michael.zhang
data-science-leadership sarah.thompson
senior-analysts david.patel
senior-analysts jennifer.kim
senior-analysts robert.chen
data-engineers priya.gupta
data-engineers marcus.johnson
data-engineers olivia.clark
analytics-team jason.nguyen
analytics-team sophia.garcia
analytics-team thomas.wong
analytics-team aisha.mohammed

We want to configure Connect such that users in the data-science-leadership and senior-analysts are “Administrators” in Connect; and users in the analytics-team are “Publishers”. Everyone else is going to be a “Viewer”. Based on your reading of the documentation, write up the configuration needed to enable this mapping.

To configure the user role mapping, we need to add the [Authorization] section to the configuration file:

[Authorization]
UserRoleGroupMapping = true
AdministratorRoleMapping = "data-science-leadership"
AdministratorRoleMapping = "senior-analysts"
PublisherRoleMapping = "analytics-team"

Groups that are not listed in the configuration file will have the role “Viewer”. Therefore, the groups research-interns and data-engineers do not need to be listed here. Note that you can use the setting Authorization.DefaultUserRole to specify the role unlisted groups will be given.

Checking that everything is working

Now that all the settings are in place to integrate the identity provider with Connect, let’s check that everything is working as expected.

  1. Restart Connect sudo systemctl restart rstudio-connect.service.
  2. Navigate to the ‘Posit Connect’ tab, click on the circular arrow to refresh the page, and click on “Log in”.
  3. Log in as the first user in the table above, using elena.rodriguez as both the user name and the password. If all goes well, you should see the “Jump Start Examples” screen. Close it.
  4. Navigate to the “People” entry in the top navigation bar. You should see a single user, elena.rodriguez with the “Administrator” role.

What you should see in the list of users after logging in as Elena Rodriguez

Note that by default, Connect is configured to create users on first log in (this is called “just in time provisioning”). Even though the identity provider knows about other users, they will not exist in Connect before they log in. For this lab, if you want to create additional users, the easiest way is to use private browsing or a different browser to open the URL of your Connect instance and log in using any of the users listed in the table above (the passwords are the same as the user names).

NoteLogging Out

Because the authentication part is handled outside of Connect by the Identity Provider service, when you click on “Log Out” in Connect, you do not log out from the session started by your Identity Provider. To fully log out, you also need to log out the user from the identity provider.

Note that these steps only work when you visit your instance URL (not the tab in Instruqt). It is not possible to fully log out from Connect in a session started within the Instruqt tab.

  1. Visit https://<your_instance_url>:8443/realms/tisop-realm/protocol/openid-connect/logout, and confirm that you want to log out
  2. Click on “Log Out” in Connect.

When you click on “Log In” again in Connect, you should be prompted for a user name and password. You can log back in using any of the users listed in the table above.

You can click the “Check” button to verify that you completed all the steps for this lab.

Troubleshooting

If you encounter any issues, the Connect logs might include information to help you troubleshoot. For instance to inspect the last 100 lines of the log:

sudo tail -100 /var/log/rstudio/rstudio-connect/rstudio-connect.log

Check your understanding

After completing this lab, you should be able to answer the following questions:

  1. Authentication vs Authorization: What is the difference between authentication and authorization in the context of Posit Connect?

  2. Role Mapping Configuration: If you wanted to configure Connect so that users in the group “data-managers” become Publishers and users in “executive-team” become Administrators, what configuration sections and settings would you need to add to the Connect configuration file?

  3. Troubleshooting OIDC: You’ve configured OIDC authentication but users are unable to log in. What are specific steps you could take to diagnose and troubleshoot this issue?

  1. Authentication verifies who the user is. It confirms their identity through credentials like usernames/passwords or external identity providers (like OIDC). In Posit Connect, authentication determines whether a user can access the system at all. Authorization determines what the authenticated user can do. It controls their permissions and access levels within Connect. Authorization assigns roles (Administrator, Publisher, Viewer) that define what actions users can perform.

  2. To configure Connect so that “data-managers” become Publishers and “executive-team” become Administrators, you would need to add the following to the [Authorization] section:

    AdministratorRoleMapping = "executive-team"
PublisherRoleMapping = "data-managers"

  3. If users cannot log in after configuring OIDC authentication, following these steps might help diagnose the issue:

    • Check that the configuration values are correct:
      • Confirm OpenIDConnectIssuer URL is correct and accessible from the Connect instance
      • Check ClientId and ClientSecret match the identity provider settings.
    • Enable verbose logging by adding Logging = true to the [OAuth2] section, and restart the Connect service.
    • Check the logs with sudo tail -100 /var/log/rstudio/rstudio-connect/rstudio-connect.log
    • Check user claims: verify the identity provider is sending the expected user information (especially if RequireUsernameClaim = true).

Looking back, Planning ahead

In this lab, we only scratched the surface of what Connect can do when it comes to integrating with authentication systems and user management. The documentation provides more information on how to integrate with other systems, and how to manually or automatically map attributes from your authentication system with the roles available in Connect.

As you plan the installation of Connect on your own infrastructure:

  • Do you know where you will be able to get the information you need to integrate your authentication system with Posit Connect? (e.g., Client URL, ID, and Secret for OIDC)
  • How are you going to decide the Connect roles user will have in your organization?