1. Articles
  2. Manage and Operate
  3. User Management & Federation
  4. Getting Started

Articles in this section

Managing OVHcloud Service Accounts via the API

Avatar
Stephanie R.
  • Updated

Learn how to generate credentials to deploy within your code, as well as their use in OVHcloud access policies.

Access to OVHcloud products can be configured within access policies, which can be accessed via the OVHcloud Control Panel. This allows you to define who can access which product. To configure this access for users, please refer to our guide on using IAM policies from your Control Panel.

When API access is required from applications or code, it is necessary to generate specific credentials in order not to link them to a user. You don't want to reset your scripts in production if your user changes their credentials or leaves your company.

This guide will explain how to generate credentials to deploy within your code, as well as their use in OVHcloud access policies. These credentials can be used within the different APIs of our products:

 

Requirements

 

Instructions

Understanding identities

Service accounts are one of the types of identities that can be set up on your OVHcloud account. Other account types are described in the related documentation.

 

How service accounts work

OVHcloud service accounts are a username/token couple that allows your code to authenticate with OVHcloud APIs. These credentials follow the OAuth2 protocol by following the client credential authentication mechanism.

This identifier/token pair has no time limit. It is therefore ideal for use within a code deployed in production. Of course, you can revoke the access associated with this service account at any time by modifying the associated access policies or by deleting this service account.

Each identifier is associated with a unique urn, which enables it to be granted fine-grained rights on OVHcloud products by linking it to access policies. These credentials are directly linked to your root account. As a result, they are not affected by user changes.

Like all OVHcloud APIs, the management of these credentials is subject to configurable access rights within the access policies. You can find more information in our guide on using IAM policies via the OVHcloud Control Panel.

 

Manage service accounts

OVHcloud service accounts can be configured within the APIs /me/api/oauth2/client.

 

Create a service account

To create a service account, use the following API call:

POST /me/api/oauth2/client

With this API call, you can create OAuth2 credentials for several authentication mechanisms. The one we are interested in here is CLIENT_CREDENTIALS. This mechanism does not require a callback URL.

You must supply the following values:

  • callbackUrls: an empty array of callback URLs []
  • flow: "CLIENT_CREDENTIALS"
  • name: the name you would like to provide to your identifier
  • description: a description of your identifier. We recommend describing how you will use this identifier. If you audit your access in the future, it is easier to link it to your application name, so that you can easily find out where the identifier is deployed (and what the impact will be if you change your access).

In response, the API will provide you with two pieces of information:

  • clientId: your service account ID
  • clientSecret: a token allowing you to authenticate yourself on our APIs. This information must be stored securely. With these two credentials, you can log in to this service account and get the rights associated with it. Save this value. It will not be possible to retrieve it at a later stage.

To retrieve the& URN required to edit an access policy, you can use the following call:

GET /me/api/oauth2/client/{clientId}

Use the value of the identifier retrieved from the previous call.
In this call, you will have access to the identity value in the form of a URN that will allow you to associate this service account with an access policy.

This URN is of the following form:

urn:v1::identity:credential:/oauth2-

 

Delete a service account

If you no longer use a service account or want to permanently delete this access, use the following call:

DELETE /me/api/oauth2/client/{clientId}

WARNING: This action is permanent. If you would like to cancel it, you will need to create a new service account and deploy the username/token pair within your application.
To delete access, we recommend detaching all access policies from this service account. This action is reversible and allows you to cancel in case of an error. Once you have ensured that this service account is not used in production, you can delete it without fear.

 

To modify access for a service account, you can associate it with an existing access policy or create a new one. To find out more about managing access policies, please read our guide on using IAM policies via the OVHcloud API.

For this example, we will use an existing access policy to provide access to the service account management APIs. Below is an example of a policy with the values xx11111-ovh and urn:v1:us:identity:credential:xx11111-ovh/oauth2-0f0f0f0f0f0f0f0f, which should be adapted to suit your configuration.

{
  "description": "Demo for service account guide",
  "identities": [
    "urn:v1:us:identity:credential:xx11111-ovh/oauth2-0f0f0f0f0f0f0f0f"
  ],
  "name": "Demo-service-account",
  "permissions": {
    "allow": [
      {
        "action": "account:apiovh:me/api/oauth2/client/get"
      },
      {
        "action": "account:apiovh:me/api/oauth2/client/create"
      },
      {
        "action": "account:apiovh:me/api/oauth2/client/edit"
      },
      {
        "action": "account:apiovh:me/api/oauth2/client/delete"
      }
    ]
  },
  "resources": [
    {
        "urn": "urn:v1:us:resource:account:xx11111-ovh"
    }
  ]
}

This example can be used directly within the following call to create a new policy:

POST /v2/iam/policy

 

Usage of service accounts

Service accounts are available in several APIs of our products. For each API, there is a guide:

 

Go further

For more information and tutorials, please see our other User Management & Federation or Manage and Operate guides, or explore the guides for other OVHcloud products and services.

Related articles