cli-onboard

Provides a way to onboard a new Akamai Property Manager and Akamai Security configuration using any flexible user-defined setup. You can include any desired settings (subject to authorization and entitlements) such as:

Any property manager configuration json rule template
Standard TLS or Enhanced TLS Network
Use new or existing SSL Certificates and Edge Hostnames
Include in existing WAF configurations (Add Selected Hosts and/or Match Targets)
Flexible activation to staging or production network

Prerequisites - Setup API Credentials

In order to use this module, you need to:

Set up your credentials in your .edgerc file
The default section used in your configuration file should be called onboard. If you wish to override, you may also use the --section <section_name> to use the specific section credentials from your .edgerc file
Your API credential should include at least the following grants:
- Property Manager (/papi)
- Edge Hostnames API (/hapi)
- Certificate Provisioning System (/cps)
- Application Security (/appsec)

[onboard]
client_secret = [CLIENT_SECRET]
host = [HOST]
access_token = [ACCESS_TOKEN_HERE]
client_token = [CLIENT_TOKEN_HERE]

Akamai Onboard CLI Install

%  akamai install onboard
%  akamai install property-manager (if not already installed)

Onboard Types

This CLI has 4 command types for onboarding new properties:

create
single-host
multi-hosts
batch-create
fetch-sample-templates
appsec-policy
appsec-create
appsec-update

create

Usage

akamai onboard create --file /templates/sample_setup_files/create.json
akamai onboard create --file ~/path/to/create.json

Setup JSON File Documentation

Sample templates/sample_setup_files/create.json for an initial empty setup file.

Click me

{
"property_info": {
    "property_name": "",
    "secure_network": "STANDARD_TLS",
    "contract_id": "ctr_",
    "group_id": "grp_",
    "product_id": "prd_",
    "version_notes": "",
    "rule_format": "latest",
    "default_cpcode": {
        "create_new_cpcode": false,
        "new_cpcode_name": ""

    },
    "file_info": {
        "use_file": false,
        "source_template_file": "",
        "source_values_file": ""
    },
    "folder_info": {
        "use_folder": false,
        "folder_path": "",
        "env_name": ""
    }
},
"public_hostnames": [
    ""
],
"edge_hostname": {
    "mode": "new_standard_tls_edgehostname",
    "use_existing_edgehostname": {
        "edge_hostname": ""
    },
    "new_standard_tls_edgehostname": {},
    "new_enhanced_tls_edgehostname": {
        "ssl_cert_info": {
            "use_existing_enrollment_id": false,
            "existing_enrollment_id": 0,
            "create_new_ssl_cert": false,
            "ssl_cert_template_file": "",
            "ssl_cert_template_values": "",
            "temp_existing_edge_hostname": ""

        }
    },
    "secure_by_default": {
        "create_new_edge_hostnames": false,
        "use_existing_edge_hostname": ""
    }
},
"activate_property_staging": false,
"update_waf_info": {
    "add_selected_host": false,
    "waf_config_name": "",
    "update_match_target": false,
    "waf_match_target_id": 0
},
"activate_waf_policy_staging": false,
"activate_property_production": false,
"activate_waf_policy_production": false,
"notification_emails": [
    ""
]
}

Field Descriptions

Show me

property_name: Name of the property manager configuration to be created
secure_network: Use either ENHANCED_TLS or STANDARD_TLS
contract_id: Contract ID (starts with ctr_)
group_id: Group ID (starts with grp_)
product_id: Product ID (usually starts with prd* and should be one of available products from specified contract_id)
rule_format: Rule format (typically latest, but can you frozen rule format if desired)

default_cpcode

create_new_cpcode: Specify true if you want a brand new cp code created as part of the new property manager configuration
new_cpcode_name: If create_new_cpcode is true, specify name of new cp code

file_info

use_file: Specify true if you want to use a single file json template
source_template_file: File path to single file json template. This file can have ${env.variable} references to serve place holders that will be substituted from values in source_values_file
source_values_file: File path to the single file variable values. This source values file can look like this:

{
	"origin_default": "origin-www.dummy.com",
	"cpcode_default": 12345
}

folder_info

