Skip to main content

Manage integration roles

Learn how to use the Storage Access API to manage integration roles for InsuranceSuite applications.

Note:

To manage roles, you need to authenticate with Guidewire Hub and obtain an access token with the following scopes:

  • storage.roles.write, tenant.{tenantId}
  • storage.roles.read, tenant.{tenantId}

Users with the write scope have the read scope granted automatically.

All sample requests in this guide include the following path parameters:

Parameter nameDescription
tenantIdYour tenant ID.
projectIdID of the star system (physical star system) for which you modify a role.

Create an integration role​

To create an integration role, send the following POST request:

curl -X 'POST' \
  '{baseUrl}/api/v2/tenants/{tenantId}/projects/{projectId}/integration-roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'\
  -d '{body}'

Where {body} contains the provided role data. For example, to create an integration role, use the following:

Example request body
{
  "externalIds": ["secret_value"],
  "integration": "integrationname",
  "roleTypes": ["INBOUND"],
  "trustedEntity": "012345678901",
  "policyData": {
    "allowedIPs": ["70.22.22.22/24", "66.22.22.22/32"],
    "allowedVPCEs": ["vpce-0dbabcdddd", "vpce-0dbabcdfgh"]
  }
}

Where:

  • externalIds

    Additional values for validation when assuming the cross-account role, such as passwords. For details, see AWS Documentation.

    With API, you can add more than one value. A user can assume a role by providing one of them.

  • integration

    Name of the integration from the related InsuranceSuite application. This parameter impacts the S3 prefix for accessing the integration.

  • roleTypes

    Requested types of access that need to be added to a role. You can use multiple values from the following options:

    • INBOUND for inbound read/write integration
    • OUTBOUND for outbound read/delete integration
    • EXTERNAL_PRODUCER for outbound write integration

    For details, see IAM external role permissions.

  • trustedEntity

    The ID of the AWS account for which the role can be assumed.

  • policyData

    Provides additional policy data and can use the following optional parameters:

    • policyData.allowedIPs with a list allowed IP addresses that can access an S3 bucket.
    • policyData.allowedVPCes with a list of allowed VPC (Virtual Private Cloud) endpoints that can access an S3 bucket.

Response contains a JSON object with a created role and attached policies, for example:

Example response
{
  "roleArn": "arn:aws:iam::335666778967:role/tenant-guidewire-pentstdev-dev-storage-role-integrationname",
  "roleName": "tenant-guidewire-pentstdev-orange-dev-storage-role",
  "roleUsageType": "VENDOR",
  "storageAccessType": "IS",
  "integration": "integrationname",
  "principal": "012345678901",
  "policyArns": [
    "arn:aws:iam::942795021942:policy/tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
  ],
  "policies": [
    {
      "name": "tenant-guidewire-pentstdev-dev-storage-inbound-integrationname",
      "type": "INBOUND",
      "arn": "arn:aws:iam::942795021942:policy/tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
    }
  ],
  "allowedIPs": ["70.22.22.22/24", "66.22.22.22/32"],
  "allowedVPCEs": ["vpce-0dbabcdddd", "vpce-0dbabcdfgh"]
}

Where:

  • roleName follows the tenant-{tenant}-{project}-{stage}-storage-role-{integration} schema.

  • 335666778967 in the role ARN represents the AWS account ID that owns the resource.


Get IAM integration role details​

To get the IAM integration role details, use the following GET request:

curl -X 'GET' \
  '{baseUrl}/api/v2/tenants/{tenantId}/projects/{projectId}/integration-roles/{integrationName}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

Where integrationName is the name of requested integration.

Response contains a JSON object with a requested role details, for example:

