Authentication

Create a personal access token or service account and start using Application Collection

Most operations in Application Collection (such as installing a Helm chart, running a container image or consuming the REST API) require authentication. In this page, you will learn about the different authentication mechanisms that Application Collection offers and how to configure them in the most common tools.

Authentication methods

Application Collection offers two ways of authenticating: personal access tokens and service accounts. Although they are configured in a pretty similar way, they offer different capabilities. Hence, it is very important to understand their nuances before making a choice of which one to use.

Both personal access tokens and service accounts allow you to authenticate to Application Collection through different non-graphical clients. In order to setup any of them, it is mandatory that you have an account with access to Application Collection.

From a conceptual point of view, when you use a personal access token you’re authenticating in behalf of yourself. However, when using a service account you’re authenticating in behalf of an organization. This leads to the first important difference between them: subscriptions. As a service account is linked to one single organization, it only has the subscriptions of the organization that it belongs to. However, a personal access token will inherit all the subscriptions of all the organizations that the user belongs to.

Let’s see that with a practical example. Imagine that we have a user jonh.doe@my-org.com that is member of two organizations:

  • Organization A has two subscriptions: Prime and SUSE AI
  • Organization B has one subscription: Prime

When the user authenticates using a personal access token, this token will inherit the subscriptions of all the organizations of the user. Hence, with a personal access token the user will be able to pull content that requires either a Prime or a SUSE AI subscription.

However, if the user authenticates with a service account that belongs to Organization B he will only be able to pull content that requires Prime subscription. With this service account the user will not be able to pull content that requires SUSE AI subscription, as he is authenticating in behalf of Organization B and Organization B does not have the SUSE AI subscription.

All SUSE employees are member of the SUSE organization, which has all available subscriptions. This means that SUSE employees are entitled to pull the whole collection using a personal access token.

However, as SUSE employees are not admins of the SUSE organization they are not allowed to create service accounts under this organization.

Another important difference between personal access tokens and service accounts is related to their configured rate limits. As a general rule, service accounts have a higher rate limit than personal access tokens and hence allow pulling a higher number of images in a given time frame. Further information about the default rate limits and how they are applied can be found here. Please, make sure you have read and understood this documentation before choosing your desired authentication method.

Finally, there are some differences regarding how personal access tokens and service accounts are created. The process for each of them is detailed in the following sections.

Create a personal access token

You can create as many personal access tokens as you want. The only requirement for creating an access token is that you have an account with access to Application Collection.

Once you have access to Application Collection, you can create a personal access token following these steps.

  1. Open the web application in your browser of choice and sign in
  2. In the upper-right corner you will see your profile picture. Click on it
  3. In the pop-up, click Settings and later, click Access tokens
  4. Insert a meaningful description for the new token in the input below Create access token
  5. Click Create. This will show a green box, with the token contents on it

Token example

Create a service account

Service accounts are always linked to an organization. It is important to notice that only the admins of an organization are entitled to create service accounts for it.

If you have an account with access to Application Collection, then you can create as many service accounts as you want for the organizations where you are an admin. You just need to follow these steps.

  1. Open the web application in your browser of choice and sign in
  2. In the upper-right corner you will see your profile picture. Click on it
  3. In the pop-up, click Settings and later, click Service accounts
  4. Insert a meaningful description for the service account in the input below Create service account, and select the target organization
  5. Click Create. This will show a green box, with the service account contents on it

Service account example

Use CLI tools

At this point, you already created either a personal access token (PAT) or a service account (SA), but you are not sure about how to use it. Below we will show you how to quickly use it with docker, podman, helm, kubectl and curl.

Every time an access token or service account is created, copy-pastable helper commands are shown for configuring the token immediately.

Docker

To set up Docker, you will need to open a terminal and run:

docker login dp.apps.rancher.io -u <your-username-or-sa-username> -p <access-token-or-sa-token>

After that, you can check the configuration by pulling an image. This is an example of the output you should get upon a successful pull:

$ docker pull dp.apps.rancher.io/containers/openjdk:17.0.10
17.0.10: Pulling from containers/openjdk
26cbacfd9b54: Pull complete 
d3e7d6906a04: Pull complete 
Digest: sha256:0f14a2a18e441da428b63e3854fe29fa6f9f20af5b99ba9780adb36bee65f5e4
Status: Downloaded newer image for dp.apps.rancher.io/containers/openjdk:17.0.10
dp.apps.rancher.io/containers/openjdk:17.0.10

Podman

You can also configure Podman to pull images from Application Collection. Execute the following command:

podman login dp.apps.rancher.io -u <your-username-or-sa-username> -p <access-token-or-sa-token>

You can verify that the configuration is correct by pulling an image, for example:

$ podman pull dp.apps.rancher.io/containers/ruby:3.3.0
Trying to pull dp.apps.rancher.io/containers/ruby:3.3.0...
Getting image source signatures
Copying blob sha256:6911d8a6e0d680cdfa227956a00667fe6cd1e2c111fa3c588d1cccc0b621bfe2
Copying blob sha256:4191f2fe96e960b152f79a6b0dcb40ad599b834e72b79edc61e6a627fec776c7
Copying config sha256:c7b272c4b0b6d09b43a32cf3215d0c86c5f148c00d6d049755f292e1c018cfa6
Writing manifest to image destination
c7b272c4b0b6d09b43a32cf3215d0c86c5f148c00d6d049755f292e1c018cfa6

Helm

Configuring Helm to use Application Collection is a matter of running a single command:

helm registry login dp.apps.rancher.io -u <your-username-or-sa-username> -p <access-token-or-sa-token>

You can check that it worked by pulling one of the Collection’s charts:

$ helm pull oci://dp.apps.rancher.io/charts/apache-apisix --version 2.4.0    
Pulled: dp.apps.rancher.io/charts/apache-apisix:2.4.0
Digest: sha256:533b7684559691782b42ee81bfde1a19ddfe81eb7cce108b01435ce7d25a7027

If you want to install charts on a Kubernetes cluster, continue to the next section.

Kubernetes

To deploy images from Application Collection to k8s workloads, you will need to configure a Kubernetes pull secret:

kubectl create secret docker-registry application-collection --docker-server=dp.apps.rancher.io --docker-username=<your-username-or-sa-username> --docker-password=<access-token-or-sa-token>

After that, you should be able to run any workload using our images:

$ kubectl run nginx --image dp.apps.rancher.io/containers/nginx:1.24.0 --overrides='{"spec": {"imagePullSecrets":[{"name": "application-collection"}]}}'
$ kubectl get pod nginx
NAME    READY   STATUS    RESTARTS   AGE
nginx   1/1     Running   0          10s

There are other ways of passing the imagePullSecret that may fit your needs better. For that, you can check this article.

cURL

If you get to this point, you may want to start using the REST API.

This is an example of making a request with cURL, that uses basic authentication with the newly created token:

curl -u <your-username-or-sa-username>:<access-token-or-sa-token> https://api.apps.rancher.io/v1/applications

If you’re going to use the API intensively, we suggest using other tools such as Postman or the embedded Swagger UI. In any case, you will need to pick basic authentication, using your email as username and token as password.

Last modified February 21, 2025