Sym helps developers solve painful access management problems with standard infrastructure tools.
Is your team experiencing:
Sym can help! This quickstart will help you launch a new access flow in under an hour. Your engineers will be able to safely and conveniently gain access to sensitive resources, all with the guardrails you need in place.
If you want to check out a demo, go here!
We're going to walk through setting up an Otka-based Sym Flow that is provisioned and managed with GitHub Actions. By the end of this tutorial, you'll have the ability to provision, test and validate Sym Flows in a sandbox environment and then push the Flows to prod, all from GitHub Actions.
The complete code for this tutorial can be found at @symopsio/sym-github-actions-quickstart
.
Check out this walkthrough companion to the quickstart if you'd like to see the workflow in action!
Users will interact with this Sym Flow
via Slack. Slack connects to the Sym platform, which executes a Flow
that use the Integrations
we are wiring together in this tutorial.
This is what a request will look like.
Sym will send a request for approval to the appropriate users or channel based on your impl.py
.
Finally, upon approval, Sym gives you access to the Okta group and updates Slack.
Implementers push their changes to a sandbox
branch, which updates the sandbox
Sym Environment via GitHub Actions.
When Implementers open a Pull Request to the main
branch, we've provided a GitHub Action that includes a terraform plan
of the changes as a comment. When you merge, the GitHub Action does a terraform apply
that updates the prod
Sym Environment.
This setup guide walks you through everything you need to get a Sym Okta workflow configured with GitHub Actions!
Key components:
You can mix and match from these components if you want to manage Terraform state differently, don't want to use GitHub actions, or don't want to use the OIDC role.
The environments directory includes sandbox, prod, and bootstrap Terraform configurations to get you up and running. Just configure a few variables in terraform.tfvars
and you're on your way!
Here's what you'll need to do:
symflow
CLITargets
You'll need to work with the Sym team to get your organization set up with access to the Sym platform. Once you're onboarded, continue from here.
symflow
CLIThe symflow
CLI is what you use to interact with Sym's control plane.
$ brew install symopsio/tap/symflow
==> Tapping symopsio/tap
Cloning into '/opt/homebrew/Library/Taps/symopsio/homebrew-tap'...
remote: Enumerating objects: 1148, done.
remote: Counting objects: 100% (285/285), done.
remote: Compressing objects: 100% (222/222), done.
remote: Total 1148 (delta 134), reused 156 (delta 59), pack-reused 863
Receiving objects: 100% (1148/1148), 324.27 KiB | 6.36 MiB/s, done.
Resolving deltas: 100% (530/530), done.
Tapped 14 formulae (43 files, 582.7KB).
==> Downloading https://github.com/symopsio/sym-flow-cli-releases/releases/download/v1.3.7/sym-flow-cli-darwin-x64.tar.gz
######################################################################## 100.0%
==> Installing symflow from symopsio/tap
🍺 /opt/homebrew/Cellar/symflow/1.3.7: 10,351 files, 198MB, built in 33 second
We'll have to login before we can do anything else. Sym also supports SSO, if your organization has set it up.
$ symflow login
Sym Org: healthy-health
Username: sym-implementer@healthy-health.co
Password: ************
MFA Token: ******
Success! Welcome, Sym Implementer. 🤓
You'll need to use the slug
given to you by the Sym team, and set it in terraform.tfvars
in your prod
and sandbox
environments.
# environments/prod/terraform.tfvars
# environments/sandbox/terraform.tfvars
sym_org_slug = "healthy-health"
Now that you've got symflow
installed, you need to install Sym's Slack app into your workspace. Sym supports running multiple environments in a single Slack workspace, OR you can choose to install your sandbox flows into a test workspace.
The easiest place to find this is in the URL you see when you run Slack in your web browser. It will start with a T
, and look something like TABC123
.
This also goes in terraform.tfvars
.
# environments/prod/terraform.tfvars
# environments/sandbox/terraform.tfvars
slack_workspace_id = "TABC123"
symflow
has a convenient way to provision an instance of Sym's Slack app. This command will generate an install link that you can either use directly, or forward on to your Workspace Administrator.
$ symflow services create --service-type slack --external-id T123ABC
Successfully set up service type slack with external ID TABC123!
Generated an installation link for the Sym Slack app:
https://static.symops.com/slack/install?token=xxx
Please send this URL to an administrator who has permission to install the app. Or, if that's you, we can open it now.
Would you like to open the Slack installation URL in a browser window? [Y/n]:
Once Slack is set up, try launching the Sym app with /sym
in Slack.
You should see a welcome modal like this one, since we haven't set up a Flow
yet:
In order to run GitHub actions to deploy your flows, make a copy of the sym-github-actions-quickstart
repo in your org. Once you have the repo copied, use symflow
to configure a bot token that lets Sym authenticate from your GitHub action:
$ symflow bots create github
$ symflow tokens issue --username github --label "GitHub Actions" --expiry 365d
<token output here>
Configure a repository secret with the token value. Set the SYM_JWT
key to the bot token value.
In order to deploy and run Sym, you'll need to provide AWS credentials to create Sym's dependencies in your infrastructure.
We provide you an AWS IAM Policy that includes all the permissions required to set up this repo. To wire this up with GitHub OIDC, update the AWS_ROLE_ARN
value in the GitHub actions configs.
If you don't want to use GitHub OIDC, you can remove the AWS_ROLE_ARN
and use standard AWS Access Keys.
If you have an existing Terraform pipeline you can include the environments/bootstrap configurations to create the required GitHub OIDC provider and IAM policy.
$ cd environments/bootstrap
$ terraform apply
We have a gist with all the requirements you need to provision Sym's policies using your own tooling.
We'll create the policy that lets you provision Sym dependencies first, and then attach this to a role, group, or user as needed.
access-policy.json
.access-policy.json
, replacing AWS_ACCOUNT_ID with the AWS Account ID you'll be provisioning into.$ aws iam create-policy --policy-name SymGitHubActionAccess \
file://access-policy.json
GitHub Actions lets you configure an AWS IAM Role that Actions can assume, so you don't have to configure and/or rotate AWS Access Keys in your GitHub account.
In order to set this up, you need to create an AWS IAM Identity Provider and an AWS IAM Role that can assume this Identity Provider.
create-open-id-connect-provider.json
and then run the following to create a GitHub OIDC Identity Provider in your account: $ aws iam create-open-id-connect-provider --cli-input-json file://create-open-id-connect-provider.json
assume-role-policy-document.json
and edit the following three values: assume-role-policy-document.json
: $ aws iam create-role --role-name SymGitHubActionAccess \
--asume-role-policy-document file://assume-role-policy-document.json
$ aws iam attach-role-policy --role-name SymGitHubActionAccess \
--policy-arn arn:aws:iam::AWS_ACCOUNT_ID:policy/SymGitHubActionAccess
AWS_ROLE_ARN
value in your GitHub Actions configs to use the ARN of the role you just created.If setting up the GitHub AWS OIDC connection is not for you, then you can simply create an AWS IAM user that can bootstrap Sym workflows, or attach the required permissions to an existing users.
If you're taking this path, you should update your GitHub Actions configs to not use AWS_ROLE_ARN
and instead rely on an AWS Access Key and Secret.
This repo includes a bootstrap workflow that you can use to set up Terraform state management directly from GitHub actions.
To run the bootstrap workflow, make sure you've edited the AWS_ROLE_ARN
value in main.yml
and terraform-bootstrap.yml
to the right value, or that you've removed it entirely if you plan to use an AWS Access Key and Secret.
You should be able to make a request now with /sym req
, though you'll get an error when you try to approve access, since we haven't configured Okta yet.
Check in your errors_channel
and you should see something like this:
Now that the prod workflow is set up, lets finishing configuring flows so that we have a sandbox flow where we can test stuff out!
sandbox
branch and push it to remote $ git checkout -b sandbox
$ git push -u sandbox
This Flow
is set up to route access requests to the #sym-requests
channel. You can change this channel in—wait for it—terraform.tfvars
.
Sym will also send any errors that happen during a Run
(due to external failures or config issues) to a configurable error channel. You'll never guess where you can configure this.
# environments/prod/terraform.tfvars
# environments/sandbox/terraform.tfvars
flow_vars = {
request_channel = "#sym-requests"
}
You can also change the channel that errors are routed to, which defaults to #sym-errors
.
# environments/prod/terraform.tfvars
# environments/sandbox/terraform.tfvars
error_channel = "#sym-errors"
Sym stores your Okta API token in an AWS Secrets Manager value. By default, the sym-runtime
module sets up a shared AWS Secrets Manager secret that you add key/value pairs to for the secrets that your Runtime
needs to access.
Follow our Okta setup instructions to create an Okta API token that has access to manage your target groups.
Configure the API key in the AWS Secrets Manager secret configured by your sym-runtime
module like so.
$ OKTA_API_TOKEN=xxx
$ aws secretsmanager put-secret-value \
--secret-id /symops.com/prod \
--secret-string "{\"okta_api_token\": \"$OKTA_API_TOKEN\"}"
$ aws secretsmanager put-secret-value \
--secret-id /symops.com/sandbox \
--secret-string "{\"okta_api_token\": \"$OKTA_API_TOKEN\"}"
Identify the initial Okta groups that Sym will move users in and out of. You can always change and modify these groups later, so we recommend starting with an existing group or creating a temporary group for testing.
Get the IDs of the Okta groups that you'll be starting with. Configure these in okta_targets
in terraform.tfvars
.
# environments/prod/terraform.tfvars
# environments/sandbox/terraform.tfvars
okta_targets = [
{
label = "AWS Ops Admin",
group_id = "CHANGEME"
}
]
Set your Okta domain as well.
# environments/prod/terraform.tfvars
# environments/sandbox/terraform.tfvars
okta_org_domain = "xxx.okta.com"
We've included a placeholder Cypress test that will run when you open a PR against the main
branch.
tfvar
configurations in step 7 and push the changes to the sandbox branch.main
. You should see a plan
of your changes against the prod
environment, as well as a cypress
run that you can use to test the sandbox version of the flow!Here are some next steps to consider:
LogDestinations
.Flow
to require that users be members of a certain Okta group to approve access: flow_vars.approver_group
with the Okta group ID in terraform.tfvars
.hook
annotation on the on_approve
method in impl.py
. This is just one example of what you can do with hooks in the SDK!symflow
CLI to configure user mappings when required.Flow
logic. Maybe change things to allow self-approval only for on-call users?Flow
!