OpenID Connect Scope Mapping Guide

Advanced

About Scope Mapping

Package Manager uses scope-based access control to determine what actions users can perform. When using OpenID Connect authentication, you can map user groups and roles from your identity provider to specific Package Manager scopes, providing fine-grained access control without manual user management.

Scope mapping allows you to:

  • Automate access control: Automatically grant appropriate permissions based on group membership or user roles
  • Centralize permissions: Manage access through your existing identity provider rather than maintaining separate user lists
  • Scale efficiently: New users automatically receive appropriate permissions based on their group assignments
  • Maintain security: Ensure users only have access to the repositories and features they need for their role

This guide provides detailed examples for configuring these mappings. For basic OpenID Connect setup, see the provider-specific guides for Okta, Microsoft Entra ID, or other OpenID Connect providers.

Understanding Package Manager Scopes

Package Manager uses scopes to control access to different features and repositories. Each scope grants specific permissions:

Administrative Scopes

  • global:admin: Full administrative access to Package Manager
  • metadata:admin: Full access to manage custom metadata
  • blocklist:admin: Full access to manage the package blocklist
  • blocklist:read: Read-only access to view the blocklist

Content Management Scopes

  • sources:write:<sources>: Upload packages, manage sources, create Git builders
  • repos:read:<repos>: Download packages from authenticated repositories

Basic Scope Assignment

The simplest approach is to assign default scopes to all users authenticating through OpenID Connect:

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
; Give all users read access to repositories
Scope = "repos:read:*"

Group-Based Scope Mapping

Use GroupToScopeMapping sections to assign scopes based on group membership. Each section maps a group name to one or more scopes.

Example: Department-Based Access

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
Issuer = "https://your-org.okta.com"
ClientId = "your-client-id"
ClientSecret = "your-client-secret"

; Basic read access for all authenticated users
Scope = "repos:read:*"

; Data Science team gets source upload privileges
[GroupToScopeMapping "data-science"]
Scope = "sources:write:*"

; DevOps team gets administrative access
[GroupToScopeMapping "devops"]
Scope = "global:admin"

; QA team gets metadata management access
[GroupToScopeMapping "qa-team"]
Scope = "metadata:admin"
Scope = "blocklist:admin"

Example: Role-Based Access with Multiple Groups

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
Issuer = "https://login.microsoftonline.com/tenant-id/v2.0"
ClientId = "your-client-id"
ClientSecret = "your-client-secret"

; Developers can upload to their team sources
[GroupToScopeMapping "R-Developers"]
Scope = "sources:write:local-r1,local-r2"

[GroupToScopeMapping "Python-Developers"]
Scope = "sources:write:local-py1,local-py2"

; Team leads get additional metadata privileges
[GroupToScopeMapping "Team-Leads"]
Scope = "sources:write:*"
Scope = "metadata:admin"

; IT administrators get full access
[GroupToScopeMapping "IT-Admins"]
Scope = "global:admin"

Example: Granular Repository Access

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
Issuer = "https://your-provider.com"
ClientId = "your-client-id"
ClientSecret = "your-client-secret"

; Repositories accessible to all employees
[GroupToScopeMapping "employees"]
Scope = "repos:read:internal-all-employees"

; Internal development repositories for developers only
[GroupToScopeMapping "developers"]
Scope = "repos:read:internal-dev"

; Research team gets access to specialized repositories
[GroupToScopeMapping "research-team"]
Scope = "repos:read:internal-research"
Scope = "metadata:admin"

Role-Based Scope Mapping

When your OpenID Connect provider sends role information in user claims, you can define the RoleClaim setting to make Package Manager aware of user roles. If the roles received from the ID token match PPM token scopes, then the user will be granted those scopes automatically. You can also define RoleToScopeMapping sections to map scopes based on user roles. This is useful for scenarios where roles are more relevant than group memberships.

If your OpenID Connect provider sends a roles claim with values like global:admin, sources:write:local-source,internal-2, or repos:read:*, these roles will automatically map to Package Manager scopes.

