• Identity and Access Management

iam
  1. Help Center
  2. Identity and Access Management
  3. API Reference
  4. Custom Role Management
  5. Creating Custom Roles

Creating Custom Roles

Function Description

This interface is used to create a custom role.

URI

URI format

POST /v3.0/OS-ROLE/roles

Request

  • Request header parameter description

    Parameter

    Mandatory

    Type

    Description

    Content-Type

    Yes

    String

    Fill application/json;charset=utf8 in this field.

    X-Auth-Token

    Yes

    String

    Authenticated token with the Security Administrator permission.

  • Request body parameter description

    Parameter

    Mandatory

    Type

    Description

    role

    Yes

    JSONObject

    Request body of a user group.

    display_name

    Yes

    String

    Displayed name of a role. The value cannot exceed 64 characters.

    type

    Yes

    String

    Display mode of a role.

    • AX: A role is displayed at the domain layer.
    • XA: A role is displayed at the project layer.
      NOTE:

      The display mode of a role can only be AX or XA. A role cannot be displayed at both the domain and project layers or neither of the two layers. That is, neither AA nor XX is allowed.

    description

    Yes

    String

    Description of a role. The value cannot exceed 256 characters.

    policy

    Yes

    JSONObject

    Permission policy of a role.

  • Description for the policy format

    Parameter

    Mandatory

    Type

    Description

    Version

    Yes

    String

    Version of a policy. The value must be 1.1.

    Statement

    Yes

    JSONArray

    Statement: The Statement field contains the Effect and Action elements. Effect indicates whether the policy allows or denies access. Action indicates authorization items. The number of statements cannot exceed 8.

  • Description for the statement format

    Parameter

    Mandatory

    Type

    Description

    Effect

    Yes

    String

    The value can be Allow and Deny. If both Allow and Deny are found in statements, the policy evaluation starts with Deny.

    Action

    Yes

    StringArray

    Permission set, which specifies the operation permissions on resources. The number of permission sets cannot exceed 100.

    Format:

    The value format is Service name:Resource type:Action, for example, vpc:ports:create.

    Service name: indicates the product name, such as ecs, evs, or vpc. Only lowercase letters are allowed.

    Resource type and Action: The values are case-insensitive, and the wildcard (*) is allowed. A wildcard (*) can represent all or part of information about resource types and actions for the specific service.

    Resource

    No

    JSONObject

    • Delegated resource. After an account establishes multiple trust relationships between itself and your account, you can authorize different users to manage resources of the delegating party. Each user can only switch to the delegated agencies. You can create custom policies to grant specified permissions to users.
    • When creating a custom policy, specify the Action as iam:agencies:assume.
    • A maximum of 10 resources can be delegated.
  • Format description of the Resource parameter

    Parameter

    Mandatory

    Type

    Description

    uri

    Yes

    StringArray

    URI of a delegated resource, which can contain a maximum of 128 characters.

    Format: /iam/agencies/{delegation ID}

  • Example request (custom policy for a cloud service)
    curl -i -k -H 'Accept:application/json' -H 'Content-Type:application/json;charset=utf8' -H "X-Auth-Token:$token" -X POST -d'{"role":{"display_name":"Customed ECS Viewer","policy":{"Version":"1.1","Statement":[{"Action":["ecs:*:get*","ecs:*:list*","ecs:blockDevice:use","ecs:serverGroups:manage","ecs:serverVolumes:use","evs:*:get*","evs:*:list*","vpc:*:get*","vpc:*:list*","ims:*:get*","ims:*:list*"],"Effect":"Allow"}]},"type":"XA","description":"The read-only permissions to all ECS resources,which can be used for statistics ands urvey."}}' https://172.30.48.86:31943/v3.0/OS-ROLE/roles
  • Example request (custom policy for an agency)
    curl -i -k -H 'Accept:application/json' -H 'Content-Type:application/json;charset=utf8' -H "X-Auth-Token:$token" -X POST -d'{"role":{"display_name":"Customed fine-grained agency","policy":{"Version":"1.1","Statement":[{"Action":["iam:agencies:assume"],"Effect":"Allow","Resource":{"uri":["/iam/agencies/4eb04341ec2d41f5add4f3846d884f2d"]}}]},"type":"AX","description":"Allow sub-user to use agency."}}' https://172.30.48.86:31943/v3.0/OS-ROLE/roles

