Skip to main content

The service's own identity

Before Delegaris can assume a role in any account, it needs an AWS identity of its own. This page covers the ways to give it one and what the Accounts page tells you about it.

What the identity needs​

Two permissions: to assume DelegarisRole in the accounts you manage, and to read AWS list prices for cost estimates. This is iam/hub-policy.json:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AssumeDelegarisRoleInManagedAccounts",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::*:role/DelegarisRole"
},
{
"Sid": "ReadListPrices",
"Effect": "Allow",
"Action": "pricing:GetProducts",
"Resource": "*"
}
]
}

Without pricing:GetProducts everything else works, but there are no cost estimates; the service tries again every few hours.

Everything else is granted by the role inside each account. Two optional extras use the service's identity directly:

PermissionForWithout it
s3:PutObject on a backup bucketUploading nightly backups (BACKUP_S3_BUCKET)Backups stay on the data volume only.
s3:PutObject on an audit bucketCopying the activity log to S3The export fails and says why.

iam/hub-role.yaml creates a role with all of this for an EC2 host; see Member account role for its parameters.

What the Accounts page shows​

The top of Accounts checks the service's identity every time the page opens.

When it works, it shows The service signs in to AWS as with the ARN (and a button to copy it), and where the credentials came from, for example "Using the EC2 instance's IAM role". This ARN is the value to give as TrustedPrincipalArn when you create DelegarisRole in an account. What this identity needs opens the policy above, with Copy policy and Download a CloudFormation template.

When there is no identity and nothing needs one, because every account brings its own access keys or Identity Center permission set, it shows The service has no AWS identity of its own and explains that this is fine for now.

When there is a problem, it shows The service cannot sign in to AWS, how many accounts rely on it (and whether backups to S3 do), and the most likely reason:

What it saysWhat to do
The container cannot collect the instance role's credentials, because the metadata service limits its token reply to one network hopRaise the instance's metadata hop limit to 2. The page shows the exact command with Copy command. See Docker on EC2.
The instance has no IAM role attachedAttach one in the EC2 console under Actions > Security > Modify IAM role, or create one from hub-role.yaml.
No AWS credentials were found, and nothing answered at the EC2 metadata addressThe container is not on EC2 (or cannot reach the metadata service). Give it a role another way, or use access keys.
AWS did not accept the service's credentialsThe keys are wrong, deleted or expired. Replace them.
The Identity Center sign-in has run outSign in through Identity Center again, or sign out of it to fall back on the container's own credentials.

After fixing something on the host, choose Check again. None of the fixes needs the container restarting.

The same check runs when the container starts (unless AWS_STARTUP_CHECK=false), and the log says either AWS identity: <arn> (from <source>) or The service cannot sign in to AWS. with the reason and the fix.

Which identity wins​

Delegaris uses the first of these that is set up:

  1. An IAM Identity Center sign-in that has a permission set chosen as the service's identity.
  2. Access keys saved under Accounts in the web UI.
  3. Whatever the container finds for itself, the same way the AWS CLI does: keys in the environment first, then a mounted AWS CLI profile, then the instance or task role.

Changes made in the web UI take effect at once, on every copy of the service.

A role on whatever runs the container: nothing to store, rotate or leak.

  • Docker on an EC2 instance: deploy iam/hub-role.yaml with CloudFormation in the instance's account and attach the instance profile it creates to the instance. Then raise the metadata hop limit; see Docker on EC2.
  • ECS: give the task role the policy above. It reaches the container with no further steps.
  • EKS: give the IRSA or Pod Identity role the policy above.

Option 2: access keys saved in the web UI​

The quickest way to a working set-up, and the one to use while the instance role is being sorted out.

  1. Create an IAM user with the policy above and an access key for it.
  2. On Accounts, choose Use access keys….
  3. Paste what AWS gave you into Paste what AWS gave you. It reads the export AWS_ACCESS_KEY_ID=… lines, a credentials-file profile ([name] with aws_access_key_id=…), PowerShell's $Env:AWS_… lines, or the bare values, and fills in Access key ID, Secret access key and Session token. Nothing is sent until you choose to use them.
  4. Choose Use these keys. Delegaris tries them against AWS first, and refuses keys AWS does not accept.

The top of the page then says which access key is saved, by whom and when, with Replace… and Remove, and use what the container has. The saved keys override anything the container found for itself, on every copy of the service, until you remove them.

Temporary keys (starting ASIA…, from IAM Identity Center or an assumed role) work too, with their session token. They expire within hours, after which AWS refuses them and you paste a fresh set. Fine for trying things out, not for leaving running.

warning

The secret is stored in the service's database and never shown again. Protect the /data volume (/var/lib/delegaris with the Linux package) or the PostgreSQL database as you would the key itself. Keep the user's policy to the two statements above, and rotate the key.

Option 3: keys or a profile in the environment​

  • Keys: set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env.
  • A mounted AWS CLI profile: if the host already has aws configure set up, mount that folder read-only and name the profile. The lines are in docker-compose.yml, commented out:
environment:
AWS_SHARED_CREDENTIALS_FILE: /aws/credentials
AWS_CONFIG_FILE: /aws/config
AWS_PROFILE: delegaris
volumes:
- delegaris-data:/data
- /home/ec2-user/.aws:/aws:ro

Environment keys win over a profile, and both win over the instance role. Profiles that sign in through IAM Identity Center (aws sso login) expire within hours and are not suitable for a service; use option 4 instead.

Option 4: sign in through IAM Identity Center​

Delegaris can sign itself in to IAM Identity Center (AWS SSO) from your start URL, the way aws sso login does. Nothing is pasted, and it renews its own temporary credentials.

  1. On Accounts, choose Sign in through Identity Center….
  2. Enter the Start URL (https://your-org.awsapps.com/start) and the Identity Center region: where Identity Center is enabled, which need not be where your machines are. Choose Start sign-in.
  3. A new tab opens at AWS. Check it shows the same code as the dialog, and approve the sign-in there. The dialog waits until you have.
  4. Choose a permission set under The service signs in as. This becomes the service's own identity, so it needs sts:AssumeRole for accounts added with a role. Choose Leave as it is to keep the current identity.
  5. Under Add accounts, tick the accounts to add, adjust Name here and pick the Permission set for each. They are added to manage EC2 and RDS in the default regions; change that on each account afterwards.
  6. Choose Finish.

The top of the Accounts page then shows where the service is signed in, by whom, and which permission set it uses, with Sign in again, or add accounts… and Sign out. Accounts added this way show "Identity Center" and the permission set in the list.

Things to know:

  • The service acts as you in AWS, so CloudTrail shows your name. That makes it right for trying things out and for small teams; an instance role is the better choice for a shared production service.
  • It renews its credentials for as long as your Identity Center session lasts, typically days or weeks depending on how Identity Center is configured. When that runs out, the top of the page says so: sign in again.
  • Sign out forgets the session. Accounts added through Identity Center stop working until the next sign-in, and the service falls back on its other credentials.
  • The sign-in is kept in the service's database, so every copy of the service shares it.

Audit​

Saving or removing access keys, and each Identity Center sign-in, sign-out and change of permission set, is recorded in Activity with who did it.

Next steps​