IBM Cloud Docs
Managing IAM access for VPC Infrastructure Services

Managing IAM access for VPC Infrastructure Services

Access to IBM Cloud® Virtual Private Cloud service instances for users in your account is controlled by Cloud Identity and Access Management (IAM). Every user that accesses the VPC Infrastructure Services service in your account must be assigned an access policy with an IAM role. Review the following roles, actions, and more to help determine the best way to assign access to VPC Infrastructure Services.

The access policy that you assign users in your account determines what actions a user can perform within the context of the service or specific instance that you select. The allowable actions are customized and defined by the VPC Infrastructure Services as operations that you are allowed to perform on the service. Each action is mapped to an IAM platform or service role that you can assign to a user.

If a specific role and its actions don't fit the use case that you're looking to address, you can create a custom role and pick the actions to include.

IAM access policies enable access to grant at different levels. The following are some options that are included:

  • Access across all instances of the service in your account
  • Access to an individual service instance in your account
  • Access to a specific resource within an instance, such as vpcId or instanceId.

The following table lists the VPC resource attributes. For more information, see VPC resource attributes.

Table 1. VPC resource attributes
Resource Resource Attribute
Auto Scale for VPC instanceGroupId:<instance-group-id>
Backup service backupPolicyId: <backup-policy-id>
Block Storage for VPC volumeId: <volume-id>
Baremetal server bareMetalServerId: <bare-metal-server-id>
Dedicated Host for VPC dedicatedHostId:<dedicated-host-id>
File Storage shareId: <share-id>
Floating IP for VPC floatingIpId: <fip-id>
Flow Logs for VPC flowLogCollectorId: <flc-id>
Image Service for VPC imageId:<image-id>
Load Balancer for VPC loadBalancerId: <load-balancer-id>
Network ACL networkAclId: <nacl-id>
Placement Group for VPC placementGroupId: <placement-group-id>
Public Gateway for VPC publicGatewayId: <pgw-id>
Reservations for VPC reservationId: <reservation-id>
Security Group for VPC securityGroupId: <default-sec-grp-id>
Snapshots snapshotId: <snapshot-id>
SSH Key for VPC keyId:<key-id>
Subnet subnetId: <subnet-id>
Virtual Network Interface virtualNetworkInterfaceId:<virtual-network-interface-id>
Virtual Private Endpoint for VPC endpointGatewayId:<endpoint-gateway-id>
Virtual Private Cloud vpcId: <vpc-id>
Virtual Server for VPC instanceId: <instance-id>
VPN for VPC vpnGatewayID: <vpn-gateway-id>

Review the following tables that outline what types of tasks each role allows when you're working with the VPC Infrastructure Services service. Platform management roles enable users to perform tasks on service resources at the platform level. For example, assign user access to the service, create or delete instances, and bind instances to applications. Service access roles enable user access to VPC Infrastructure Services and the ability to call the VPC Infrastructure Services API.

Table 2. IAM VPC Infrastructure Services platform roles
Platform role Description of actions
Viewer You can view service instances, but you can't modify them.
Operator You can perform platform actions that are required to configure and operate service instances, such as viewing a service dashboard.
Editor You can perform all platform actions except for managing the account and assigning access policies.
Administrator You can perform all platform actions based on the resource this role is assigned, including assigning access policies to other users.
Table 2. IAM VPC Infrastructure service access roles
Service role Description of actions
Reader You can perform read-only actions within a service, such as viewing service-specific resources.
Writer You have permissions beyond the reader role, including creating and editing service-specific resources.
Manager You have permissions beyond the writer role that allows you to complete privileged actions, as defined by the service. In addition, you can create and edit service-specific resources.
VPNClient You need to select only this role if you need to assign access to VPN clients that have user ID and passcode authentication configured. If you need to configure the user ID and passcode authentication, see Configuring user IDs and passcodes.
Bare Metal Advanced Network Operator You have access to modify IP spoofing and infrastructure NAT on bare metal interfaces.
Bare Metal Console Admin You can access the bare metal server console.
IP Spoofing Operator You can enable or disable the IP spoofing check on virtual server instances. Grant this role only if necessary.
Console Administrator You can access the virtual server instance console. This role provides only console access and must be combined with another role that has operator access to the virtual server, such as Operator, Editor, or Administrator.