Example response
{
  "roleArn": "arn:aws:iam::335666778967:role/tenant-guidewire-pentstdev-dev-storage-role-integrationname",
  "roleName": "tenant-guidewire-pentstdev-orange-dev-storage-role",
  "roleUsageType": "VENDOR",
  "storageAccessType": "IS",
  "integration": "integrationname",
  "principal": "012345678901",
  "policyArns": [
    "arn:aws:iam::335666778967:policy/tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
  ],
  "policies": [
    {
      "name": "tenant-guidewire-pentstdev-dev-storage-inbound-integrationname",
      "type": "INBOUND",
      "arn": "arn:aws:iam::335666778967:policy/tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
    }
  ],
  "allowedIPs": ["70.22.22.22/24", "66.22.22.22/32"],
  "allowedVPCEs": ["vpce-0dbabcdddd", "vpce-0dbabcdfgh"]
}

Get details of all IAM roles​

To get details of all IAM roles, use the following GET request:

curl -X 'GET' \
  '{baseUrl}/api/v2/tenants/{tenantId}/projects/{projectId}/all-roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

Response contains a JSON object with role details, for example:

Example response with one role
[
  {
    "roleArn": "arn:aws:iam::335666778967:role/tenant-guidewire-pentstdev-dev-storage-role-integrationname",
    "roleName": "tenant-guidewire-pentstdev-orange-dev-storage-role",
    "roleUsageType": "VENDOR",
    "storageAccessType": "IS",
    "integration": "integrationname",
    "principal": "012345678901",
    "policyArns": [
      "arn:aws:iam::335666778967:policy/tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
    ],
    "policies": [
      {
        "name": "tenant-guidewire-pentstdev-dev-storage-inbound-integrationname",
        "type": "INBOUND",
        "arn": "arn:aws:iam::335666778967:policy/tenant-tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
      }
    ],
    "allowedIPs": ["70.22.22.22/24", "66.22.22.22/32"],
    "allowedVPCEs": ["vpce-0dbabcdddd"]
  }
]

Update an IAM integration role​

Important:

Note that policies are shared between IAM user and internal IAM role access points. This means that when you configure IP ranges and VPC endpoints for an IAM user, the same settings will automatically apply to an internal IAM role. If IP ranges or VPC endpoints aren't specified or left empty, the existing access conditions will be deleted.

If multiple policies are assigned to a role, such as inbound, outbound, and bucket, the same access conditions will be applied to all these policies.

To update a role, send the following PUT request:

curl -X 'PUT' \
  '{baseUrl}/api/v2/tenants/{tenantId}/projects/{projectId}/integration-roles' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'\
  -d '{body}'

Where {body} contains the provided role data. For example, to delete a VPC endpoint from an InsuranceSuite role, use the following:

Example request body
{
  "externalIds": ["secret_value"],
  "integration": "integrationname",
  "roleTypes": ["INBOUND", "OUTBOUND"],
  "trustedEntity": "012345678901",
  "policyData": {
    "allowedIPs": ["70.22.22.22/24", "66.22.22.22/32"],
    "allowedVPCEs": ["vpce-0dbabcdddd", "vpce-0dbabcdfgh"]
  }
}

Response contains updated role data and attached policies, for example:

Example response
{
  "roleArn": "arn:aws:iam::335666778967:role/tenant-guidewire-pentstdev-dev-storage-role-integrationname",
  "roleName": "tenant-guidewire-pentstdev-orange-dev-storage-role",
  "roleUsageType": "VENDOR",
  "storageAccessType": "IS",
  "integration": "integrationname",
  "principal": "012345678901",
  "policyArns": [
    "arn:aws:iam::335666778967:policy/tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
  ],
  "policies": [
    {
      "name": "tenant-guidewire-pentstdev-dev-storage-inbound-integrationname",
      "type": "INBOUND",
      "arn": "arn:aws:iam::335666778967:policy/tenant-guidewire-pentstdev-dev-storage-inbound-integrationname"
    }
  ],
  "allowedIPs": ["70.22.22.22/24", "66.22.22.22/32"],
  "allowedVPCEs": ["vpce-0dbabcdddd"]
}

Delete an IAM integration role​

To delete an IAM integration role, send the following DELETE request without a request body:

curl -X 'DELETE' \
  '{baseUrl}/api/v2/tenants/{tenantId}/projects/{projectId}/integration-roles/{integrationName}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

Where integrationName is the name of the requested integration.

For a successful request, you'll receive the 204 status code.