Setup Access Gateway using Amazon Web Services


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

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.


  • You have reviewed all Prerequisites for Deploying Access Gateway
  • You have the aws-cli installed and configured on your local machine.
  • 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

Download the latest OVA image.

To download the latest Okta Access Gateway OVA Image

  1. See Okta Support to both enable this feature and for a link to the latest Okta Access Gateway OVA image file.

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 | grep region command to determine your current region.
    For example:

    $ aws configure list | grep region
    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

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 to import images
    Note: AWS requires the use of the vmimport identity when importing an OVA.

    1. Create a json file, representing the trust policy for the vmimport IAM identity 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 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://~/Download/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 "AG2019.ova." --license-type "BYOL" --disk-containers "file://~/Downloads/containers.json".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 deployement 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