Summary
This end point is used to manage credentials within Cloudability that support the integration and ingestion of data from public cloud vendors. This includes tasks such as initial setup, listing out current credentials and deleting deprecated credentials.
- This endpoint does not support filtering and sorting.
Endpoint Particulars
endpoint: /vendors/AWS/accounts for RESTful CRUD interactions
endpoint: /vendors/AWS/accounts/[vendorAccountId]/verification
endpoint: /vendors/AWS/accounts/[vendorAccountId]/user-to-role-migration
endpoint: /vendors/AWS/accounts/[vendorAccountId]/cloudformation-template
endpoint: /vendors/AWS/accounts/[vendorAccountId]/external-id-rotation
The Credential Object
id (string) - 12 digit string corresponding to your AWS account ID
vendorAccountName (string) - The name give to your AWS account
vendorAccountId (string) - 12 digit string corresponding to your AWS account ID
vendorKey (string) - "aws"
verification (object) - object containing details of verification state:
state (string) - examples "unverified", "verified", "error"
lastVerificationAttemptedAt (string) - date timestamp, example: "1970-01-01T00:00:00.000Z"
message (string) - error message for credentials in error state
authorization (object) - object contain vendor specific authorization details
type (string) - "aws_role" or "aws_user"
roleName (string) - currently hardcoded to "CloudabilityRole",
externalId (string) - the external ID used to prevent confused deputies. Generated by Cloudability
parentAccountId (string) - 12 digit string representing parent's account ID (if current cred is a linked account)
createdAt - (string) - date timestamp corresponding to cloudability credential creation time
Example 'Verified' Linked Account Credentials Object
{
"result": {
"id": "999988887777",
"vendorAccountName": "Account Name",
"vendorAccountId": "999988887777",
"vendorKey": "aws",
"verification": {
"state": "verified",
"lastVerificationAttemptedAt": "2017-11-03T08:35:55.049Z"
},
"authorization": {
"type": "aws_role",
"roleName": "CloudabilityRole",
"externalId": "1265c251-1e14-49db-b933-af3364c8ac77"
},
"parentAccountId": "111122223333",
"createdAt": "2017-11-03T07:35:55.049Z"
}
}
Example Requests
Create Credential for Linked Account
Special Note: If your linked account is brand new to make sure Cloudability is aware of it run a verification on your master payer account. We do have a regular background job to register new accounts, but if your account is brand new do run the verification to guarantee the credential can be created as follows.
curl -X POST 'https://api.cloudability.com/v3/vendors/aws/accounts' \
-H 'Content-Type: application/json' \
-u '[auth_token]:' \
-d @- << EOF
{
"vendorAccountId": "999988887777",
"type": "aws_role"
}
EOF
Upon successful creation the API will return the credentials object
Retrieve Account
curl 'https://api.cloudability.com/v3/vendors/AWS/accounts/[vendorAccountId]' \
-u '[auth_token]:'
Pro Tip!: If you are reviewing a master payer account you can get the payload to include all it's linked accounts by adding include=associatedAccounts as a query parameter. All linked accounts will return as a list of regular credential objects within the associatedAccounts attribute.
Delete Credential for an account
curl -X DELETE 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777' \
-u '[auth_token]:'
List Accounts
curl 'https://api.cloudability.com/v3/vendors/AWS/accounts' \
-u '[auth_token]:'
Verify credentials for an account
curl -X POST 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777/verification' \
-u '[auth_token]:'
Migrate a AWS User Cred to AWS Role
curl -X POST 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777/user-to-role-migration' \
-u '[auth_token]:'
Get CloudFormation Template For Account
curl 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777/cloudformation-template' \
-u '[auth_token]:'
Rotate the external ID
curl -X POST 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777/external-id-rotation' \
-u '[auth_token]:'
Recipe for Adding New Linked Account Credentials (AWS)
- If your linked account is brand new to make sure Cloudability is aware of it run a verification on your master payer account. We do have a regular background job to register new accounts, but if your account is brand new do run the verification to guarantee the credential can be created in the next step.
- Create Credential For Linked Account
- Get Cloudformation Template (CFT) For Account
- Create CFT Stack in AWS via AWS console or AWS API/SDK/CLI (net result is the creation of the IAM role Cloudability assumes)
- Verify Credentials for an account
Recipe for Migrating AWS User Creds to AWS Role creds
- Migrate a AWS User Credential to AWS Role Credential
- Get Cloudformation Template (CFT) For Account
- Create the CFT Stack in AWS via AWS console or AWS API/SDK/CLI
- Verify Credentials for an account
Recipe for rotating External ID
- Rotate ExternalId
- Update CFT Stack in AWS
- Verify Credentials for an account
Recipe for creating credential, retrieving externalID and creating IAM role with your own scripting
The only unique thing about each CloudFormation template is the externalID itself. This is a AWS best practice from a security perspective, but instead of needing to generate a separate template each time you could just activate a credential, retrieve it's externalID and then script on your end to create the role. Here are the calls to do this:
- create the credential within Cloudability
- The externalID is returned within the JSON response from a successful request above. It can also be obtained afterwards by retrieving the account credential.
- Use a script on your end to apply the externalID as a parameter with your own template.
- Verify Credentials for an account
Updated 2 years ago