Set up the AWS connector

The AWS connector runs as part of the Ploy Connector, a single self-contained binary that runs inside your network and initiates outbound HTTPS to Ploy. It scans AWS IAM Identity Center (AWS SSO) users, groups, memberships, permission sets, and their account assignments. Optional group_management lets Ploy add or remove user memberships in Identity Center groups.

What you need before you start

The Ploy Connector binary for your platform (Linux amd64/arm64 or Windows amd64), downloaded from the Ploy console.
An AWS IAM Identity Center instance provisioned in a known AWS region.
An AWS identity that the connector can use, with the required IAM policy attached.
A connector bearer key from the Ploy admin UI. It must start with ploy_ct_.
Outbound HTTPS (port 443) from the connector host to api.joinploy.com.

AWS authentication options

AWS credentials never flow through Ploy. The connector uses the aws-sdk-go-v2 default credential chain, so the simplest and most secure setup is to run the connector on AWS compute and supply no keys at all.

Recommended approaches:

Run the connector on EC2 with an instance profile.
Run the connector on EKS with IRSA.
Run the connector on ECS with a task role.

Off-AWS hosts: put static credentials under credentials in the config file, referencing them with URI prefixes such as env://AWS_ACCESS_KEY_ID or literal://....

Required IAM policy

Attach this policy to the identity the connector runs as. The read actions cover scan; the last four actions (starting with identitystore:DescribeGroup) are only needed if you enable group_management:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity",
        "sso:ListInstances",
        "sso:ListPermissionSets",
        "sso:DescribePermissionSet",
        "sso:ListAccountsForProvisionedPermissionSet",
        "sso:ListAccountAssignments",
        "identitystore:ListUsers",
        "identitystore:ListGroups",
        "identitystore:ListGroupMemberships",
        "identitystore:DescribeGroup",
        "identitystore:CreateGroupMembership",
        "identitystore:GetGroupMembershipId",
        "identitystore:DeleteGroupMembership"
      ],
      "Resource": "*"
    }
  ]
}

Configure the connector

Create or edit the connector's config.yaml. On Linux the default path is /etc/ploy-connector/config.yaml; on Windows it is %ProgramData%\Ploy\Connector\config.yaml.

Add an AWS integration block. The slug (for example aws) must be unique within this connector:

backend:
  key: env://PLOY_CONNECTOR_KEY

integrations:
  aws:
    type: aws
    enabled_features: [scan, group_management]
    credentials:
      region: literal://eu-west-2

When running on AWS compute with ambient credentials, omit access_key_id, secret_access_key, session_token, and role_arn. The region is required and must match the region where your Identity Center instance lives. If the region is wrong, the integration reports health degraded with the message no Identity Center instance found.

Off-AWS example with static credentials:

integrations:
  aws:
    type: aws
    enabled_features: [scan, group_management]
    credentials:
      region: literal://eu-west-2
      access_key_id: env://AWS_ACCESS_KEY_ID
      secret_access_key: env://AWS_SECRET_ACCESS_KEY
      # session_token: env://AWS_SESSION_TOKEN
      # role_arn: literal://arn:aws:iam::123456789012:role/PloyConnector

Scope and filtering

The connector applies two scoping layers to groups. A group must pass both to be scanned or written:

Local scope (config.yaml) — scope.group_include and scope.group_exclude are the floor. The Ploy dashboard can only narrow within these, never widen. Empty group_include means all groups pass this layer.
Server-side settings — group_include and group_exclude globs set in the Ploy admin UI further restrict the result.

Server-owned settings

These values are delivered from Ploy at runtime and can be adjusted without restarting the connector:

Setting	Default	Meaning
`scan_interval`	`15m`	How often to scan (Go duration string).
`group_include`	`[]`	Group display-name globs to include. Empty means all groups.
`group_exclude`	`[]`	Group display-name globs to exclude. Excludes always win.
`scan_account_assignments`	`true`	Scan group-to-permission-set assignments across accounts. Disable on very large multi-account orgs if the scan is too costly.

Feature flags

scan — read users, groups, memberships, permission sets, and account assignments from Identity Center.
group_management — accept tasks that add or remove a user from an Identity Center group using CreateGroupMembership / DeleteGroupMembership. Classic IAM groups are deliberately refused.

Install and run the service

Windows — install as a service from an Administrator shell:

cd "C:\Program Files\Ploy\Connector"
.\ploy-connector.exe install-service
Start-Service PloyConnector

Linux — run directly or via systemd. A sample systemd unit ships in the release tarball:

sudo systemctl enable --now ploy-connector

You can also run the binary directly for testing:

./ploy-connector -config /etc/ploy-connector/config.yaml

Verify the setup

Open the Ploy admin UI and go to Integrations > Connectors. Within about 30 seconds the connector should report online with a recent heartbeat.
On Windows, tail the log at C:\ProgramData\Ploy\Connector\logs\connector.log. On Linux, check journalctl -u ploy-connector or stdout.
On a healthy startup you will see connector starting, then manifest registered, then periodic scan completed lines. A failed partial scan uploads nothing that cycle and flips the integration health to degraded so the failure is visible.

Update or uninstall

Updates are drop-in replacements. Stop the service, replace the binary, and restart. Config and state persist across upgrades.

On Windows:

Stop-Service PloyConnector
Copy-Item .\ploy-connector.exe "C:\Program Files\Ploy\Connector\" -Force
Start-Service PloyConnector

Was this helpful?