Skip to main content
Version: 24.11.01

Service Account

Service account is a specialized type of identity account used by services, applications, and automated processes to interact with PDS APIs in a secure and controlled manner.

Advantages of Service account​

Service account are used in applications and systems to access resources and perform tasks. Here's how to use service accounts:

  • Authenticate: Service accounts authenticate themselves using API keys, tokens, or other credentials.
  • Authorization: Service accounts are authorized to access specific resources or perform certain actions based on defined permissions.
  • Interactions: Service accounts interact with other services or APIs to perform tasks, retrieve data, or update resources.
  • Secure communication: Service account uses JSON Web Token (JWT) tokens along with Transport Layer Security (TLS) to communicate with other services.

Service accounts are important for establishing robust safeguards for service and API key access in the following ways:

Enhanced security​

  • Reduced attack surface: When services use dedicated service accounts, it reduces the attack surface compared to sharing a common user account. Breaching a single service account does not automatically grant access to other systems, as each account has its own set of permissions.
  • Credential management: Service accounts use secure credentials, such as API keys, tokens, or certificates, which are typically stored and managed securely. This reduces the risk of credentials being exposed and used maliciously.

Audit and monitoring​

Service accounts make it easier to audit and monitor activities. Each service account's actions are logged separately, providing detailed visibility into who or what is performing which operations. This is crucial for compliance and security monitoring.

Simplified revocation and rotation​

  • Revocation: When a service or application no longer requires access to specific resources, its service account can be easily revoked, rendering the associated credentials useless. This is more efficient and secure than having to change the credentials of a shared user account.
  • Rotation: Service account credentials can be regularly rotated for security reasons. Automated processes make it easier to update and manage these credentials in an organized manner.

API access control​

Service accounts often come with access controls that allow organizations to specify which APIs or endpoints they can access. This ensures that the service account can interact only with the necessary parts of a system.

1. Log in to obtain an authentication token​

Before creating a service account (Step 2), you need to log in to the PDS platform to authenticate yourself and establish the necessary credentials to perform API operations securely. The login process, using the Login API, generates an authentication token (idToken) that is required to authorize API requests for subsequent steps.

API endpoint for login​

Use the following API endpoint to log in and retrieve the idToken:

https://cloud.portworx.io/core/v1/oauth:login

Login API call​

curl --location 'https://cloud.portworx.io/core/v1/oauth:login' \
--header 'Content-Type: application/json' \
--data-raw '{
     "email": "<insert email ID here>",
     "password": "<insert password here>"
}' | jq -r ".idToken"

where:

  • email: Enter the email address associated with your PDS account.
  • password: Enter the password for the specified email address.

Example response​

If the login is successful, the API returns a JSON response containing the idToken. For example:

{
  "idToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The idToken is a JWT that authenticates the user and authorizes API calls.

Usage of idToken​

The idToken is required as a bearer token in the Authorization header for all subsequent API requests.

For example:

--header "Authorization: Bearer <idToken>"

2. Create a service account​

To create a service account:

Use the Service account API to create a service account. A service account represents an application or service that requires controlled access to PDS resources, enabling programmatic interactions with the PDS platform.

API endpoint​

Use the following endpoint to create a service-account for a specific tenant (organization) resource:

https://cloud.portworx.io/core/v1/tenants/<insert-tenant-id>/serviceAccounts

Replace <insert-tenant-id> with the unique ID of the tenant (organization) for which you want to create the service account.

API call​

This API call creates a service account and provides the necessary credentials (clientId and clientSecret) to enable secure and controlled access to PDS resources, making it essential for integrating external applications or services with the PDS platform.

The request body is a JSON object containing details about the service account you want to create:

curl --http2 --location "https://cloud.portworx.io/core/v1/tenants/<insert-tenant-id>/serviceAccounts" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "px-account-id: <insert-account-id>" \
--header "Authorization: Bearer <insert-token>" \
--data '{
  "meta": {
    "name": "<insert-service-account-name>"
  },
  "config": {
  }
}' | jq -r ".config"

where: Headers:

  • Content-Type: application/json: Indicates that the request body is in JSON format.
  • Accept: application/json: Requests the response in JSON format.
  • px-account-id: The unique identifier for the account associated with the PDS setup.
  • Authorization: Bearer <insert-token>:
    • Replace <insert-token> with the idToken obtained from the login step.
    • Used to authenticate and authorize the API call.

