Deploy Access Gateway into Amazon Web Services


The purpose of this guide is to walk through the process of deploying the Access Gateway software appliance into an Amazon Web Services (AWS) EC2 virtualization environment.


  • You have reviewed all Prerequisites for Deploying Access Gateway
  • You have the aws-cli installed and configured on your local machine. Note that many of the commands also have a GUI equivalent.
  • You have access rights in AWS to define IAM policies, create S3 buckets, and AMI images.
  • You are familiar with AWS S3, EC2, cli, and AMIs commands and concepts.

What’s covered in this guide

AWS can import and use the Okta Access Gateway virtual appliance. In order to use the OVA with AWS we must:

  • Create an S3 bucket to store the OVA and converted image. AWS stores files in buckets.  Typically an import uses one bucket to store the original import and a second as the target of the convert to AMI process. During this procedure will use the same bucket for import and convert.
  • Create the vmimport identity. AWS requires the use of this special identity for OVA imports.
  • Assign privileges to the vmimport identity. AWS requires a variety of privileges in order to access an S3 bucket.
  • Convert an OVA to an AMI.  Once configured, the vmimport account, and S3 bucket can be used to convert an image.

The process includes:

  1. Download the latest OVA image
  2. Determine your region
  3. Upload Access Gateway OVA image to AWS.
  4. Convert and import the OVA Image to an Amazon Image (AMI)

Determine your region

Your AWS region is required to convert an OVA image to an AWS AMI image.
To determine your region:

  1. Open a terminal.

  2. Use the aws configure list command to determine your current region.
    For example:

    aws configure list 
    . . . 
    region		us-east-1	config file	~/.aws/config
    . . .

  3. Note the region as it will be required to convert the OVA to an AWS AMI file



    Region can also be identified by logging into the AWS console, where the default region is shown to the right of account information.
    Default region

Upload Access Gateway OVA image to AWS.

An AWS S3 bucket can be created using either the AWS CLI or via AWS UI. Note that this procedure uses the same bucket for import and convert.

To create an S3 bucket using the UI

  1. Login to AWS as root.

  2. Select Services.

  3. In the Storage section click S3.

  4. Click + Create Bucket.

  5. Enter an appropriate name, for example my-access-gateway-bucket.

  6. From the Region drop down select the correct region.

  7. Follow the wizard steps finish creating the bucket.

Note: Buckets can be created at the command line using the aws s3api create-bucket command. For example:

aws s3api create-bucket --bucket okta-access-gateway-ova-bucket --region us-east-1 --create-bucket-configuration LocationConstraint=us-east-1
Which will return something similar to:
    "Location": "/my-access-gateway-bucket"

Upload the Okta Access Gateway OVA to the bucket

To upload the OVA to the bucket using the UI:

  1. In the Storage section click S3.

  2. In the bucket list click the bucket name.

  3. Click Upload.

  4. Click Add Files.

  5. Navigate to the OVA file, select it and click Next.

  6. Click Next thru the follow on upload steps.
    When complete the OVA will be uploaded to the bucket.

Note: Files can be uploaded to an existing bucket using the aws s3 cp command. For example,

aws s3 cp Okta-Access-Gateway.ova s3://my-access-gateway-bucket
aws s3 ls s3://my-access-gateway-bucket
2019-09-11 12:36:00   . . .  Okta-AccessGateway.ova

Convert and import the OVA Image to an Amazon Image (AMI)

Importing an OVA to AWS is a multi-step process.

  1. Open a terminal window.

  2. Create the required vmimport IAM identity role to import images
    Note: AWS requires the use of the vmimport identity role when importing an OVA.

    1. Create a json file, representing the trust policy for the vmimport IAM identity role as follows:
          "Version": "2012-10-17",
          "Statement":[ {
              "Effect": "Allow",
              "Principal": { "Service": "" },
              "Action": "sts:AssumeRole",
              "Condition": {
              "StringEquals":{ "sts:Externalid": "vmimport"}


    2. In a terminal window create the IAM identity role using the aws iam create-role command using the new trust policy, as shown:

      aws iam create-role --role-name vmimport --assume-role-policy-document "file://~/Downloads/trust-policy.json

      Which should return a result similar to:
          "Role": {
              AssumeRolePolicyDocument": {. . . }
      	"Arn": "arn:aws:iam::809227661992:role/vmimport"

    3. Create a role policy to associate the new IAM identity with the previously created bucket.

             }, {
             }, {

      Replacing BUCKET_NAME with the previously created buckets name.

    4. Grant an inline role policy to vmimport identity granting various rights to access S3 bucket and perform ec2 operations using the aws iam put-role-policyy command. For example:

      aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document "file://~/Downloads/role-policy.json"

      Note the aws iam put-role-policy command does not return any value on success.

  3. Using the vmimport identity to convert the OVA image to an AMI image

    1. Create a json file representing the locations for the containers used during the import.
              "Description": "DESCRIPTION",
              "Format": "ova",
              "UserBucket": {
                  "S3Bucket": "BUCKET_NAME",
                  "S3Key": "FILE_NAME"

      BUCKET_NAME with the bucket name. For example "access-gateway-bucket".
      DESCRIPTION with an appropriate description. For example, "Okta Access Gateway".
      FILE_NAME with the specific name of the OVA file. For example "Okta-AccessGateway.ova".

    2. Begin the import process using a command similar to: :
      aws ec2 import-image --description "Okta Access Gateway" --license-type "BYOL" --disk-containers "file://~/Downloads/containers.json" 
    3. Examine the output of command and note the task id associated with the import process.

      	"Status": "active", 
      	"LicenseType": "BYOL", 
      	"Description": "AG2019.ova.", 
      	"SnapshotDetails": [...], 
      	"Progress": "2", 
      	"StatusMessage": "pending", 
      	    "ImportTaskId": "import-ami-08800a79da64acae7"

    4. Examine the progress of the import using the task id
      aws ec2 describe-import-image-tasks --import-task-ids TASK_ID
      Where task id is the value from the prior step. For example:
      aws ec2 describe-import-image-tasks --import-task-ids import-ami-08800a79da64acae7

      Import progress is noted in the Progress json element and represents a percentage from 0-100%.

      1. Monitor the import until it reaches status completed. For example:

            "ImportImageTasks": [
        		"Status": "completed", 
        		"LicenseType": "BYOL", 
        		"Description": "AG2019.ova.",
        		ImageId": "ami-0c20c537e7f8dd6a5"

        Note the ImageId field, it will be used to confirm the image import in the AWS console.

  4. Confirm that the import completed in the AWS console

    1. Return to the AWS console

    2. Navigate to Services > EC2.

    3. In the left hand navigation pane select Images > AMI.

    4. Examine the image list, searching for the image with matching id.

      AWS AMI Image list

AWS Specific Post Installation

The following AWS post installation steps are required to complete the deployment of Okta Access Gateway in an AWS environment.

Next Steps

After Okta Access Gateway has been installed there are a number of common post installation tasks that should be performed.

For More Information