Work with service accounts

Service accounts are created for automation purposes, such as to authenticate bots that operate on your organization.

Work with service accounts through snctl

In this section, the organization has the name matrix as an example name.

Create a service account through snctl

To create a service account through snctl, follow these steps.

Define a service account resource named bot by using a manifest file and save the manifest file sa-bot.yaml.

apiVersion: cloud.streamnative.io/v1alpha1
kind: ServiceAccount
metadata:
  namespace: matrix
  name: bot

The following table lists fields in the manifest file.

Field	Description
apiVersion	Specify the version of Pulsar API server.
kind	Specify the component to be created.
metadata	Configure the metadata information about the service account. - namespace: specify the name of the organization. - name: specify the name of the service account.

Apply the manifest file to create the service account.

snctl apply -f /path/to/sa-bot.yaml

Output

serviceaccount.cloud.streamnative.io/bot created

Check whether the service account was created successfully.

snctl describe serviceaccount bot

Output

Name:         bot
Namespace:    matrix
Labels:       <none>
Annotations:  <none>
API Version:  cloud.streamnative.io/v1alpha1
Kind:         ServiceAccount
Metadata:
  Creation Timestamp:  2020-08-11T16:25:10Z
  Finalizers:
    serviceaccount.finalizers.cloud.streamnative.io
  Generation:        1
  Resource Version:  396516
  Self Link:         /apis/cloud.streamnative.io/v1alpha1/namespaces/matrix/serviceaccounts/bot
  UID:               874b226b-ea01-41c2-9a7b-059fdcc0d5c1
Spec:
Status:
  Conditions:
    Last Transition Time:  2020-08-14T06:25:52Z
    Reason:                Provisioned
    Status:                True
    Type:                  Ready
  Private Key Data:
  Private Key Type:        TYPE_SN_CREDENTIALS_FILE
Events:                    <none>

From the output, you can see that the status and type parameters for items under Conditions are set to true and ready. This means that the service account bot was created successfully.

In addition, you can use the snctl create serviceaccount SERVICE_ACCOUNT_NAME command to create a service account. For details, see snctl reference.

Download service account credentials

To use a service account, you first download its associated credentials to a JSON file. The information is made available through the status block of the ServiceAccount resource.

The following example shows how to download the service account credentials to a file called bot.json.

snctl auth export-service-account bot --key-file bot.json

The file contents will be similar to the following:

{
  "type": "SN_SERVICE_ACCOUNT",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "client_email": "[email protected]"
}

The following table lists two fields in the JSON file.

Field	Description
`client_id`	It is an Auth0 Application that has been created.
`client_secret`	It is used to authenticate to Auth0 for accessing snctl.

The file contains credentials information and should be well protected.

Activate a service account

This example shows how to activate a service account through a key file called bot.json.

snctl auth activate-service-account --key-file bot.json -a https://api.streamnative.cloud -i https://auth.streamnative.cloud/

Output

Logged in as [email protected]
Welcome to StreamNative Cloud!

Access the StreamNative Cloud API

This example shows how to access the StreamNative Cloud API through a service account.

Create a service account.

This example creates a service account named bot.

snctl create serviceaccount bot.

Output

serviceaccount.cloud.streamnative.io/bot created

Download the associated credentials of the service account to a JSON file。

snctl auth export-service-account bot -f bot.json

Output

Wrote private key file 'bot.json'.

Bind the service account with an "admin" role.

snctl create rolebinding bot-cluster-admin --role admin --serviceaccount bot

Output

rolebinding.cloud.streamnative.io/bot-cluster-admin created

Log out from snctl.
```
snctl auth logout
```

snctl auth activate-service-account --key-file bot.json

Output

Logged in as [email protected]
Welcome to StreamNative Cloud!

Connect to a Pulsar cluster

This example shows how to connect to a Pulsar cluster by using a service account.

Create a service account.

This example creates a service account named bot.

snctl create serviceaccount bot.

Output

serviceaccount.cloud.streamnative.io/bot created

Download the associated credentials of the service account to a JSON file。

snctl auth export-service-account bot -f bot.json

Output

Wrote private key file 'bot.json'.

