API Task - Manage AWS Configurations
Warning
API access is migrating to Enterprise only. Beginning in Release 9.5, all new or renewed subscriptions have access to public API endpoints on the Enterprise product edition only. Existing customers on non-Enterprise editions will retain access their available endpoints (Legacy) until their subscription expires. To use API endpoints after renewal, you must upgrade to the Enterprise product edition or use a reduced set of endpoints (Current). For more information on differences between product editions in the new model, please visit Pricing and Packaging.
Overview
The Alteryx Analytics Cloud supports multiple methods of authenticating to AWS resources. At the topmost level, authentication can be broken down into two modes: system and user.
System mode: One set of credentials is used for each user of the platform to authenticate to AWS.
User mode: Individual user accounts must be configured with AWS credentials.
Note
This section covers how to manage AWS credentials through the APIs for individual users (user mode). When in system mode, please manage AWS configuration through the application.
Per-User Authentication Methods
To connect to AWS resources and access S3 data, the following information is required for each user, depending on the method of authentication.
Note
Since instance credentials are provided at the system level, use of the instance credential provider type in AWS configuration objects is not supported.
Method 1 - AWS Key and Secret
If users are providing key-secret combinations, the following information is required.
Item | Description |
---|---|
key/secret | (credential provider type is |
default bucket | The default S3 bucket where the user can upload data and store generated results |
extra buckets | Any extra S3 buckets to which the user should have access |
Method 2 - AWS IAM Role ARNs
Users can access AWS resources by assigning an awsConfig object to the account.
Tip
This method is recommended.
The following information is required:
Item | Description |
---|---|
IAM role | (credential provider type is Note If this information is not immediately available, a placeholder one is created when you create the configuration object. You can assign roles later. More information is provided below. |
default bucket | The default S3 bucket where the user can upload data and store generated results |
extra buckets | Any extra S3 buckets to which the user should have access |
Authentication objects
For each authentication method, the above pieces of information must be provided for each user.
These pieces of information are defined in an awsConfig
object. An awsConfig object is a set of AWS configuration properties that can be created, modified, and assigned to individual users via API.
For Method 2, the awsConfig object maps to an awsRole object. An awsRole object references an IAM role and an awsConfig object. When you create an awsConfig object and its credential provider is set to temporary
, the awsRole object is automatically created for you:
Each awsRole object maps to a single IAM role.
Each awsRole object is mapped to an awsConfig object.
The awsConfig object is then assigned to individual users.
Through this mechanism, you have more flexibility in assigning the active role to users.
As needed, the awsConfig object can be mapped at a later time to another awsRole object through the
role
attribute.
This approach steps through the process for all these methods.
Platform roles
Your account must have one of the following roles:
Workspace admin
For more information, see
Designer Cloud Powered by Trifacta: API Reference docs
Basic Steps
Choose your method of authentication.
Locate the internal identifier for the user to which to assign the configuration object.
Create an
awsConfig
object, assigning the object to the user as part of the process.Verify that the assignment is working.
Step - Acquire information
Acquire all of the information listed above for the awsConfig object you wish to create.
Step - Locate user
Now, you need to locate the internal identifier for the user to which you wish to assign this AWS configuration.
Request:
Endpoint | http://www.wrangle-dev.example.com:3005/v4/people |
---|---|
Authentication | Required |
Method | GET |
Request Body | None. |
Response:
Status Code | 200 - Ok |
---|---|
Response Body | { "data": [ { "id": 3, "email": "4070250@example.com", "name": "Test User4070250", "ssoPrincipal": null, "hadoopPrincipal": null, "isAdmin": false, "isDisabled": false, "forcePasswordChange": false, "state": "active", "lastStateChange": null, "createdAt": "2019-04-16T16:27:51.143Z", "updatedAt": "2019-04-16T16:27:56.630Z", "outputHomeDir": "/trifacta/queryResults/4070250@example.com", "fileUploadPath": "/trifacta/uploads", "awsConfigId": 2 }, { "id": 2, "email": "32870@example.com", "name": "Test User32870", "ssoPrincipal": null, "hadoopPrincipal": null, "isAdmin": false, "isDisabled": false, "forcePasswordChange": false, "state": "active", "lastStateChange": null, "createdAt": "2019-04-16T16:27:19.511Z", "updatedAt": "2019-04-16T16:27:26.703Z", "outputHomeDir": "/trifacta/queryResults/32870@example.com", "fileUploadPath": "/trifacta/uploads", "awsConfigId": 1 }, { "id": 1, "email": "<admin_email>", "name": "Administrator", "ssoPrincipal": null, "hadoopPrincipal": null, "isAdmin": true, "isDisabled": false, "forcePasswordChange": false, "state": "active", "lastStateChange": null, "createdAt": "2019-04-16T07:44:04.299Z", "updatedAt": "2019-04-16T16:28:16.379Z", "outputHomeDir": "/trifacta/queryResults/admin@example.com", "fileUploadPath": "/trifacta/uploads", "awsConfigId": 3 } ] } |
Tip
In the above, you noticed that userId=2 is associated with awsConfig object id=1, which is the one you are replacing. This is the user to modify. Retain this value for later.
For more information, see Designer Cloud Powered by Trifacta: API Reference docs
Step - Create awsConfig object
Create the AWS configuration object.
Note
Optionally, the personId
value can be inserted into the request to assign the AWS configuration object to a specific user at create time, when it is created by an admin user. If it is created by a non-admin user, the object is assigned to the user who created it.
Note
For Method 2, an awsRole object is automatically created for you when you create the awsConfig object. It is mapped to the awsConfig object.
Request:
Endpoint | http://www.wrangle-dev.example.com:3005/v4/awsConfigs |
---|---|
Authentication | Required |
Method | POST |
Request Body | Method 1: AWS key-secret combination { "credentialProvider": "default", "personId": 2, "key": "<my_key>", "secret": "<my_secret>", "defaultBucket": "main_bucket", "extraBuckets":["extra-bucket1","extra-bucket2"] } Method 2: IAM role { "credentialProvider": "temporary", "personId": 2, "role":"<my_iam_role_object>", "defaultBucket":"main_bucket", "extraBuckets":["extra-bucket1","extra-bucket2"] } |
Response for Method 2:
Status Code | 201 - Created |
---|---|
Response Body | Method 2 example: { "extraBuckets": [ "extra-bucket1", "extra-bucket2" ], "id": 6, "defaultBucket": "main_bucket", "credentialProvider": "temporary", "externalId": null, "activeRoleId":"4", "updatedAt": "2019-04-16T23:06:32.049Z", "createdAt": "2019-04-16T23:06:32.047Z", "credential": null } |
Tip
In the above, the awsConfig object has an internal identifier (id=6
).
As part of the request, this object was assigned to user 2 personId=2
.
The activeRoleId
attribute indicates that the internal ID of the awsRole object that was automatically created for you.
For more information, see Designer Cloud Powered by Trifacta: API Reference docs
Step - Verify Authentication
To verify that the above configuration works:
User id=2 should login to the application.
User uploads assets through the Import Data page.
User creates a short recipe that modifies these assets.
User runs a job on that recipe to generate output to the default S3 bucket in CSV or JSON for downloading.
User verifies that the results can be downloaded.
Tip
Configuration and verification is complete.
Step - For Method 2, assign new IAM role to awsConfig object
If you need to change the IAM role ARN for a user, you can modify the awsConfig object for that user with the new role information.
Note
This section only applies if credentialProvider
has been set to temporary
for the object and if you are using multiple IAM role ARNs in the Alteryx Analytics Cloud.
The following request modifies the awsConfig id=6
.
Request:
Endpoint | http://www.wrangle-dev.example.com:3005/v4/awsConfigs/6 |
---|---|
Authentication | Required |
Method | PATCH |
Request Body | { "role":"<my_iam_role_object_3>" } |
Response:
Status Code | 200 - OK |
---|---|
Response Body | { "extraBuckets": [ "extra-bucket1", "extra-bucket2" ], "id": 6, "defaultBucket": "main_bucket", "credentialProvider": "temporary", "externalId": null, "activeRoleId":"<awsRoleId>", "updatedAt": "2019-04-16T23:06:32.049Z", "createdAt": "2019-04-16T23:06:32.047Z", "credential": null } |
Tip
In the above step, you assigned a new IAM role to the awsConfig object. The underlying awsRole object is created for you and automatically assigned. For more information, see Designer Cloud Powered by Trifacta: API Reference docs
Note
After you have completed the above update, the previous awsRole object still exists. If the IAM role associated with it is no longer in use, you should delete the awsRole object. See Designer Cloud Powered by Trifacta: API Reference docs
Step - Switching Persons or Workspaces for an awsRole
When you create or modify an awsRole, you can optionally pass in a person or workspace identifier. When either value is provided, the Alteryx Analytics Cloud attempts to assign the awsRole to the provided identifier based on the related awsConfig object.
Acquire awsRole identifier
Via awsConfig identifier
Use the following endpoint to retrieve the awsConfig object. This one uses awsConfigId=6:
Request:
Endpoint | http://www.wrangle-dev.example.com:3005/v4/awsConfigs/6 |
---|---|
Authentication | Required |
Method | GET |
Request Body | Empty. |
Response:
Status Code | 200 - OK |
---|---|
Response Body | { "extraBuckets": [ "extra-bucket1", "extra-bucket2" ], "id": 6, "defaultBucket": "main_bucket", "credentialProvider": "temporary", "externalId": null, "activeRoleId":"<awsRoleId>", "updatedAt": "2019-04-16T23:06:32.049Z", "createdAt": "2019-04-16T23:06:32.047Z", "credential": null } |
Acquire the value for activeRoleId
.
Via awsRoles identifier
Use the following request to retrieve all of the awsRoles:
Request:
Endpoint | http://www.wrangle-dev.example.com:3005/v4/awsRoles |
---|---|
Authentication | Required |
Method | GET |
Request Body | Empty. |
In the response, locate the appropriate identifier.
Reassign the awsRole
You can use the PUT method of the following endpoint to re-assign the awsRole to the specified person or workspace. The following example reassigns awsRoleId=3 to personId=6.
Request:
Endpoint | http://www.wrangle-dev.example.com:3005/v4/awsRoles/3 |
---|---|
Authentication | Required |
Method | PUT |
Request Body | { "personId": 6 } |
If the request is successful, the awsRole is reassigned to the person identifier.
Tip
In the above request, you can replace "personId"
with "workspaceId"
to reassign the role to all users in a workspace.
Step - Switching Authentication Methods
Suppose you have created your awsConfig objects to use the AWS Key-Secret method of authenticating. You have now created a set of IAM roles that you would like to assign to your Alteryx users.
The generalized steps for completing this task is the following:
Acquire the identifiers for all of the awsConfigs you wish to modified. For each awsConfig, retain the
personId
, so that you can map your configuration changes to individuals. See Designer Cloud Powered by Trifacta: API Reference docsFor more information on getting your list of users, see Designer Cloud Powered by Trifacta: API Reference docs
For each user account (
personId
), you must identify the IAM role that you wish to assign it.Use the following modification to the awsConfig object to switch to using the IAM role for the user:
Request:
Endpoint | http://www.wrangle-dev.example.com:3005/v4/awsConfigs/<awsConfigId> |
---|---|
Authentication | Required |
Method | PUT |
Request Body | { "credentialProvider": "temporary", "role":"<my_iam_role_object>" } |
Response for Method 2:
Status Code | 200 - Ok |
---|---|
Response Body | Method 2 example: { "extraBuckets": [ "extra-bucket1", "extra-bucket2" ], "id": <awsConfigId>, "defaultBucket": "main_bucket", "credentialProvider": "temporary", "externalId": null, "activeRoleId":"<awsRoleId>", "updatedAt": "2019-04-16T23:06:32.049Z", "createdAt": "2019-04-16T23:06:32.047Z", "credential": null } |
Notes:
Item | Description |
---|---|
credentialProvider | To use IAM roles, this attribute must be updated to be |
role | The IAM role to assign to the configuration. |
personId | If needed, you can change the person (user) to which this awsConfig is applied. Note that the former user of the configuration cannot access AWS resources until you create a new configuration object for the user's account. |
activeRoleId | (response) Internal identifier of the awsRole object that was created for you and assigned to this awsConfig object. |
Note
The above request must be applied to each awsConfig object that you wish to remap to using an IAM role.