Skip to content

Latest commit

 

History

History
226 lines (148 loc) · 7.66 KB

SETUP.md

File metadata and controls

226 lines (148 loc) · 7.66 KB

Install (AWS)

Install the infrastructure and code to run the uDeploy portal in AWS.

1. Clone Infrastructure

$ mkdir udeploy && cd udeploy
$ git clone --branch v0.33.1-rc git@github.com:turnerlabs/udeploy.git infrastructure

2. Create Base Infrastucture

Optionally, customize infrastructure.

Replace {{TOKENS}} in infrastructure/base/terraform.tfvars.

$ terraform init -var-file=infrastructure/base/terraform.tfvars  infrastructure/base 
$ terraform apply -var-file=infrastructure/base/terraform.tfvars  infrastructure/base

3. Initilize Configuration

$ cp infrastructure/env.template infrastructure/portals/prod/.env

4. Create Database

Create an empty MongoDB database preferably called udeploy-prod on an Atlas M2 (General) cluster or equivalent. Want to Terraform Atlas MongoDB? If not, delete atlas.tf.

Replace {{TOKENS}} in ./infrastructure/portals/prod/.env file.

DB_URI={{DB_CONNECTION_STRING}}
DB_NAME={{DB_NAME}}

Add an initial admin user to the users collection. Additional users can be added through the portal.

use {{DB_NAME}}
db.users.insert({"admin":true,"email":"User.Email@domain.com","apps":{}})

IMPORTANT: The email address is case sensitive.

5. Configure Event Notifications

Replace {{TOKENS}} in ./infrastructure/portals/prod/.env file.

SQS_CHANGE_QUEUE=udeploy-prod-notification-queue.fifo
SQS_ALARM_QUEUE=udeploy-prod-alarm-queue
SQS_S3_QUEUE=udeploy-prod-s3-queue
SNS_ALARM_TOPIC_ARN=arn:aws:sns:us-east-1:{{ACCOUNT_ID}}:{{APP}}-prod-alarms

6. Create Portal Infrastucture

Replace {{TOKENS}} in infrastructure/portals/prod/terraform.tfvars.

$ terraform init -var-file=infrastructure/portals/prod/terraform.tfvars infrastructure/portals/prod
$ terraform apply -var-file=infrastructure/portals/prod/terraform.tfvars infrastructure/portals/prod

7. Configure User Authentication

The portal uses OIDC with OAuth2 for authenticating users before loading user authorization from the database. Choose an authentication option.

Portal (OIDC) -> AzureAD

  1. Register the portal with Azure.

  2. Replace the following configuration in ./infrastructure/portals/prod/.env.

Update the {{TOKENS}} using the values specified in the Azure app registration.

OAUTH_CLIENT_ID={{CLIENT_ID}} 
OAUTH_CLIENT_SECRET={{CLIENT_SECRET}}
OAUTH_AUTH_URL=https://login.microsoftonline.com/{{TENANT_ID}}/oauth2/v2.0/authorize
OAUTH_TOKEN_URL=https://login.microsoftonline.com/{{TENANT_ID}}/oauth2/v2.0/token
OAUTH_REDIRECT_URL=https://{{PORTAL_DOMAIN}}/oauth2/response
OAUTH_SIGN_OUT_URL=https://login.microsoftonline.com/{{TENANT_ID}}/oauth2/logout?client_id={{CLIENT_ID}}
OAUTH_SCOPES=openid,offline_access,email
Portal (OIDC) -> Okta
  1. Register the portal with Okta using a login_redirect_url and logout_redirect_url values.

Example:

LOGIN_REDIRECT_URL=https://{{PORTAL_DOMAIN}}/oauth2/response
LOGOUT_REDIRECT_URL=https://{{PORTAL_DOMAIN}}

Okta app registration process depends on each individual implementation.

  1. Replace the OAUTH configuration in ./infrastructure/portals/prod/.env.

Update the {{TOKENS}} with the values from the registration.

OAUTH_REDIRECT_URL=https://{{PORTAL_DOMAIN}}/oauth2/response

OAUTH_CLIENT_ID={{OKTA_CLIENT_ID}} 
OAUTH_CLIENT_SECRET={{OKTA_CLIENT_SECRET}}

OAUTH_TOKEN_URL={{OKTA_TOKEN_URL}}
OAUTH_AUTH_URL={{OKTA_SIGNIN_URL}}
OAUTH_SIGN_OUT_URL={{OKTA_SIGNOUT_URL}}?client_id={{OKTA_CLIENT_ID}}