use_folder: Specify true if you want to use an existing Akamai pipeline folder structure. This folder should contain the projectInfo.json and environments folder
folder_path: File path to the Akamai pipeline folder
env_name: Environment name to build. This name should be defined in projectInfo.json and have correct setting and variable values in environments folder

public_hostnames

Array of property hostnames in this new configuration

edge_hostname

For a new property manager configuration, we can use an existing edge hostname, create a new standard_tls edge hostname, or create a new enhanced_tls edge hostname
mode: Should be one of: use_existing_edgehostname, new_standard_tls_edgehostname, new_enhanced_tls_edgehostname, secure_by_default

use_existing_edgehostname

edge_hostname: Specify the existing edge hostname to use.
- If using ENHANCED_TLS, this should end with edgekey.net
- If using STANDARD_TLS, this should end with edgesuite.net

new_enhanced_tls_edgehostname -- use existing enrollment

use_existing_enrollment_id: Set to true if you want to create a new edge hostname from an existing certificate enrollment. If true, you must also put in value for the existing_enrollment_id.
existing_enrollment_id: Enrollment ID of the existing certificate

new_enhanced_tls_edgehostname -- create new enrollment

create_new_ssl_cert: Set to true if you want to brand new certificate enrollment. If true, you must also put in values for the ssl_cert_template_file, ssl_cert_template_values, and use_temp_existing_edge_hostname_id (NOT USED ANYMORE)
ssl_cert_template_file: File path to ssl certificate template json file. This can be for any certificate type (NOT USED ANYMORE)
ssl_cert_template_values: Values for the ssl certificate template to be used (NOT USED ANYMORE)
temp_existing_edge_hostname: Due to backend api limitations, a new edge hostname cannot be immediately made that references a newly created certificate enrollment for a brief period of time. Rather than be blocked by this process, specify a temporary edge hostname to use as a placeholder. This value is not really used and just a place holder to proceed with the property manager configuration creation. If using ENHANCED_TLS, use an existing edge hostname ends with edgekey.net ; otherwise if using STANDARD_TLS, use an existing edge hostname that ends with edgesuite.net (NOT USED ANYMORE)

secure_by_default -- provision secure by default certificates

create_new_edge_hostnames: set to true if you want a new unique edge hostname created for each onboarded hostname. The edge hostnames created will be in the form {hostname}.edgekey.net
use_existing_edge_hostname: add an existing edge hostname to use - it must be SNI. All Secure by Default certificates are SNI.

update_waf_info

add_selected_host: Set to true if you want to add specified public_hostnames to WAF selected hosts
waf_config-name: Name of security configuration
update_match_target: Set to true if you want to add specified public_hostnames to specified waf_match_target_id
waf_match_target_id: waf match target id to add hostnames to (use numeric waf match target id)
NOTE: If you do not know the match target id, leave the value as 0 and execute the onboarding. The validation steps will print out the existing match target IDs for the WAF config selected.
NOTE: These settings can only happen if property manager configuration is activated on the Akamai Staging network

activate settings

activate_property_staging: Activate property manager configuration to staging network
activate_property_production: Activate property manager configuration to production network (must go through staging first)
activate_waf_policy_staging: Activate security configuration to staging network
activate_waf_policy_production: Activate security configuration to production network (must go through staging first)
notification_emails: Array of emails to be notified after activations

single-host

Description

single-host creates a property with one public hostname at the top level of the contract unless group_id is specified in the JSON file.

Usage

akamai onboard single-host --file /templates/sample_setup_files/single.json
akamai onboard single-host --file ~/path/to/single.json

{
    "property_info": {
        "contract_id": "ctr_",
        "product_id": "prd_",
        "property_hostname": "",
        "property_origin": ""
    },
    "edge_hostname": {
        "secure_by_default": true,
        "use_existing_edge_hostname": "",
        "create_from_existing_enrollment_id": 0
    },
    "update_waf_info": {
        "create_new_security_config": true,
        "waf_config_name": ""
    },
    "activate_production": false,
    "notification_emails": [
        "noreply@akamai.com"
    ]
}

Field Descriptions

Show me

contract_id: Contract ID (starts with ctr_)
product_id: Product ID: one of prd_SPM, prd_Fresca,prd_API_Accel (case sensitive)
property_hostname: Public facing hostname. This will be used as the name of the property.
property_origin: Origin hostname for property_hostname
activate_production: Activate to Akamai production network (single-mode will always activate property on the Akamai staging)
notification_emails: Array of emails to be notified after activations