Connect to a Pulsar cluster using the pulsarctl. Replace the YOUR-KEY-FILE-PATH parameter with the local path for the downloaded JSON file. For details about connecting to a Pulsar cluster through other Pulsar CLI tools, see connect.

pulsarctl namespaces list public \
    --admin-service-url https://neo1.matrix.us-east4.streamnative.g.snio.cloud \
    --issuer-endpoint https://streamnative.cloud \
    --client-id abcdefghigk0123456789 \
    --audience urn:sn:pulsar:pulsar-instance-ns:pulsar-instance-name \
    --key-file YOUR-KEY-FILE-PATH

Check service accounts through snctl

This example shows how to check the service accounts of an organization.

snctl get serviceaccount

Output

NAME   CREATED AT
bot   2020-08-11T16:25:10Z

From the output of this command, you can see all created service accounts and the time when these service accounts were created.

Check service account details through snctl

Before checking the details about a service account, you should use the following command to confirm whether the service account is available.

snctl get serviceaccount

Then, you can use the following command to check details about a service account.

snctl describe serviceaccount SERVICE_ACCOUNT_NAME

The following example checks the details about the service account bot.

snctl describe serviceaccount bot

Output

Name:         bot
Namespace:    matrix
Labels:       <none>
Annotations:  <none>
API Version:  cloud.streamnative.io/v1alpha1
Kind:         ServiceAccount
Metadata:
  Creation Timestamp:  2020-08-11T16:25:10Z
  Finalizers:
    serviceaccount.finalizers.cloud.streamnative.io
  Generation:        1
  Resource Version:  396516
  Self Link:         /apis/cloud.streamnative.io/v1alpha1/namespaces/matrix/serviceaccounts/bot
  UID:               874b226b-ea01-41c2-9a7b-059fdcc0d5c1
Spec:
Status:
  Conditions:
    Last Transition Time:  2020-08-14T06:25:52Z
    Reason:                Provisioned
    Status:                True
    Type:                  Ready
  Private Key Data:
  Private Key Type:        TYPE_SN_CREDENTIALS_FILE
Events:                    <none>

Delete a service account through snctl

You can use the following command to delete a service account based on the service account name.

snctl delete serviceaccount SERVICE_ACCOUNT_NAME

In addition, you can use the following command to delete the service account based on the name specified in the manifest file.

snctl delete -f ./sa-bot.yaml

Work with a service account through StreamNative Cloud Console

This section describes how to work with a service account through the StreamNative Cloud Console.

Currently, you can't edit a service account. If you need a service account to have Super Admin access, make sure to enable this feature when creating the service account. Service accounts do not have Super Admin enabled by default.

Create a service account through StreamNative Cloud Console

To create a service account, follow these steps.

On the left navigation pane, click Service Accounts.
Click Create Service Account. A dialog box displays.
(Optional) Select Super Admin to grant the service account access to a namespace or tenant.
Enter a name for the service account, and then click Confirm.

Check service account details

After you have created a service account, you can check the details of the account.

On the left navigation pane, click Service Accounts. The Service Accounts page displays all of the created service accounts.

The table below describes the details that you can view about the service account.

Item	Description
Name	The name of the service account.
Pulsar Role Name	This name displays in the Admin Role field when creating a tenant.
Key File	The key file for the service account.
Token	The token for the service account.
Organization	The organization that the service account was created in.
Create Time	The time when the service account was created.
Status	The status of the service account.
Admin	Whether the service account has Super Admin enabled or not.
...	Click the ellipsis to display the delete icon.

Get the service account key file or token

Both the key file and the token are used for authentication. Tokens are only valid for seven days. When a token expires, you need to use the key file to generate a new token for authentication. Or, you can directly use the key file for authentication.

To get the key file or token of a service account, follow these steps.

On the left navigation pane, click Service Accounts.
Get the key file or the token.
- In the row of the service account you want to use, in the Key File column, click the Download icon to download the key file to your local directory.
- In the row of the service account you want to use, in the Token column, click Generate new token, then click expires in 7 days to copy the token to your clipboard.

Delete a service account

To delete a service account, follow these steps.

On the left navigation pane, click Service Accounts.
Click the ellipsis at the end of the row of the service account you want to delete, and then select Delete.
On the dialog box asking, Are you sure you want to delete this service account?, click Confirm.