OAUTH_SCOPES=openid,email
Portal (OIDC) -> AWS Cognito (SAML) -> Okta

  1. Copy cognito.tf and cognito.auto.tfvars into ./infrastructure/portals/prod.

  2. Update signin_url_prefix in ./infrastructure/portals/prod/cognito.auto.tfvars only.

Must be a unique prefix across the AWS region. This will be used to prefix the application sign in url.

signin_url_prefix = "{{AWS_COGNITO_SIGNIN_URL_PREFIX}}"
  1. Create initial AWS Cognito infrastructure.
$ terraform apply -var-file=infrastructure/portals/prod/cognito.auto.tfvars infrastructure/portals/prod -target=aws_cognito_user_pool.pool
$ terraform apply -var-file=infrastructure/portals/prod/cognito.auto.tfvars infrastructure/portals/prod -target=aws_cognito_user_pool_domain.domain
  1. Register the portal with Okta using the aws_cognito_return_url and aws_cognito_audience_restriction values generated by the $ terraform output command.

Okta app registration process depends on each individual implementation.

  1. Update ./infrastructure/portals/prod/cognito.auto.tfvars with the configuration from the Okta registration and the portal domain.
metadata_url              = "{{OKTA_METADATA_URL}}"
sso_redirect_binding_uri  = "{{OKTA_SSO_REDIRECT_BINDING_URI}}"

callback_url         = "https://{{PORTAL_DOMAIN}}/oauth2/response"
logout_url           = "https://{{OKTA_DOMAIN}}/logout.aspx?AppID={{OKTA_APP_ID}}"
  1. Create the final AWS Cognito infrastructure.
$ terraform apply -var-file=infrastructure/portals/prod/cognito.auto.tfvars infrastructure/portals/prod
  1. Replace the OAUTH configuration in ./infrastructure/portals/prod/.env.

Update the {{TOKENS}} with the values generated by the $ terraform output command.

OAUTH_REDIRECT_URL=https://{{PORTAL_DOMAIN}}/oauth2/response

OAUTH_CLIENT_ID={{AWS_COGNITO_CLIENT_ID}} 
OAUTH_CLIENT_SECRET={{AWS_COGNITO_CLIENT_SECRET}}

OAUTH_TOKEN_URL={{AWS_COGNITO_TOKEN_URL}}
OAUTH_AUTH_URL={{AWS_COGNITO_SIGNIN_URL}}
OAUTH_SIGN_OUT_URL={{AWS_COGNITO_SIGNOUT_URL}}

OAUTH_SCOPES=openid,email

NOTE: The OAUTH_SESSION_SIGN should be updated to a secure string.

8. Push Configuration to Parameter Store

Install cstore and run the following commands from the repository root to store configuration in SSM Parameter Store.

$ export AWS_REGION=us-east-1
$ export AWS_PROFILE=aws-account-profile
$ cstore push infrastructure/portals/prod/.env -s aws-parameter -t prod

When prompted, set context to udeploy and the KMS Key ID to the kms_key_id from the Terraform output.

9. Link Other AWS Accounts (optional)

To deploy resources accross multiple AWS accounts, provide permissions to each additional AWS account the portal should control.

Duplicate the folder infrastructure/accounts/dev for each account infrastructure/accounts/{{ACCOUNT_IDENTIFIER}} and following the intructions.

Replace {{TOKENS}} in infrastructure/accounts/{{ACCOUNT_IDENTIFIER}}/terraform.tfvars.

$ terraform init -var-file=infrastructure/accounts/{{ACCOUNT_IDENTIFIER}}/terraform.tfvars  infrastructure/accounts/{{ACCOUNT_IDENTIFIER}} 
$ terraform apply -var-file=infrastructure/accounts/{{ACCOUNT_IDENTIFIER}}/terraform.tfvars  infrastructure/accounts/{{ACCOUNT_IDENTIFIER}}

Update linked_account_ids in infrastructure/base/terraform.tfvars with account ids of all linked accounts.

$ terraform apply -var-file=infrastructure/base/terraform.tfvars  infrastructure/base

Update linked_account_ids in infrastructure/portals/prod/terraform.tfvars with account ids of all linked accounts.

$ terraform apply -var-file=infrastructure/portals/prod/terraform.tfvars  infrastructure/portals/prod