Optional Values:

group_id: Group ID (starts with grp_) If you do not have security at the contract/top level or you would like to put the property on a specify property group.
version_notes: Allow you to override the default value Initial Version

edge_hostname

secure_by_default: set to true if you want to provision a default certificate for the hostname. This will automatically create a new edge hostname.
use_existing_edge_hostname: specify existing edge hostname to use (must already exist). Value will not be used if secure_by_default is set to true.
create_from_existing_enrollment_id: create new edge hostname from existing certificate enrollment id (must already exist)

update_waf_info

create_new_security_config:
- set to true will create default security configuration in alert mode
- set to false will not create a security configuration
waf_config_name: name of new security config to be created. If blank, the default policy will be WAF Security File

multi-hosts

Description

multi-hosts creates a property with multiple public hostnames at the top level of the contract unless group_id is specified in the JSON file.

Usage

akamai onboard multi-hosts -f path-to/multiple.json --csv path-to/multi-hosts-input.csv

{
  "property_info": {
    "contract_id": "ctr_",
    "product_id": "prd_",
    "property_name": "",
    "individual_cpcode": false
  },
  "edge_hostname": {
    "secure_by_default": false,
    "use_existing_edge_hostname": "",
    "create_from_existing_enrollment_id": 0
  },
  "update_waf_info": {
    "create_new_security_config": true,
    "waf_config_name": ""
  },
  "activate_production": true,
  "notification_emails": ["noreply@akamai.com"]
}

Field Descriptions

contract_id: Contract ID (starts with ctr_) You can get this information from Akamai Technical Project Manager
product_id: Supported Product ID are prd_SPM, prd_Fresca, prd_API_Accel (case sensitive)
property_name: Name of the property aka delivery configuration
individual_cpcode: Set to true if you want to create cp code for each hostname
The rest is the same as single-host mode

Optional Values:

group_id: Group ID (starts with grp_) If you do not have security at the contract/top level or you would like to put the property on a specify property group.

batch-create

Description

batch-create creates and optionally activates multi properties based on a custom json template and csv input file. It can add multiple hostnames and origin behaviors to a single property, or create multiple porperties.

Usage

akamai onboard batch-create --template ~/path/to/ruletree.json --csv ~/path/to/csv.csv --product prd_SPM --group grp_1234 --contract ctr_1-2345
akamai onboard batch-create --template ~/path/to/ruletree.json --csv ~/path/to/csv.csv --product prd_SPM --group grp_1234 --contract ctr_1-2345 --secure-by-default

CSV Input File Documentation

Sample templates/sample_setup_files/batch-activation.csv for an initial empty setup file.

Click me

hostname,origin,propertyName,forwardHostHeader,edgeHostname
www.example.com,origin.example.com,new_property_1,ORIGIN_HOSTNAME,www.example.com.edgekey.net

hostname: [required] Hostname that you want to onboard
origin: [required] Origin hostname
propertyName: Name of property. If empty or column is missing, defaults to hostname.
- If 2 rows have the same propertyName, the hostnames will be added to the same property and an origin behavior ruleset will be injected into the input template
forwardHostHeader: Host header used on forward request to origin. Can be either REQUEST_HOST_HEADER or ORIGIN_HOSTNAME. If empty or column is missing, defaults to REQUEST_HOST_HEADER. This setting will override whatever is in the input template default origin behavior.
edgeHostname: [required unless using secure_by_default] The edge hostname to map the hostname to. The edge hostname must already exist. batch-create mode does NOT create new edge hostnames unless secure-by-default mode is being used.

Input Descriptions

Show me

--template -t: file path to single file json template. [required]
--csv: csv file with headers hostname,origin,edgeHostname,forwardHostHeader,propertyName [required]
--network -n: use either ENHANCED_TLS or STANDARD_TLS [default:ENHANCED_TLS]
--contract -c: Contract ID (starts with ctr_) [required]
--group -g: Group ID (starts with grp_) [required]
--product -p: Product ID (usually starts with prd* and should be one of available products from specified contract_id) [required]
--rule-format -f: Rule format (typically latest, but can you frozen rule format if desired) [default:latest]
--use-cpcode: Override creation of new cpcodes and use single cpcode for all properties
--secure-by-default: Use secure by default certificates
--waf-config: name of security configuration to update
--waf-match-target: waf match target id to add hostnames to (use numeric waf match target id)
--activate: Activation networks. If activating waf on a network, delivery must also be activated. Options: delivery-staging, delivery-production, waf-staging, waf-production
--email: email(s) for activation notifications