Endpoints:

  • The endpoint targets the serviceAccounts resource under the specified tenant (organization).
  • Replace <insert-tenant-id> with the tenant (organization) ID.

Request body:​

{
  "meta": {
    "name": "<insert-service-account-name>"
  },
  "config": {
  }
}

where:

  • meta.name: Specifies the name of the service account. Replace <insert-service-account-name> with the desired name for the service account.
  • config: Reserved for future use; currently left empty.
  • The | jq -r ".config" filters the response to return only the config section, which contains the client credentials.

Example response:​

{
  "clientId": "c/p4aG21J47s0O/kQCCv1yPDeoTr/b05",
  "clientSecret": "e9870b49617c50ebb99a6818d27949e2bf397a4dbca763b43fb869afe9ab43bc",
  "disabled": false
}

where:

  • clientId: The unique identifier for the service account.
  • clientSecret: The secret associated with the service account, used for generating access tokens.
  • disabled: Indicates whether the service account is active (false) or disabled (true).

Example workflow​

  1. Replace placeholders with actual values:

    • Tenant (organization) ID: Replace <insert-tenant-id> with the tenant (organization) ID.
    • Account ID: Replace <insert-account-id> with the account ID.
    • Token: Replace <insert-token> with the idToken obtained during login.
    • Service Account Name: Replace <insert-service-account-name> with the desired name.

  2. Execute the command using curl.

  3. Copy the clientId and clientSecret from the response. These credentials will be used in subsequent steps, such as generating access tokens for authenticating the service account.

3. Associate a service account with a role​

After creating the service account, the next step is to associate the service account with a specific role using the IAM API. This step ensures the service account has the necessary permissions to access resources and APIs as defined by the assigned role.

  1. Define the IAM configuration:

    1. Specify the actorId as the service account ID created in the above procedure.
    2. Set the actorType to SERVICE_ACCOUNT to identify the type of actor.
    3. Define the accessPolicy to associate the service account with a role (for example, tenant-admin) and the required resource IDs.

  2. Send an HTTP request to the following endpoint to create the IAM configuration:

    https://cloud.portworx.io/core/v1/iam

    Example IAM API request:

    curl --http2 --location 'https://cloud.portworx.io/core/v1/iam' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header "px-account-id: "<insert account id here. Ex: acc:xxxxxxxx-xxxx-xxxx-xxxx-57602280771a >" \
    --header "Authorization: Bearer "<insert idToken obtained from /core/v1/oauth:login here>" \
    --data '{
      "meta": {
        "name": "sa-iam"
      },
      "config": {
        "actorId": "<insert service account id here. Ex: sa:xxxxxxxx-xxxx-xxxx-xxxx-a783d919d356 >",
        "actorType": "SERVICE_ACCOUNT",
        "accessPolicy": {
          "tenant": [
            {
              "roleName": "tenant-admin",
              "resourceIds": [
                "<insert tenant id here. Ex: ten:acc:xxxxxxxx-xxxx-xxxx-xxxx-57602280771a >"
              ]
            }
          ]
        }
      }
    }'

    where:

    • actorId: The unique ID of the service account created in Step 1.
    • actorType: Set to SERVICE_ACCOUNT to indicate that the actor is a service account.
    • accessPolicy: Defines the role and the resources the service account can access.
    • roleName: Specifies the role to be assigned (for example, tenant-admin).
    • resourceIds: The IDs of the resources the service account can access.
    note

    The token used in the Authorization header for this API request is the idToken obtained during the login step (Step 1). To retrieve this token, use the /core/v1/oauth endpoint. This token is required to authenticate and authorize the request. To authenticate this request:

    1. Obtain the idToken by logging in using the /core/v1/oauth endpoint.

    2. Replace <insert idToken obtained from /core/v1/oauth:login here> in the Authorization header with the token retrieved from Step 1.

    This ensures the API call is authorized properly.

Example response​

{
  "meta": {
    "uid": "iam:abc12345-6789-xyz",
    "name": "sa-iam",
    "createTime": "2024-11-18T12:34:56.789Z"
  },
  "status": {
    "reason": "IAM created successfully",
    "phase": "ACTIVE"
  }
}

This step associates the service account with a role (for example, tenant-admin) and grants it access to resources as per the assigned role's permissions. This is essential for enabling the service account to authenticate and interact with PDS APIs effectively. Proceed to the next step to generate an access token for the service account.

4. Generate access token from service account​