Response

  • Response body parameter description

    Parameter

    Mandatory

    Type

    Description

    role

    Yes

    Dict

    Details of the role.

  • Description for the role format

    Parameter

    Mandatory

    Type

    Description

    domain_id

    Yes

    String

    ID of the domain to which a role belongs.

    id

    Yes

    String

    ID of a role.

    links

    Yes

    Dict

    Resource links of a role.

    name

    Yes

    String

    Name of a role.

    type

    Yes

    String

    Display mode of a role.

    • AX: A role is displayed at the domain layer.
    • XA: A role is displayed at the project layer.

    display_name

    No

    String

    Displayed name of a role.

    catalog

    No

    String

    Directory where a role locates.

    policy

    No

    Dict

    Policy of a role.

    description

    No

    String

    Description of a role.

  • Example successful response (custom policy for a cloud service)
    {
      "role": {
          "domain_id": "9698542758bc422088c0c3eabfc30d12",
          "id": "24e7a89bffe443979760c4e9715c13a5",
          "links": {
            "self": "www.example.com/v3/roles/9698542758bc422088c0c3eabfc30d12"
          },
          "name": "custom_9698542758bc422088c0c3eabfc30d12_0",
          "type": "XA",
          "display_name": "Customed ECS Viewer",
          "catalog": "CUSTOMED",
          "policy": {
            "Version": "1.1",
            "Statement": [
              {
                "Action": [
                  "ecs:*:get*",
                  "ecs:*:list*",
                  "ecs:blockDevice:use",
                  "ecs:serverGroups:manage",
                  "ecs:serverVolumes:use",
                  "evs:*:get*",
                  "evs:*:list*",
                  "vpc:*:get*",
                  "vpc:*:list*",
                  "ims:*:get*",
                  "ims:*:list*"
                ],
                "Effect": "Allow"
              }
            ]
          },
          "description": "The read-only permissions to all ECS resources, which can be used for statistics and survey."
        }
    }
  • Example successful response (custom policy for an agency)
    {
      "role": {
          "domain_id": "9698542758bc422088c0c3eabfc30d12",
          "id": "5c03c324d4784435baaedb6a9bf01321",
          "links": {
            "self": "www.example.com/v3/roles/9698542758bc422088c0c3eabfc30d12"
          },
          "name": "custom_9698542758bc422088c0c3eabfc30d12_1",
          "type": "AX",
          "display_name": "Customed fine-grained agency",
          "catalog": "CUSTOMED",
          "policy": {
            "Version": "1.1",
            "Statement": [
              {
                "Action": [
                  "iam:agencies:assume"
                ],
                "Effect": "Allow",
                "Resource": {
                "uri": [
                  "/iam/agencies/4eb04341ec2d41f5add4f3846d884f2d"
                ]
               }
              }
            ]
          },
          "description": "Allow sub-user to use agency."
        }
    }

  • Error response body parameter description

    Parameter

    Mandatory

    Type

    Description

    error

    Yes

    Dict

    Response error

    message

    Yes

    String

    Error details

    code

    Yes

    Int

    Error code

    title

    Yes

    String

    Error type

  • Sample response (failed response)
{
    "error": {
        "message": "The request you have made requires authentication.",
        "code": 401,
        "title": "Unauthorized"
    }
}

Status Codes

Status Code

Description

201

The request is successful.

400

The server failed to process the request.

401

You must enter a username and password to access the requested page.

403

You are forbidden to access the requested page.

500

Failed to complete the request because of an internal service error.