AWS ECS Installation Guide - Authlete Documentation

The purpose of this document is to provide a clear and concise guidance to customers using AWS ECS, who would like to deploy the self-hosted version of Authlete through the Ansible solution.

Prerequisites

AWS

ECS Cluster (Fargate)
ECR
Load Balancer
- Target Group
RDS (Engine: MySQL Community)
Cloud Map
EFS
CloudWatch Logs groups

Ansible Execution Environment

Python (3.12 or later)
Python modules: boto3, botocore, requests
Ansible (11.5.0 or later)
AWS CLI
Docker
Crane (https://github.com/google/go-containerregistry/tree/main/cmd/crane)

Installation Steps

Setup Phase: Authlete

1. Create an Organization

Log in to the Authlete Console.
Create an organization for your company.
Note down the Organization ID.

2. Request Access

Share the Organization ID and Organization Name with Authlete Support.
Authlete will authorize registry access for your organization.

3. Generate Organization Token

In the Authlete Console, generate a Token for your organization.
Keep the Organization ID and Token handy for authentication.

Setup Phase: Ansible Execution Environment

Setup Ansible execution environment.

1. Install Python Requirements:

Install boto3 and botocore for AWS interactions. Use the following command:

  pip3 install boto3 botocore

You will also need the Python requests module which you can install with the following command:

  pip3 install requests

2. Install Ansible

To install ansible, run the following: Ansible version (>=11.5.0) is recommended.

pip3 install "ansible>=11.5.0"

3. Install Ansible Collections

Option 1: Install the latest Ansible collection: community.aws and amazon.aws dependency:

ansible-galaxy collection install --force community.aws:==9.2.0
ansible-galaxy collection install --force amazon.aws:==9.4.0

Option 2: Create and add the community.aws collection and amazon.aws dependency to a requirements.yml file:

  collections:
    - name: community.aws
      version: 9.2.0
    - name: amazon.aws
      version: 9.4.0

Then, install the requirements:

ansible-galaxy collection install -r requirements.yml

4. Setup AWS CLI Environment

Before anything, you will need to set up your AWS account. Contact your AWS administrator and have them create credentials for you. Install AWS CLI Use the following guide to install or update to the latest version of AWS CLI. Skip this step if your AWS CLI environment is already up to date. AWS Configuration If you do not have a pre-existing folder, create ~/.aws. Once done, create a ~/.aws/credentials file containing the following information :

[default]
aws_access_key_id = <ACCESS_KEY>
aws_secret_access_key = <SECRET_ACCESS_KEY>

You can find these keys in your AWS IAM account settings. Then, create another ~/.aws/config file containing the following information :

[default]
region = <REGION>
output = json

This corresponds to the region under which you have created your ECS cluster.

Preparation and Configuration Phase

1. Pull the ansible-playbook

First, log into the artifact registry using your organization identifiers :

docker login artifacts.authlete.com -u <org_id> -p <org_token>

Then, pull the Ansible playbook from the artifact registry :

crane pull artifacts.authlete.com/authlete-platform-playbook:1.0.0 ansible-playbook-image.tar.gz

Finally, extract the files on your system :

mkdir extract-image
tar xzf ansible-playbook-image.tar.gz -C extract-image
ls extract-image
  73d73aa9481500d08886e6510eed900ff301dfcaccc55f5c80ac488b78caa470.tar.gz
  manifest.json
  sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a

mkdir ansible-playbook
tar xzf extract-image/73d73aa9481500d08886e6510eed900ff301dfcaccc55f5c80ac488b78caa470.tar.gz -C ansible-playbook
# This tarball file will have a random name

ls ansible-playbook
  ansible.cfg
  deployment-guide.md
  files
  galaxy.yml
  group_vars
  inventories
  playbooks
  README.md
  roles

rm -r ansible-playbook-image.tar.gz extract-image

Create configuration files from sample files for further editing.

cd ansible-playbook
cp -a group_vars/all.yml.sample group_vars/all.yml
cp -a group_vars/aws_ecs.yml.sample group_vars/aws_ecs.yml

You can check the group_vars/aws_ecs.yml file provided by Ansible for configuration details. This file contains all the required keys with dummy placeholder values that need to be replaced with your AWS resource identifiers.

ecs_cluster_name
execution_role_arn
efs_filesystem_id
efs_access_point_id
efs_access_point_arn
aws_logs_groups
cloudmap_registry_arns

The following steps will show you how to configure the values in group_vars/aws_ecs.yml file.

2. Create AWS ECS

Once your AWS account is set up, create a Fargate ECS cluster with a name of your choosing. Use the following aws cli command to display your ECS cluster information:

aws ecs describe-clusters --clusters <CLUSTER_NAME>

In the group_vars/aws_ecs.yml file, you can now replace the following AWS resource identifiers with your AWS ECS values:

# AWS account identifier
aws_account_id: "123455673100"

# Region in which ECS resources will be provisioned
region: us-east-2

# ECS cluster name where services will be deployed
ecs_cluster_name: <CLUSTER_NAME>

3. Create AWS ECR Repositories

Create ECR repositories. Navigate to the ECR dashboard and create the following repositories:

<CLUSTER_NAME>/server-db-schema
<CLUSTER_NAME>/server
<CLUSTER_NAME>/idp-db-schema
<CLUSTER_NAME>/idp
<CLUSTER_NAME>/authlete-bootstrapper
<CLUSTER_NAME>/console
<CLUSTER_NAME>/nginx
<CLUSTER_NAME>/alpine
<CLUSTER_NAME>/valkey (Optional, you can disable the valkey option in the all.yml file)

NOTE: Keep in mind that the namespace in the repository name must be the same as your <CLUSTER_NAME>. To correctly setup the ecr_repo_url, copy/paste the URI of one of your ECR repositories, and remove the repository name at the end (the final result should end with amazonaws.com) Use the following command to list your repositories.

aws ecr describe-repositories | grep repositoryArn

In the group_vars/aws_ecs.yml file, replace the value of repo. Make sure not to configure the container images and tags.

#### #### #### #### ####
# ECR Container Images
# Dont change the Container images or tags, unless specified by support@authlete.com or
# unless mentioned in our deployment guide
repo: 123456789.dkr.ecr.us-east-2.amazonaws.com

4. Create AWS ECS Task

From your AWS ECS cluster, go to Tasks and follow instructions to create your task role and execution. When your task is launched, find and replace the following AWS resource identifiers with your AWS ECS values.

The execution_role_arn and task_role_arn values can be found under the task definitions.
The subnet_id values can be found under the tasks.

In the group_vars/aws_ecs.yml file, configure the following:

# IAM role for ECS tasks to pull images and write logs
execution_role_arn: arn:aws:iam::123455673100:role/ecsTaskExecutionRole

# IAM role for ECS tasks to access AWS services at runtime
task_role_arn: arn:aws:iam::123455673100:role/ecsTaskRole

# Security group ID attached to the ECS service for network rules
security_group_id: sg-0f8bef00

# Subnet ID (within a VPC) where ECS tasks will be launched
subnet_id: subnet-4af11000

5. Create AWS Target Groups

In the AWS EC2 dashboard, under Load Balancing, create the following target groups:

authlete-console-tg
authlete-idp-tg
authlete-api-tg
authlete-proxy-tg, Health check path=/health
authlete-valkey-tg

Make sure these target groups should be of type IP address and use the corresponding container port number. Finally, in the group_vars/aws_ecs.yml file, replace the following target group ARNs with your AWS EC2 resource identifiers.

# Application Load Balancer (ALB) target groups per microservice
api_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-api-tg/00be0deb21695fcde5
idp_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-idp-tg/abcd1234ijkl5678
console_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-console-tg/abcd1234mnop5678
proxy_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-proxy-tg/abcd1234qrst5678
valkey_target_group_arn: arn:aws:elasticloadbalancing:us-west-1:123456789012:targetgroup/my-valkey-tg/abcd1234qrst5876

6. Create AWS ALB

Create the following load balancers:

authlete-lb
idp-lb
console-lb
proxy-lb

Set the following fields for each of the load balancers:

Availability zones
Security group
Listener port and forwarding
Certificate (required for HTTPS protocol only)

7. Create AWS Cloud Map

Navigate to AWS Cloud Map and create a new namespace. This namespace must have the same name as your previously created ECS cluster.

Navigate to the newly created CloudMap namespace and create the following services:

console
idp
authlete-api

Replace the following AWS resource identifiers with your AWS Cloud Map values. To list any AWS services, use the following:

aws servicediscovery list-services

In the group_vars/aws_ecs.yml file, configure the following:

# Service discovery (Cloud Map) registry ARNs for internal DNS-based discovery
api_cloudmap_registry_arn: arn:aws:servicediscovery:us-west-1:123456789012:service/srv-xxxxxxxxxxxxxxxx
idp_cloudmap_registry_arn: arn:aws:servicediscovery:us-west-1:123456789012:service/srv-yyyyyyyyyyyyyyyy
console_cloudmap_registry_arn: arn:aws:servicediscovery:us-west-1:123456789012:service/srv-zzzzzzzzzzzzzzzz

To correctly set this up, copy/paste your CloudMap namespace ARN, then replace namespace/... with service/{SERVICE_ID} for each registry

8. Create AWS CloudWatch Log Group

In the AWS CloudWatch dashboard, under Logs, create a new log group with a name of your choosing. In the group_vars/aws_ecs.yml file:

# CloudWatch Logs group name for ECS container logs
aws_logs_groups: /ecs/authlete

9. Create AWS RDS Database

Create an AWS RDS Database with the following configurations:

Engine type: MySQL
Engine version: 8.0.X

Before starting the installation, ensure that both of the following databases are created.

create database authlete;
create database idp;

After creating RDS Database, configure the following values:

api_db_user: <USER_NAME>
api_db_password: <PASSWORD>
api_db_root_password: <PASSWORD>
api_db_host: <DB_IDENTIFIER>.*****.ap-northeast-1.rds.amazonaws.com
api_db_port: 3306
api_db_type_name: mysql
api_db_type: mariadb
api_db_name: authlete    #The name of database you created


idp_db_user: <USER_NAME>
idp_db_password: <PASSWORD>
idp_db_root_password: <PASSWORD>
idp_db_host: <DB_IDENTIFIER>.*****.ap-northeast-1.rds.amazonaws.com
idp_db_port: 3306
idp_db_type_name: mysql
idp_db_type: mariadb
idp_db_name: idp    #The name of database you created

10. Create AWS EFS

Create an Amazon EFS and replace the following AWS resource identifiers with your Amazon EFS Filesystem values.

In the group_vars/aws_ecs.yml file, configure the following EFS values:

# Amazon EFS (Elastic File System) configuration for persistent shared storage
efs_filesystem_id: fs-02e6123720a9550b5
efs_access_point_id: fsap-02e6123720a9550b5
efs_access_point_arn: arn:aws:elasticfilesystem:us-west-1:123456789012:file-system/fs-02e6123720a9550b5
efs_filesystem_id_valkey: fs-0ba6a21018f65eaas
efs_access_point_id_valkey: fsap-007fd448ce3basass
efs_access_point_arn_valkey: arn:aws:elasticfilesystem:us-west-1:123456789012:file-system/fs-0ba6a21018f65eaas
#### #### #### #### ####

11. Container Images

The Ansible playbook automates the transfer of Authlete-provided container images to a customer’s own container registry. This avoids direct runtime dependency on Authlete’s registry, and ensures reproducible deployments.

Make sure not to modify the following container images and tags in the group_vars/aws_ecs.yml file.

Image	Description	Supported Version Tags
server	Core API server that handles OAuth 2.0 and OpenID Connect operations	3.0.11
server-db-schema	Database schema initialization tool for the API server	v3.0.11
idp	Identity Provider server for user authentication and management	1.0.5
idp-db-schema	Database schema initialization tool for the IDP server	v1.0.5
console	React based management console for platform configuration and monitoring	v1.0.5
nginx	Nginx-based reverse proxy for handling TLS termination and routing	1.26.3
valkey	Caching service for improved performance and reduced database load	8.0.1
alpine	A minimal Docker image based on Alpine Linux, designed for security, simplicity, and resource efficiency. Commonly used as a base image for lightweight containers.	3.18
authlete-bootstrapper	Initialization service for the platform. Only used during first deployment.	1.0.0

images:
  api:
    name: server
    tag: "3.0.11"
  server_db_schema:
    name: server-db-schema
    tag: "v3.0.11"
  idp:
    name: idp
    tag: "1.0.5"
  idp_db_schema:
    name: idp-db-schema
    tag: "v1.0.5"
  console:
    name: console
    tag: "1.0.5"
  bootstrapper:
    name: authlete-bootstrapper
    tag: "1.0.0"
  proxy:
    name: nginx
    tag: "1.26.3"
  valkey:
    name: valkey
    tag: "8.0.1"
  proxy_sidecar:
    name: alpine
    tag: "3.18"
#### #### #### #### ####

12. Authlete URLs

Configure Authlete URLs: Make sure you follow the required format to avoid errors: In the group_vars/aws_ecs.yml file, configure the following:

authlete_api_url
authlete_idp_base_url
authlete_idp_console_url

#### #### #### #### ####
#### URLs to be used (without http:// or https://)
authlete_api_url: "<api_url>"               # eg: authlete-api.example.com
authlete_idp_base_url: "<idp_url>"          # eg: authlete-idp.example.com
authlete_idp_console_url: "<console_url>"   # eg: authlete-console.example.com
url_scheme: "https"                         # either http or https
#### #### #### #### ####

13. Authlete Email and Password

Configure your admin_user_email and admin_user_password

Your first Authlete user will be instantiated with these values.

In the group_vars/aws_ecs.yml file, configure the following:

# It create's necessary configuartions for Authlete to start

admin_user_email: "<admin_email>"      # eg: admin@example.com, Admin email used by the bootstrapper to create or log into the Authlete system
admin_user_password: <admin_password>  # Corresponding password for the admin user (used during initial setup only)
boot_task_def: bootstrapper-task       # ECS task definition name for the bootstrapper container/task

14. Configure Authlete Organization ID and Token

Log into the Authlete console and find the Authlete Organization Id and Organization Token for the following step. Configure your Authlete Organization Id and Organization Token in the group_vars/all.yml file:

authlete_org_id: "<org_id>"
authlete_org_token: "<org_token>"

Validation Phase

Now that you have created and configured all the required AWS resources, you will need to update values in the Ansible group_vars so that your installation correctly points towards them. Run the environment validation playbook to verify that all required AWS infrastructure is in place. However, you may choose to skip this step as it will be automatically executed during the installation process. Run the following ansible playbook command:

ansible-playbook playbooks/site.yml --tags prereq --skip-tags=install,uninstall,upgrade,rollingupgrade

If the output displays failed=0, it means this step is completed.

Deployment Phase

1. Install the Authlete Stack

To install the Full Authlete Stack, run the following ansible commands:

ansible-playbook playbooks/site.yml --tags aws,install --skip-tags upgrade,uninstall,rollingupgrade
ansible-playbook playbooks/site.yml --tags aws,upgrade --skip-tags install,uninstall,rollingupgrade

Each of these commands will take approximately from 10 to 20 minutes to complete.

Uninstall Phase

1. Uninstall the Stack

To uninstall the full Authlete Stack:

ansible-playbook playbooks/site.yml --tags aws,uninstall --skip-tags install,upgrade,rollingupgrade

Manage Individual Components

1. Authlete API

To install:

ansible-playbook playbooks/site.yml --tags api,install_api --skip-tags uninstall,upgrade,rollingupgrade

To uninstall:

ansible-playbook playbooks/site.yml --tags api,uninstall_api --skip-tags install,upgrade,rollingupgrade

Rolling upgrade:

ansible-playbook playbooks/site.yml --tags api,rollingupgrade --skip-tags install,upgrade,uninstall

2. Authlete IDP

To install:

ansible-playbook playbooks/site.yml --tags idp,install_idp --skip-tags uninstall,rollingupgrade

To uninstall:

ansible-playbook playbooks/site.yml --tags idp,uninstall_idp --skip-tags upgrade,rollingupgrade

Rollling upgrade:

ansible-playbook playbooks/site.yml --tags idp,rollingupgrade --skip-tags upgrade,uninstall

3. Authlete Console

To install:

ansible-playbook playbooks/site.yml --tags console,install_console --skip-tags uninstall,rollingupgrade

To uninstall:

ansible-playbook playbooks/site.yml --tags console,uninstall_console --skip-tags upgrade,rollingupgrade

Rolling upgrade:

ansible-playbook playbooks/site.yml --tags console,rollingupgrade --skip-tags upgrade,uninstall

​Prerequisites

​AWS

​Ansible Execution Environment

​Installation Steps

​Setup Phase: Authlete

​1. Create an Organization

​2. Request Access

​3. Generate Organization Token

​Setup Phase: Ansible Execution Environment

​1. Install Python Requirements:

​2. Install Ansible

​3. Install Ansible Collections

​4. Setup AWS CLI Environment

​Preparation and Configuration Phase

​1. Pull the ansible-playbook

​2. Create AWS ECS

​3. Create AWS ECR Repositories

​4. Create AWS ECS Task

​5. Create AWS Target Groups

​6. Create AWS ALB

​7. Create AWS Cloud Map

​8. Create AWS CloudWatch Log Group

​9. Create AWS RDS Database

​10. Create AWS EFS

​11. Container Images

​12. Authlete URLs

​13. Authlete Email and Password

​14. Configure Authlete Organization ID and Token

​Validation Phase

​Deployment Phase

​1. Install the Authlete Stack

​Uninstall Phase

​1. Uninstall the Stack

​Manage Individual Components

​1. Authlete API

​2. Authlete IDP

​3. Authlete Console

Prerequisites

AWS

Ansible Execution Environment

Installation Steps

Setup Phase: Authlete

1. Create an Organization

2. Request Access

3. Generate Organization Token

Setup Phase: Ansible Execution Environment

1. Install Python Requirements:

2. Install Ansible

3. Install Ansible Collections

4. Setup AWS CLI Environment

Preparation and Configuration Phase

1. Pull the ansible-playbook

2. Create AWS ECS

3. Create AWS ECR Repositories

4. Create AWS ECS Task

5. Create AWS Target Groups

6. Create AWS ALB

7. Create AWS Cloud Map

8. Create AWS CloudWatch Log Group

9. Create AWS RDS Database

10. Create AWS EFS

11. Container Images

12. Authlete URLs

13. Authlete Email and Password

14. Configure Authlete Organization ID and Token

Validation Phase

Deployment Phase

1. Install the Authlete Stack

Uninstall Phase

1. Uninstall the Stack

Manage Individual Components

1. Authlete API

2. Authlete IDP

3. Authlete Console