This API call is essential for enabling service accounts to interact with the PDS platform securely. The generated JWT token:

  • Authenticates API requests: Validates the service account's identity.
  • Grants access: Provides controlled access to resources and operations based on the service account's assigned role and permissions.
  • Ensures security: Uses client-specific credentials (clientId and clientSecret) to maintain secure and isolated access.

For more information about the API, view the documentation.

Use the following endpoint to generate a JWT for a service account:

https://cloud.portworx.io/core/v1/tenants/<insert tenant id here>:getToken

Replace <insert-tenant-id> with the unique identifier of the tenant (organization) associated with the service account.

This is the URL endpoint where you will send an HTTP/2 request to generate a JWT token for a service account. The endpoint is specifically designed for creating tokens, and it does not require a dynamic identifier (for example, user or account ID) in the URL.

API call​

The request body is a JSON object that contains the details necessary to generate the JWT token:

curl --http2 --location 'https://cloud.portworx.io/core/v1/tenants/<insert tenant id here>:getToken' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "px-account-id: <insert-account-id>" \
--header "Authorization: Bearer <insert-token>" \
--data '{
  "clientId": "<insert-client-id>",
  "clientSecret": "<insert-client-secret>"
}' | jq -r ".token"

Request body​

{
  "clientId": "<insert-client-id>",
  "clientSecret": "<insert-client-secret>"
}

where:

  • clientId: The unique identifier for the service account, obtained when the service account was created.
  • clientSecret: The secret key associated with the service account, also provided during the service account creation.
  • The | jq -r ".token" filters the response to extract and display only the JWT token.

Example workflow​

  1. Replace the placeholders with actual values:

    • Tenant (organization) ID: Replace <insert-tenant-id> with the tenant (organization) ID.
    • Account ID: Replace <insert-account-id> with the account ID.
    • Authorization Token: Replace <insert-token> with the idToken obtained during login.
    • Client ID and Secret: Replace <insert-client-id> and <insert-client-secret> with the credentials generated during the service account creation step.

  2. Run the command using curl.

    The response will return a JWT token.

Example response​

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

  • token: The JWT token generated for the service account. This token is used for authenticating API requests made by the service account.

    note

    The token provided has a limited time-to-live (TTL) of 60 minutes, after which it will expire. You should generate a new token following the instructions detailed in the next section.

5. Use the generated token in subsequent API calls​

After generating a JWT token for the service account in Step 4, you can use this token to authenticate and authorize subsequent API requests made by the service account. The token, included in the Authorization header, ensures secure access to PDS resources and APIs.

For every API request made by the service account, include the Authorization header in the HTTP request with the following format:

--header "Authorization: Bearer <insert-generated-token>"

where:

  • Authorization: Specifies the authentication mechanism.
  • Bearer: Indicates that the header contains a token used for access control.
  • <insert-generated-token>: Replace this placeholder with the JWT token obtained in Step 4.

Example Usage in an API Call​

Here’s how to include the token when calling another API, such as fetching details about a tenant (organization):

curl --http2 --location 'https://cloud.portworx.io/core/v1/tenants/<tenant-id>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."

Best practices​

When working with service accounts, consider these best practices:

  • Follow the principle of least privilege: Grant the minimum permissions necessary for the service to perform its tasks.
  • Securely store and manage service account credentials to prevent unauthorized access.
  • Implement logging and auditing to track service account activities for security and compliance.
  • Use secure communication protocols like HTTPS to protect credentials and data in transit.
  • Regularly review and update permissions to ensure they remain aligned with the service's requirements.
  • Rotate service account credentials periodically for improved security.
  • Educate your team on security best practices and the use of service accounts.

Service accounts play a critical role in modern application development and security, enabling secure, automated, and controlled interactions between services and components. Understanding and implementing best practices is essential for maintaining a robust and secure system.

User account versus user API keys versus service account​

  • User account: User accounts represent individual users and their access permissions. They are associated with human-readable usernames, passwords, and sometimes additional information such as email addresses and roles.
  • User API keys: These are typically associated with user accounts and grant access based on the user's permissions. User API keys are used for user-specific tasks and are tied to a specific user account.
  • Service account: Service accounts represent applications, services, or components. They are used for programmatic access to resources and are typically associated with API keys or tokens. Service accounts lack the human-specific attributes of user accounts and are designed for machine-to-machine communication.
Last updated on
Was this page helpful?