For more information about the exact actions that are mapped to each role, see Infrastructure Services on the IAM roles and actions page.

The following links take you directly to the specific infrastructure service on the IAM roles and actions page.

Network IAM roles and actions

Compute IAM roles and actions

Storage IAM roles and actions

Some VPC tasks require authorizations for multiple IAM actions. For example, create virtual server instance not only requires is.instance.instance.create, it also requires is.vpc.vpc.operate, is.subnet.subnet.operate, is.security-group.security-group.operate, and is.volume.volume.create. Additional conditional actions might be required. For example, if you provision an instance on a dedicated host, you need is.dedicated-host.dedicated-host-group.operate and is.dedicated-host.dedicated-host.operate. The Virtual Private Cloud API reference includes an Authorization section for each API call, for example, Create an instance.

Assigning access to VPC Infrastructure Services in the console

You have two common ways to assign access in the console:

  • Access policies per user. You can manage access policies per user from the Manage > Access (IAM) > Users page in the console. For more information about the steps to assign IAM access, see Managing access to resources.
  • Access groups. Access groups are used to streamline access management by assigning access to a group once, then you can add or remove users as needed from the group to control their access. You manage access groups and their access from the Manage > Access (IAM) > Access groups page in the console. For more information, see Assigning access to a group in the console.

Assigning access to VPC Infrastructure Services in the CLI

For step-by-step instructions for assigning, removing, and reviewing access, see Assigning access ro resources by using the CLI.

The following example shows a command for assigning the Viewer role for VPC Infrastructure Services:

Use is for the service name. Also, use quotations around role names that are more than one word as shown in the example here.

ibmcloud iam user-policy-create USER@EXAMPLE.COM --service-name is --roles "Viewer"

Assigning access to VPC Infrastructure Services by using the API

For step-by-step instructions for assigning, removing, and reviewing access, see Assigning access to resources by using the API or Create a policy API. Role cloud resource names (CRN) in the following table are used to assign access with the API.

Table 2. VPC Infrastructure Services role ID values for API use
Role name Role CRN
Viewer crn:v1:bluemix:public:iam::::role:Viewer
Operator crn:v1:bluemix:public:iam::::role:Operator
Editor crn:v1:bluemix:public:iam::::role:Editor
Administrator crn:v1:bluemix:public:iam::::role:Administrator
Reader crn:v1:bluemix:public:iam::::serviceRole:Reader
Writer crn:v1:bluemix:public:iam::::serviceRole:Writer
Manager crn:v1:bluemix:public:iam::::serviceRole:Manager
VPNClient crn:v1:bluemix:public:iam::::serviceRole:VPNClient
Bare Metal Advanced Network Operator crn:v1:bluemix:public:iam::::serviceRole:BareMetalAdvancedNetworkOperator
Bare Metal Console Admin crn:v1:bluemix:public:iam::::serviceRole:BareMetalConsoleAdmin
IP Spoofing Operator crn:v1:bluemix:public:iam::::serviceRole:IPSpoofingOperator
Console Administrator crn:v1:bluemix:public:iam::::serviceRole:VirtualServerConsoleAdmin

The following example is for assigning the Viewer role for VPC Infrastructure Services:

Use is for the service name and refer to the Role ID values table to make sure that you're using the correct value for the CRN.

curl -X POST 'https://iam.cloud.ibm.com/v1/policies' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{
  "type": "access",
  "description": "Object Writer role for Cloud Object Storage",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }'
  ],
  "roles":[
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources":[
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "$ACCOUNT_ID"
        },
        {
          "name": "serviceName",
          "value": "is"
        }
      ]
    }
  ]
}
SubjectAttribute subjectAttribute = new SubjectAttribute.Builder()
      .name("iam_id")
      .value("IBMid-123453user")
      .build();

PolicySubject policySubjects = new PolicySubject.Builder()
      .addAttributes(subjectAttribute)
      .build();

PolicyRole policyRoles = new PolicyRole.Builder()
      .roleId("crn:v1:bluemix:public:iam::::role:Viewer")
      .build();

ResourceAttribute accountIdResourceAttribute = new ResourceAttribute.Builder()
      .name("accountId")
      .value("ACCOUNT_ID")
      .operator("stringEquals")
      .build();