fetch-sample-templates

This will create a folder called sample_setup_files locally so you will have sample setups in both JSON and CSV format depending on the command you choose the onboard.

command	Required JSON	Required CSV
`create`	✔️
`single-host`	✔️
`multi-hosts`	✔️	✔️
`batch-create`	✔️	✔️
`appsec-create`		✔️
`appsec-update`		✔️

appsec-policy

This is a helper command to list existing security configurations on the account. The result displays security configuration name and id. If --waf-config-name is provided, the result displays associated policies and website match targets. This information is essential for appsec-update command

Usage

akamai onboard appsec-policy
akamai onboard appsec-policy --name-contains test
akamai onboard appsec-policy --waf-config-name sample_sec
akamai onboard appsec-policy --waf-config-name sample_sec --policy-name Default

appsec-create

You can onboard multiple hostnames to a new security configuration with an option to activate. If you choose to activate, everything will be set on alert mode on the 1st version. Currently, we only allow multiple hostnames when they are on the same group and contract.

There are two templates available. You can upload by hostname or by property name. Default option is by hostname. If the template has propertyname on the header, you need to provide argument --by propertyname

Use fetch-sample-templates command to get sample templates

Usage

# create only
akamai onboard appsec-create -c ctr_1111 -g grp_1111 --csv appsec-create-by-hostname.csv
akamai onboard appsec-create -c ctr_1111 -g grp_1111 --csv appsec-create-by-propertyname.csv --by propertyname

# create and activate on Akamai staging network
akamai onboard appsec-create -c ctr_1111 -g grp_1111 --csv appsec-create-by-hostname.csv --activate staging --email noreply@akamai.com
akamai onboard appsec-create -c ctr_1111 -g grp_1111 --csv appsec-create-by-hostname.csv --activate production --email noreply@akamai.com

# create and activate on Akamai staging and production network
akamai onboard appsec-create -c ctr_1111 -g grp_1111 --csv appsec-create-by-propertyname.csv --by propertyname --activate staging --email noreply@akamai.com
akamai onboard appsec-create -c ctr_1111 -g grp_1111 --csv appsec-create-by-propertyname.csv --by propertyname --activate production --email noreply@akamai.com

CSV Input File Documentation

Template 1 - By hostname [Default]

Click me

Sample templates/sample_setup_files/appsec-create-by-hostname.csv for an initial empty setup file.

waf_config_name,waf_policy_name,hostname
ah_onboard_1,policy_1,sample-hostname-1.com
ah_onboard_1,policy_1,sample-hostname-2.com
ah_onboard_1,policy_1,sample-hostname-3.com
ah_onboard_1,policy_1,sample-hostname-4.com
ah_onboard_1,policy_2,sample-hostname-5.com
ah_onboard_1,policy_3,sample-hostname-6.com
ah_onboard_1,policy_3,sample-hostname-7.com
ah_onboard_appsec_h1,Default,demo-hostname.com

2 security configuration will be created ah_onboard_1 and ah_onboard_appsec_h1
For security config ah_onboard_1,
- 3 security policies will be created policy_1, policy_1, and policy_3
  - policy_1 protects 4 hostnames
  - policy_2 protects 1 hostname
  - policy_3 protects 2 hostnames
For security config ah_onboard_appsec_h1,
- Only one security policy named Default is created and protect only one hostname demo-hostname.com

Template 2 - By property name

Click me

Sample **templates/sample_setup_files/appsec-create-by-propertyname.csv** for an initial empty setup file.

property_name,waf_config_name,waf_policy_name,hostname
sample,appsec_X,policy_1
sample,appsec_X,policy_2,sample-hostname-1.com
sample,appsec_X,policy_2,sample-hostname-2.com
sample,appsec_Y,policy_1,demo-hostname-1.com
sample,appsec_Z,policy_1,eg-hostname-1.com
sample,appsec_Z,policy_1,eg-hostname-2.com
another_sample,appsec_A,Default

