Setup
commonfate/ecs-exec-sso@v1-alpha1
Example granted_deployment.yml
version: 2
deployment:
stackName: example
account: "12345678912"
region: ap-southeast-2
release: v0.12.0
parameters:
CognitoDomainPrefix: example
AdministratorGroupID: granted_administrators
ProviderConfiguration:
ecs-exec-sso:
uses: commonfate/ecs-exec-sso@v1-alpha1
with:
ecsClusterArn: ""
ecsRegion: ""
ecsRoleArn: ""
identityStoreId: ""
instanceArn: ""
ssoRegion: ""
ssoRoleArn: ""
Find the AWS SSO instance details
Configuration Fields
This step will guide you through collecting the values for these fields required to setup your provider.
Field | Description |
---|---|
identityStoreId | The AWS SSO Identity Store ID |
instanceArn | The AWS SSO Instance ARN |
ssoRegion | The region the AWS SSO instance is deployed to |
Using the AWS CLI
If you have the AWS CLI installed and can access the account that your AWS SSO instance is deployed to, run the following command to retrieve details about the instance:
aws sso-admin list-instances
You will see an output similar to the following:
{
"Instances": [
{
"InstanceArn": "arn:aws:sso:::instance/ssoins-1234567890",
"IdentityStoreId": "d-1234567890"
}
]
}
The InstanceArn value in the CLI output should be provided as the instanceArn parameter when configuring the provider.
The IdentityStoreId field in the CLI output should be provided as the identityStoreId parameter when configuring the provider.
If your AWS SSO instance is deployed in a separate region to the region that Common Fate is running in, set the region parameter to be the region of your AWS SSO instance (e.g. 'us-east-1').
Using the AWS Console
Open the AWS console in the account that your AWS SSO instance is deployed to. If your company is using AWS Control Tower, this will be the root account in your AWS organisation.
Visit the Settings tab. The information about your SSO instance will be shown here, including the Instance ARN (as the “ARN” field) and the Identity Store ID.
Locating your ECS Resources
Configuration Fields
This step will guide you through collecting the values for these fields required to setup your provider.
Field | Description |
---|---|
ecsClusterArn | The ARN of the ECS Cluster to provision access to |
ecsRegion | The region the ecs cluster instance is deployed to |
Locating your ECS Cluster
Locate your chosen ecsClusterArn
by running the following command:
> aws ecs list-clusters
{
"clusterArns": [
"arn:aws:ecs:ap-southeast-2:1234567890:cluster/MyFirstCluster",
"arn:aws:ecs:ap-southeast-2:1234567890:cluster/MySecondCluster",
"arn:aws:ecs:ap-southeast-2:1234567890:cluster/MyThirdCluster",
]
}
Copy in the ARN of the ECS cluster you want to set up the Access Provider for.
Enter the region where your cluster is deployed.
Create a SSO IAM role
Configuration Fields
This step will guide you through collecting the values for these fields required to setup your provider.
Field | Description |
---|---|
ssoRoleArn | The ARN of the AWS IAM Role with permission to administer SSO |
This Access Provider requires permissions to manage your SSO instance.
The following instructions will help you to setup the required IAM Role with a trust relationship that allows only the Common Fate Access Handler to assume the role.
This role should be created in the root account of your AWS organization. This is the account where AWS SSO is configured and your AWS Organization is managed.
Copy the following YAML and save it as 'common-fate-access-handler-ecs-exec-sso-role.yml'.
We recommend saving this alongside your deployment.yml file in source control.
Resources:
CommonFateAccessHandlerSSORole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Statement:
- Action: sts:AssumeRole
Effect: Allow
Principal:
AWS: "{{ Access Handler Execution Role ARN }}"
Version: "2012-10-17"
Description: This role grants management access to AWS SSO for the Common Fate Access Handler.
Policies:
- PolicyDocument:
Statement:
- Action:
- sso:DescribeAccountAssignmentDeletionStatus
- sso:DescribeAccountAssignmentCreationStatus
- sso:DescribePermissionSet
- sso:ListPermissionSets
- sso:ListTagsForResource
- sso:ListAccountAssignments
- organizations:ListAccounts
- organizations:DescribeAccount
- organizations:DescribeOrganization
- iam:GetSAMLProvider
- iam:GetRole
- iam:ListAttachedRolePolicies
- iam:ListRolePolicies
- identitystore:ListUsers
- iam:ListRoles
- iam:ListUsers
Effect: Allow
Resource: "*"
Sid: ReadSSO
- Action:
- sso:DeletePermissionSet
- sso:DeleteAccountAssignment
- sso:CreatePermissionSet
- sso:PutInlinePolicyToPermissionSet
- sso:CreateAccountAssignment
Effect: Allow
Resource: "*"
Sid: AssignSSO
Version: "2012-10-17"
PolicyName: AccessHandlerSSOPolicy
Outputs:
RoleARN:
Value:
Fn::GetAtt:
- CommonFateAccessHandlerSSORole
- Arn
Using the AWS CLI
If you have the AWS CLI installed and can deploy cloudformation you can run the following commands to deploy this stack. Ensure you have credentials for the same account that Common Fate is deployed to and that AWS_REGION environment variable is set correctly, we recommend deploying this role to the same region as your Common Fate stack.
aws cloudformation deploy --template-file common-fate-access-handler-ecs-exec-sso-role.yml --stack-name Common-Fate-Access-Handler-ECS-Exec-SSO-Role --capabilities CAPABILITY_IAM
Once the stack is deployed, you can retrieve the role ARN by running the following command.
aws cloudformation describe-stacks --stack-name Common-Fate-Access-Handler-ECS-Exec-SSO-Role --query "Stacks[0].Outputs[0].OutputValue"
Using the AWS Console
Open the AWS Console to Cloudformation in the root account of your AWS organization and click Create stack then select with new resources (standard) from the menu.
Upload the template file
Name the stack 'Common-Fate-Access-Handler-ECS-Exec-SSO-Role'
Click Next
Click Next
Acknowledge the IAM role creation check box and click Create Stack
Copy the RoleARN output from the stack and paste it in the ssoRoleArn config value on the right.
Create an ECS IAM role
Configuration Fields
This step will guide you through collecting the values for these fields required to setup your provider.
Field | Description |
---|---|
ecsRoleArn | The ARN of the AWS IAM Role with permission to read ECS |
This Access Provider requires permissions to read ECS properties.
The following instructions will help you to setup the required IAM Role with a trust relationship that allows only the Common Fate Access Handler to assume the role.
This role should be created in the same account where your cluster is deployed.
Copy the following YAML and save it as 'common-fate-access-handler-ecs-exec-ecs-role.yml'.
We recommend saving this alongside your deployment.yml file in source control.
Resources:
CommonFateAccessHandlerECSRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Statement:
- Action: sts:AssumeRole
Effect: Allow
Principal:
AWS: "{{ Access Handler Execution Role ARN }}"
Version: "2012-10-17"
Description: This role grants read access to ECS for the Common Fate Access Handler.
Policies:
- PolicyName: AccessHandlerECSPolicy
PolicyDocument:
Statement:
- Action:
- ecs:ListTasks
- ecs:ListTaskDefinitionFamilies
- ecs:DescribeTasks
- ecs:DescribeClusters
- cloudtrail:LookupEvents
Effect: Allow
Resource: "*"
Sid: ReadECS
Version: "2012-10-17"
Outputs:
RoleARN:
Value:
Fn::GetAtt:
- CommonFateAccessHandlerECSRole
- Arn
Using the AWS CLI
If you have the AWS CLI installed and can deploy cloudformation you can run the following commands to deploy this stack. Ensure you have credentials for the same account that Common Fate is deployed to and that AWS_REGION environment variable is set correctly, we recommend deploying this role to the same region as your Common Fate stack.
aws cloudformation deploy --template-file common-fate-access-handler-ecs-exec-ecs-role.yml --stack-name Common-Fate-Access-Handler-ECS-Exec-ECS-Role --capabilities CAPABILITY_IAM
Once the stack is deployed, you can retrieve the role ARN by running the following command.
aws cloudformation describe-stacks --stack-name Common-Fate-Access-Handler-ECS-Exec-ECS-Role --query "Stacks[0].Outputs[0].OutputValue"
Using the AWS Console
Open the AWS Console to Cloudformation in the same account that your ECS cluster is running in and click Create stack then select with new resources (standard) from the menu.
Upload the template file
Name the stack 'Common-Fate-Access-Handler-ECS-Exec-ECS-Role'
Click Next
Click Next
Acknowledge the IAM role creation check box and click Create Stack
Copy the RoleARN output from the stack and paste it in the ssoRoleArn config value on the right.
Finalizing Your Deployment
Configuration Fields
This step will guide you through collecting the values for these fields required to setup your provider.
Field | Description |
---|
Setting up Python shell access
If you aren't using interactive Python shells on your ECS tasks, skip this step.
The following instructions detail how to install the granted-flask library for audited Python shell access.
Installing the Python library
Add granted-flask
to your Docker container's Python dependencies. This will depend on what dependency management approach you use. We've given an example below for requirements.txt
:
pip install granted-flask
pip freeze > requirements.txt
Set the GRANTED_WEBHOOK_URL environment variable
A GRANTED_WEBHOOK_URL
environment variable must be provided to the ECS task pointing to your Common Fate deployment URL.
To find your webhook URL open a terminal at the directory containing your deployment.yml
file. Then run:
gconfig output WebhookUrl
Update the task definition of the ECS container with the following environment variable:
GRANTED_WEBHOOK_URL=<Webhook URL from the gconfig output>