Menu
Amazon EC2 Systems Manager
User Guide

Systems Manager Parameter Store

Storing and referencing configuration data such as passwords, license keys, key pairs, certificates, and lists of users can be a time-consuming and error-prone process, especially at scale. Storing and using password in a secure manner is equally challenging at scale. Parameter Store efficiently and securely centralizes the management of configuration data that you commonly reference in scripts, commands, or other automation and configuration workflows. Parameter Store lets you reference parameters (called Systems Manager parameters) across Systems Manager features, including Run Command, State Manager, and Automation.

For parameters such as passwords or key pairs that should be encrypted, Parameter Store lets you encrypt data by using an AWS Key Management Service (AWS KMS) key. You can then delegate access to users who should be allowed to decrypt and view the sensitive data. You can also monitor and audit parameter usage in Amazon EC2 or AWS CloudTrail.

About Parameter Store

A parameter is a key-value pair that you create by specifying the following information.

  • Name: (Required) Specify a name to identify your parameter. Be aware of the following requirements and restrictions for Systems Manager parameter names:

    • A parameter name must be unique within your AWS account.

    • Parameter names are case-sensitive.

    • A parameter name can't be prefixed with "aws" or "ssm" (case-insensitive). For example, awsTestParameter or SSM-testparameter will fail with an exception.

    • Parameter names can only include the following symbols and letters:

      a-zA-Z0-9_.-

  • Data Type: (Required) Specify a data type to define how the system uses a parameter. Parameter Store currently supports the following data types: String, String List, and Secure String.

  • Description (Optional): Type a description to help you identify your parameters and their intended use.

  • Value: (Required) Your parameter value.

  • Key ID (for Secure String): Either the default AWS KMS key automatically assigned to your AWS account or a custom key.

Note

You can use a period "." or an underscore "_" to group similar parameters. For example, you could group parameters as follows: prod.db.string and prod.domain.password.

Using Systems Manager Parameters

After you create a parameter, you can specify it in your SSM documents, commands, or scripts using the following syntax (no space between brackets):

{{ssm:parameter_name}} or {{ ssm:parameter_name }}

Note

The name of a Systems Manager parameter can't be prefixed with "ssm" or "aws", but when you specify the parameter in an SSM document or a command, the name must be prefixed with "ssm:". Valid: {{ssm:addUsers}}. Invalid: {{ssm:ssmAddUsers}}.

The following is an example of an AWS CLI Run Command command using an SSM Parameter.

Copy
aws ssm send-command --instance-ids i-1a2b3c4d5e6f7g8 --document-name AWS-RunPowerShellScript --parameter '{"commands":["echo {{ssm:addUsers}}"]}'

Note

The runtimeConfig section of SSM documents use similar syntax for local parameters. You can distinguish local parameters from Systems Manager parameters by the absence of the "ssm:" prefix.