4 security configuration will be created appsec_X, appsec_Y, appsec_Z, appsec_A
For security config appsec_X,
- 2 security policies will be created policy_1 and policy_2
  - policy_1 will protect ALL Hostnames available from property named sample
  - policy_2 will protect 2 hostnames
For security config appsec_Y,
- Only one security policy named policy_1 is created and protect only one hostname demo-hostname-1.com
For security config appsec_Z,
- Only one security policy named policy_1 is created but protect 2 hostnames eg-hostname-1.com and eg-hostname-2.com
For security config appsec_A,
- Only one security policy named Default is created
- ALL Hostnames available from property named another_sample will be protected

appsec-update

You can onboard multiple hostnames to an existing security configuration and optionally add to policy match target and activate.

Use fetch-sample-templates command to get sample templates

# update only
akamai onboard appsec-update --config-id 9999 --csv appsec-update.csv

# update and activate
akamai onboard appsec-update --config-id 9999 --csv appsec-update.csv --activate staging --email noreply@akamai.com --version-notes "add 3 hostnames"

CSV Input File Documentation

Click me

Sample templates/sample_setup_files/appsec-update.csv for an initial empty setup file.

hostname,matchTargetId
www.example-1.com,1111111
www.example-2.com,1111111
www.example-3.com,2222222

2 hostnames will be added to WAF match target id 1111111 on security configuration id 9999
1 hostname will be added to WAF match target id 2222222 on security configuration id 9999

Contribution

By submitting a contribution (the “Contribution”) to this project, and for good and valuable consideration, the receipt and sufficiency of which are hereby acknowledged, you (the “Assignor”) irrevocably convey, transfer, and assign the Contribution to the owner of the repository (the “Assignee”), and the Assignee hereby accepts, all of your right, title, and interest in and to the Contribution along with all associated copyrights, copyright registrations, and/or applications for registration and all issuances, extensions and renewals thereof (collectively, the “Assigned Copyrights”). You also assign all of your rights of any kind whatsoever accruing under the Assigned Copyrights provided by applicable law of any jurisdiction, by international treaties and conventions and otherwise throughout the world.

Local Install

Minimum python 3.6 git clone https://github.com/akamai/cli-onboard.git
cd into cli-onboard directory cd cli-onboard
Create python virtual environment python3 -m venv .venv
Install required packages pip3 install -r requirements.txt
If testing another branch i.e shared-policy run git checkout -b shared-policy
Verify as Akamai CLI, first uninstall existing version akamai uninstall onboard
Install from local repo
- Run pwd to get current directory i.e /Users/Documents/cli-onboard
  - For MAC OS, run akamai install file:///Users/Documents/cli-onboard
    - Please note there is 3 slashes
  - For Window, run akamai install file://C:/Users/sample/cli-onboard
    - Only 2 slashes

Notice

All works contained in this repository, excepting those explicitly otherwise labeled, are the property of Akamai Technologies, Inc.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

cli-onboard

Prerequisites - Setup API Credentials

Akamai Onboard CLI Install

Onboard Types

create

Usage

Setup JSON File Documentation

Field Descriptions

single-host

Description

Usage

Field Descriptions

multi-hosts

Description

Usage

Field Descriptions

batch-create

Description

Usage

CSV Input File Documentation

Input Descriptions

fetch-sample-templates

appsec-policy

Usage

appsec-create

Usage

CSV Input File Documentation

Template 1 - By hostname [Default]

Template 2 - By property name

appsec-update

CSV Input File Documentation

Contribution

Local Install

Notice

Files

README.md

Latest commit

History

README.md

File metadata and controls

cli-onboard

Prerequisites - Setup API Credentials

Akamai Onboard CLI Install

Onboard Types

create

Usage

Setup JSON File Documentation

Field Descriptions

single-host

Description

Usage

Field Descriptions

multi-hosts

Description

Usage

Field Descriptions

batch-create

Description

Usage

CSV Input File Documentation

Input Descriptions

fetch-sample-templates

appsec-policy

Usage

appsec-create

Usage

CSV Input File Documentation

Template 1 - By hostname [Default]

Template 2 - By property name

appsec-update

CSV Input File Documentation

Contribution

Local Install

Notice