Authentication

Authenticated Repositories

EnhancedAdvanced

Package Manager supports authenticated repositories via Basic HTTP authentication. This feature allows you to create repositories that restrict access to users with an API token.

To create an authenticated repository, you must create an API token and then use the token to access the repository. At a high level, the steps should include:

1. Require Authentication for the repository.

   You can create a new repository that requires authentication by running rspm create repo with the --authenticated flag:

   # Create an authenticated CRAN repository:
   rspm create repo --name=cran --description='Access CRAN packages' --authenticated
   rspm subscribe --repo=cran --source=cran
   
   # Create an authenticated PyPI repository:
   rspm create repo --name=pypi --type=python --description='Access PyPI packages' --authenticated
   rspm subscribe --repo=pypi --source=pypi
   
   # Create an authenticated Bioconductor repository:
   rspm create repo --type=bioconductor --name=bioconductor --description='Access Bioconductor packages' --authenticated

   Or edit an existing repository to require authentication:

   rspm edit repo --name=cran --authenticated

   To require authentication by default for new repositories, configure the Authentication.NewReposAuthByDefault setting.

2. Create an API token that includes the repos:read scope.

   Terminal

   rspm create token --scope=repos:read --repos='*' --description="Allows read access for all repos"

3. Instruct users to configure R or configure Python to use the API token.

   If you are using Connect or Workbench with authenticated repositories, you can also configure credentials globally for all users. See Configuring Posit Connect and Configuring Posit Workbench.

API Tokens

API tokens are used to:

• Advanced Authenticate with the server when using the Package Manager CLI remotely.
• EnhancedAdvanced Authenticate users for repositories that require authentication.

API Token Security

For the best security, please consider the following when creating API tokens:

• Grant access only to the minimum necessary scope to run the required commands. For sources tokens, grant access only to the required sources using the --sources flag.
• Provide a token expiration with the --expires flag when creating a token. Tokens never expire by default.
• Rotate tokens regularly.

Creating API Tokens

You can create a token using the rspm create token command. API tokens have several properties. The token scope, description, expiry, and sources can only be set when the token is created; they cannot be changed. Tokens can be revoked at any time.

Property	Description
Scope	The type of access granted by the token, such as sources:write or global:admin. See API Token Scopes for a list of available scopes. Required.
Description	A description of the token; provided when token is created. Required.
Sources	The sources to which the token is granted access. When set to *, the token is valid for all current and future sources. Required for sources tokens.
Repos	The repos to which the token is granted access. When set to *, the token is valid for all current and future repos. Required for repos tokens.
Expires	An expiration time for the token. The token cannot be used after this time. An expiry of never means that the token never expires. You can specify a duration like 30d (30 days) or 5m (5 minutes). Defaults to never.
Revoked	A revoked token cannot be used; revoked tokens cannot be reinstated.

Note

When an API token is created for a specific local or git source, the token is valid only for the source you specified. If you delete the source and recreate a new source with the same name, you will need to create a new API token for the new source.

Examples

• Create a repos:read token with access to download packages from all repos (no expiry):

  Terminal

  rspm create token --scope=repos:read --repos='*' \
    --description="Allows read access for all repos"

• Create a sources:write token with access to upload packages to all sources (no expiry):

  Terminal

  rspm create token --scope=sources:write --sources='*' \
    --description="Allows write access for all sources"

• Create a sources:write token with access to upload packages to the internal and internal-git sources (no expiry):

  Terminal

  rspm create token --scope=sources:write --sources=internal,internal-git \
    --description="Allows write access for the internal and internal-git sources"

• Create a metadata:admin token with access to manage custom metadata (30 day expiry):

  Terminal

  rspm create token --scope=metadata:admin --expires=30d \
    --description="Allows full access to manage metadata"

• Create a global:admin token with full administrative access (30 day expiry):

  Terminal

  rspm create token --scope=global:admin --expires=30d \
    --description="Allows global admin access"

See the rspm create token documentation for more examples.

API Token Scopes

Name	Tiers	Description
global:admin	Advanced	Grants full access to manage the Package Manager server.
sources:write	Advanced	Grants read and write access to sources, such as uploading packages, removing packages, creating Git builders, and importing Git credentials. Access can be limited to specific sources or granted to all sources with --sources='*'.
repos:read	EnhancedAdvanced	Grants read access to authenticated repositories. Access can be limited to specific repositories or can be granted to all repositories with --repos='*'.
blocklist:admin	Advanced	Grants full access to manage the blocklist.
blocklist:read	Advanced	Grants read access to the blocklist.
metadata:admin	Advanced	Grants full access to manage metadata.
metadata:read	Advanced	Deprecated. Grants read access to metadata. Existing tokens can be used, but you cannot create new tokens with the metadata:read scope. New tokens should use the repos:read scope.

Listing API Tokens

You can list API tokens with the rspm list tokens command. Use the --expired and --revoked flags to filter the results.

Revoking API Tokens

You can revoke API tokens at any time with the rspm revoke token command. Revoked tokens cannot be reinstated, and are no longer valid for use. To revoke a token, you can provide the token or the GUID associated with the token. You can List API Tokens to find the GUID associated with each token.