If your OpenID Connect provider sends a roles claim with values like admin, developer, and analyst, you can map these roles to specific scopes:

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
Issuer = "https://your-provider.com"
ClientId = "your-client-id"
ClientSecret = "your-client-secret"
; You must define a RoleClaim to use role-based mappings
RoleClaim = "roles"

[RoleToScopeMapping "admin"]
Scope = "global:admin"

[RoleToScopeMapping "developer"]
Scope = "sources:write:*"
Scope = "repos:read:*"

[RoleToScopeMapping "analyst"]
Scope = "repos:read:*"

[RoleToScopeMapping "manager"]
Scope = "repos:read:*"
Scope = "metadata:admin"

Advanced Mapping Scenarios

Combining Group and Role Mappings

You can use both group and role mappings simultaneously. Users receive scopes from all applicable mappings:

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
Issuer = "https://your-provider.com"
ClientId = "your-client-id"
ClientSecret = "your-client-secret"
RoleClaim = "job_title"

; Base access by role
[RoleToScopeMapping "Data Scientist"]
Scope = "repos:read:*"

[RoleToScopeMapping "DevOps Engineer"]
Scope = "sources:write:*"
Scope = "repos:read:*"

; Additional privileges by group membership
[GroupToScopeMapping "senior-staff"]
Scope = "metadata:admin"

[GroupToScopeMapping "security-team"]
Scope = "blocklist:admin"

[GroupToScopeMapping "ppm-admins"]
Scope = "global:admin"

Handling Complex Group Names

Some identity providers use complex group names with spaces or special characters:

/etc/rstudio-pm/rstudio-pm.gcfg
[GroupToScopeMapping "Engineering - Data Platform"]
Scope = "sources:write:*"
Scope = "metadata:admin"

[GroupToScopeMapping "IT/Security/Admins"]
Scope = "global:admin"

[GroupToScopeMapping "Contractors (External)"]
Scope = "repos:read:*"

Using Group/Role Separators

If your provider sends groups or roles as delimited strings:

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
Issuer = "https://your-provider.com"
ClientId = "your-client-id"
ClientSecret = "your-client-secret"
GroupsSeparator = ","
RolesSeparator = ";"

; Now groups like "admin,developer,qa" will be split into separate groups
[GroupToScopeMapping "admin"]
Scope = "global:admin"

[GroupToScopeMapping "developer"]
Scope = "sources:write"

[GroupToScopeMapping "qa"]
Scope = "repos:read"
Scope = "blocklist:read"

; Similarly, roles like "devops;managers" will be split into separate roles
[RoleToScopeMapping "devops"]
Scope = "sources:write:*"
Scope = "repos:read:*"

[RoleToScopeMapping "managers"]
Scope = "repos:read:*"

Troubleshooting Scope Mappings

Enable Verbose Logging

When debugging scope mappings, enable detailed logging:

/etc/rstudio-pm/rstudio-pm.gcfg
[OpenIDConnect]
Logging = true

[Logging]
SystemLogLevel = DEBUG

Common Issues

  1. Groups not mapping: Verify that group names in your configuration exactly match those sent by your provider (case-sensitive).

  2. Missing scopes: Check that users are actually members of the expected groups in your identity provider.

  3. Scope conflicts: Remember that users receive scopes from ALL applicable mappings - both base scopes and group/role mappings.

Testing Scope Assignments

To verify that your scope mappings are working correctly, you can use several methods to test and validate the assigned scopes:

Method 1: Log Analysis

Enable verbose logging and examine the Package Manager logs during user authentication:

  1. Enable verbose logging in your configuration
  2. Have a user authenticate through the OpenID Connect flow
  3. Search the logs for entries indicating scope assignments and token claims

The logs will show:

  • Group and role claims received from your identity provider
  • Scope mappings applied based on those claims
  • Final set of scopes granted to the user

Method 2: Token Inspection

Use the Package Manager CLI to test the authentication flow and inspect the resulting token:

  1. Test the login flow:

    rspm login sso

  2. Retrieve the token from the local token storage:

    cat ~/.ppm/tokens.toml

  3. Decode and inspect the JWT token using command-line tools or online JWT decoders to verify that the expected Package Manager scopes are present in the token claims.

This method allows you to directly verify that users receive the correct scopes without needing to parse log files.

Back to top