ResourceAttribute serviceNameResourceAttribute = new ResourceAttribute.Builder()
      .name("serviceName")
      .value("is")
      .operator("stringEquals")
      .build();

PolicyResource policyResources = new PolicyResource.Builder()
      .addAttributes(accountIdResourceAttribute)
      .addAttributes(serviceNameResourceAttribute)
      .build();

CreatePolicyOptions options = new CreatePolicyOptions.Builder()
      .type("access")
      .subjects(Arrays.asList(policySubjects))
      .roles(Arrays.asList(policyRoles))
      .resources(Arrays.asList(policyResources))
      .build();

Response<Policy> response = service.createPolicy(options).execute();
Policy policy = response.getResult();

System.out.println(policy);
const policySubjects = [
  {
    attributes: [
      {
        name: 'iam_id',
        value: 'IBMid-123453user',
      },
    ],
  },
];
const policyRoles = [
  {
    role_id: 'crn:v1:bluemix:public:iam::::role:Viewer',
  },
];
const accountIdResourceAttribute = {
  name: 'accountId',
  value: 'ACCOUNT_ID',
  operator: 'stringEquals',
};
const serviceNameResourceAttribute = {
  name: 'serviceName',
  value: 'is',
  operator: 'stringEquals',
};
const policyResources = [
  {
    attributes: [accountIdResourceAttribute, serviceNameResourceAttribute]
  },
];
const params = {
  type: 'access',
  subjects: policySubjects,
  roles: policyRoles,
  resources: policyResources,
};