Copy
"runtimeConfig":{ "aws:runShellScript":{ "properties":[ { "id":"0.aws:runShellScript", "runCommand":"{{ commands }}", "workingDirectory":"{{ workingDirectory }}", "timeoutSeconds":"{{ executionTimeout }}"

You can reference Systems Manager parameters in the Parameters section of an SSM document, as show in the following example.

Copy
{ "schemaVersion":"2.0", "description":"Sample version 2.0 document v2", "parameters":{ "commands" : { "type": "StringList", "default": ["{{ssm:commands}}"] } }, "mainSteps":[ { "action":"aws:runShellScript", "name":"runShellScript", "inputs":{ "commands": "{{commands}}" } } ] }

Predefined SSM documents (all documents that begin with "AWS-") currently don't support Secure Strings or references to Secure String type parameters. This means that to use Secure String parameters with Run Command, you have to retrieve the parameter value before passing it to Run Command, as shown in the following examples:

Linux

Copy
$value=aws ssm get-parameters --names secureparam --with-decryption
Copy
aws ssm send-command –name AWS-JoinDomain –parameters password=$value –instance-id instance_ID

Windows

Copy
$secure = (Get-SSMParameterValue -Names SecureParam -WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -AsPlainText -Force
Copy
$cred = New-Object System.Management.Automation.PSCredential -argumentlist username,$secure

About Secure String Parameters

A secure string is any sensitive data that needs to be stored and referenced in a secure manner. If you have data that you don't want users to alter or reference in clear text, such as domain join passwords or license keys, then create those parameters using the Secure String data type. You should use secure strings when:

  • You want to use data/parameters across AWS services without exposing the values as clear text in commands, functions, agent logs, or AWS CloudTrail logs.

  • You want to control who has access to sensitive data.

  • You want to be able to audit when sensitive data is accessed (AWS CloudTrail).

  • You want AWS-level encryption for your sensitive data and you want to bring your own encryption keys to manage access.

If you choose the Secure String data type when you create your parameter, then AWS KMS encrypts the parameter value. For more information about AWS KMS, see AWS Key Management Service Developer Guide.

Each AWS account is assigned a default AWS KMS key. You can view your key by executing the following command from the AWS CLI:

Copy
aws kms describe-key --key-id alias/aws/ssm

Create a Secure String Parameter Using the Default KMS Key

If you create a Secure String parameter using the default KMS key, then you don't have to provide a value for the Key ID parameter. The following CLI example shows the command to create a new Secure String parameter in Parameter Store without the --key-id parameter:

Copy
aws ssm put-parameter --name secure_string1_default_key --value "a_secure_string_value" --type SecureString

Create a Secure String Parameter Using Your KMS Customer Master Key (CMK)

If you want to use a custom KMS key instead of the default key assigned to your account, then you must specify the ARN using the --key-id parameter. The parameter supports all AWS KMS parameter formats. For example:

  • Key ARN example

    arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

  • Alias ARN example

    arn:aws:kms:us-east-1:123456789012:alias/MyAliasName

  • Globally Unique Key ID example

    12345678-1234-1234-1234-123456789012

  • Alias Name example

    alias/MyAliasName

You can create a custom AWS KMS key from the AWS CLI by using the following commands:

Copy
aws kms create-key

Use the following command to create a Secure String parameter using the key you just created.

Copy
aws ssm put-parameter --name secure_string1_custom_key --value "a_secure_string_value" --type SecureString --key-id arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e

Note

You can manually create a parameter with an encrypted value. In this case, because the value is already encrypted, you don’t have to choose the Secure String data type. If you do choose Secure String, your parameter will be doubly encrypted.

By default, all Secure String values are displayed as cipher text in the Amazon EC2 console and the AWS CLI. To decrypt a Secure String value, a user must have KMS decryption permissions, as described in the next section.

Secure String Parameter Walkthrough

This walkthrough shows you how to join a Windows instance to a domain using Systems Manager Secure String parameters and Run Command. The walkthrough uses typical domain parameters, such as the DNS address, the domain name, and a domain user name. These values are passed as unencrypted string values. The domain password is encrypted and passed as a Secure String.

To create a Secure String Parameter and Join a Domain to an Instance

  1. Enter parameters into the system using AWS Tools for Windows PowerShell.

    Copy
    Write-SSMParameter -Name dns -Type String -Value DNS_IP_Address Write-SSMParameter -Name domainName -Type String -Value Domain_Name Write-SSMParameter -Name domainJoinUserName -Type String -Value DomainJoinUserName Write-SSMParameter -Name domainJoinPassword -Type SecureString -Value DomainJoinPassword
  2. Attach the AmazonEC2RoleforSSM managed policy to the IAM role permissions for your instance. For information, see Managed Policies and Inline Policies.

  3. Edit the IAM role attached to the instance and add the following policy. This policy gives the instance permissions to call the kms:Decrypt API.

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt", ], "Resource": [ "arn:aws:kms:region:account_id:key/key_id" ] } ] }
  4. Copy and paste the following json sample into a simple text editor and save the file as JoinInstanceToDomain.json in the following location: c:\temp\JoinInstanceToDomain.json.

    Copy
    { "schemaVersion":"2.0", "description":"Run a PowerShell script to securely domain-join a Windows instance", "mainSteps":[ { "action":"aws:runPowerShellScript", "name":"runPowerShellWithSecureString", "inputs":{ "runCommand":[ "$ipdns = (Get-SSMParameterValue -Name dns).Parameters[0].Value\n", "$domain = (Get-SSMParameterValue -Name domainName).Parameters[0].Value\n", "$username = (Get-SSMParameterValue -Name domainJoinUserName).Parameters[0].Value\n", "$password = (Get-SSMParameterValue -Name domainJoinPassword -WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -asPlainText -Force\n", "$credential = New-Object System.Management.Automation.PSCredential($username,$password)\n", "Set-DnsClientServerAddress \"Ethernet 2\" -ServerAddresses $ipdns\n", "Add-Computer -DomainName $domain -Credential $credential\n", "Restart-Computer -force" ] } } ] }
  5. Execute the following command in AWS Tools for Windows PowerShell to create a new SSM document.

    Copy
    $json = Get-Content C:\temp\JoinInstanceToDomain | Out-String New-SSMDocument -Name JoinInstanceToDomain -Content $json
  6. Execute the following command in AWS Tools for Windows PowerShell to join the instance to the domain

    Copy
    Send-SSMCommand -InstanceId Instance-ID -DocumentName JoinInstanceToDomain