iamPolicyManagementService.createPolicy(params)
  .then(res => {
    examplePolicyId = res.result.id;
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
policy_subjects = PolicySubject(
  attributes=[SubjectAttribute(name='iam_id', value='IBMid-123453user')])
policy_roles = PolicyRole(
  role_id='crn:v1:bluemix:public:iam::::role:Viewer')
account_id_resource_attribute = ResourceAttribute(
  name='accountId', value='ACCOUNT_ID')
service_name_resource_attribute = ResourceAttribute(
  name='serviceName', value='is')
policy_resources = PolicyResource(
  attributes=[account_id_resource_attribute,
        service_name_resource_attribute])

policy = iam_policy_management_service.create_policy(
  type='access',
  subjects=[policy_subjects],
  roles=[policy_roles],
  resources=[policy_resources]
).get_result()

print(json.dumps(policy, indent=2))
subjectAttribute := &iampolicymanagementv1.SubjectAttribute{
  Name:  core.StringPtr("iam_id"),
  Value: core.StringPtr("IBMid-123453user"),
}
policySubjects := &iampolicymanagementv1.PolicySubject{
  Attributes: []iampolicymanagementv1.SubjectAttribute{*subjectAttribute},
}
policyRoles := &iampolicymanagementv1.PolicyRole{
  RoleID: core.StringPtr("crn:v1:bluemix:public:iam::::role:Viewer"),
}
accountIDResourceAttribute := &iampolicymanagementv1.ResourceAttribute{
  Name:     core.StringPtr("accountId"),
  Value:    core.StringPtr("ACCOUNT_ID"),
  Operator: core.StringPtr("stringEquals"),
}
serviceNameResourceAttribute := &iampolicymanagementv1.ResourceAttribute{
  Name:     core.StringPtr("serviceName"),
  Value:    core.StringPtr("is"),
  Operator: core.StringPtr("stringEquals"),
}
policyResources := &iampolicymanagementv1.PolicyResource{
  Attributes: []iampolicymanagementv1.ResourceAttribute{
    *accountIDResourceAttribute, *serviceNameResourceAttribute}
}

options := iamPolicyManagementService.NewCreatePolicyOptions(
  "access",
  []iampolicymanagementv1.PolicySubject{*policySubjects},
  []iampolicymanagementv1.PolicyRole{*policyRoles},
  []iampolicymanagementv1.PolicyResource{*policyResources},
)

policy, response, err := iamPolicyManagementService.CreatePolicy(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(policy, "", "  ")
fmt.Println(string(b))

Assigning access to VPC Infrastructure Services by using Terraform

The following example is for assigning the Viewer role for VPC Infrastructure Services:

Use is for the service name.

resource "ibm_iam_user_policy" "policy" {
  ibm_id = "test@example.com"
  roles  = ["Viewer"]

  resources {
    service = "is"
  }
}

For more information, see ibm_iam_user_policy.

Tips

  • Access to a container resource doesn't automatically grant access to its subresources. For example, granting access to a VPC doesn't grant access to subnets in that VPC.
  • Similarly, access to a subresource does not grant access to its container resource. For example, granting access to a subnet doesn't grant access to that subnet's VPC.
  • In general, to change the relationship between multiple resources, the user must have access to each resource. For example, to attach a network interface to a security group, the user must have access to both the network interface and the security group. For more information, see Required permissions for VPC resources.

For more information about assigning user roles in the UI, see Managing user permissions for VPC resources.

You can also assign user roles by using IBM Cloud® Command Line Interface (CLI). You can select resources by using resource attributes. For more information, see VPC resource attributes.

Resource groups

A resource group is a collection of resources, such as an entire VPC or a single subnet that are associated for establishing authorization and usage. You can think of a resource group as a collection of infrastructure resources that might be used by a project, a department, or a team.

Large enterprises might divide a VPC into various resource groups, whereas smaller companies might need only one resource group because all team members have access to the entire VPC. If you are familiar with OpenStack, a resource group is similar in concept to a Project in OpenStack Keystone.

Assignment of a resource to a resource group can be done only when the resource is created. Resources can't change resource groups after they are created.

If you want to use multiple resource groups, it’s good to plan for how you want to assign the resources and the users in your organization to each resource group.

For more information about resources group, see Resource groups.

Access management tags

Access management tags are metadata that is added to resources to help organize access control relationships. Tags create flexible resource groupings for you to administer.

When you use tags to control access to your resources, your team's projects can grow without requiring updates to IAM policies. You can attach Access Management Tags to VPC Infrastructure Resources and you can define access level to those resources based on tags.

VPC Infrastructure resources have a complex authorization model where a single API call might check authorizations on multiple resources. For such APIs, tags must be attached to all resources that an API needs access to. For more information about required API authorizations, see the VPC API Reference.

If the API call returns UNKNOWN for a resource group name, add Viewer access to resource groups when you create the access management tags policy.

For more information about using access management tags, see the following resources:

Limitations

  1. Some gaps exist between current implementation and the API Spec, which are documented here.

  2. Instance templates and dedicated host groups don't support access management tags. As a result, you can't completely manage Auto scale and Dedicated hosts access by using these tags.

  3. Internet Key Exchange (IKE) and IPsec policy resources that are used in site-to-site VPNs don't support access management tags.

UI Limitations for Assigning Service Defined roles

Assigning Service Defined roles to an access policy with an access management tag by using the UI isn't supported. This feature is supported only through the API and CLI.

Using API for Assigning Service Defined roles

Assigning Service Defined roles to an access policy with an access management tag by using the UI isn't supported. This feature is supported only through the API and CLI. Use the following example for API.

curl --location --request POST 'https://iam.cloud.ibm.com/v1/policies' \
--header 'Content-Type: application/json' \
--header 'Authorization: <your token>' \
--data-raw '{
    "description": "useful description here",
    "type": "access",
    "subjects": [
        {
            "attributes": [
                {
                    "name": "iam_id",
                    "value": "<user iam-id>"
                }
            ]
        }
    ],
    "roles": [
        {
            "role_id": "crn:v1:bluemix:public:is::::serviceRole:VPNClient"
        }
    ],
    "resources": [
        {
            "attributes": [
                {
                            "name": "serviceName",
                            "value": "is",
                            "operator": "stringEquals"
                        },
                        {
                            "name": "accountId",
                            "value": "<your account id>"
                        }
            ],
            "tags":[
                {
                    "name": "abc",
                    "value": "test"
                }
            ]
        }
    ]
}'

Using CLI for Assigning Service Defined roles

Assigning Service Defined roles to an access policy with an access management tag by using the UI isn't supported. This feature is supported only through the API and CLI. Use the following example for CLI.

ic iam access-group-policy-create Developers_MyApp --roles Viewer --service-name kms --tags abc:test