AWS Systems Manager
User Guide

About Systems Manager Parameters

You can reference Systems Manager parameters in your scripts, commands, and configuration and automation workflows. Parameters work with Systems Manager capabilities such as Run Command, State Manager, and Automation. You can also reference parameters in other AWS services such as Amazon Elastic Container Service and AWS Lambda.

With Systems Manager capabilities, you can reference Systems Manager parameters in your AWS CLI or AWS Tools for Windows PowerShell commands or scripts. You can also reference parameters in SSM documents. For more information about SSM documents, see AWS Systems Manager Documents.

The following is an example of a Systems Manager parameter in an AWS CLI command for Run Command. Systems Manager Parameters are always prefixed with ssm:.

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

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

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


The runtimeConfig section of SSM documents use similar syntax for local parameters. A local parameter is not the same as a Systems Manager parameter. You can distinguish local parameters from Systems Manager parameters by the absence of the ssm: prefix.

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

SSM documents currently don't support references to Secure String parameters. This means that to use Secure String parameters with, for example, Run Command, you have to retrieve the parameter value before passing it to Run Command, as shown in the following examples:


$value=aws ssm get-parameters --names the parameter name --with-decryption
aws ssm send-command –name AWS-JoinDomain –parameters password=$value –instance-id the instance ID

Tools for Windows PowerShell

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

Using Secure String Parameters

A Secure String parameter 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 passwords or license keys, then create those parameters using the Secure String data type. We recommend using Secure String parameters for the following scenarios.

  • 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.


Only the value of the secure string parameter is encrypted. The name of the parameter, description, and other properties are not encrypted. For this reason, consider creating a naming system that avoids the word "password" in parameter names.

Create a Secure String Parameter Using the Default KMS Key

Systems Manager includes a default AWS KMS key. You can view this key by executing the following command from the AWS CLI:

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

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:

aws ssm put-parameter --name a_name --value "a value" --type SecureString

Create a Secure String Parameter Using a 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 the following AWS KMS parameter formats.

  • Key ARN example:


  • Alias ARN example:


  • Globally Unique Key ID example:


  • Alias Name example:


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

aws kms create-key

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

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


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. To decrypt a Secure String value, a user must have KMS decryption permissions.

Using Secure String Parameters With Other AWS Services

You can also use Secure String parameters with other AWS services. In the following example, the Lambda function retrieves a Secure String parameter by using the GetParameters API.

from __future__ import print_function import json import boto3 ssm = boto3.client('ssm', 'us-east-1') def get_parameters(): response = ssm.get_parameters( Names=['LambdaSecureString'],WithDecryption=True ) for parameter in response['Parameters']: return parameter['Value'] def lambda_handler(event, context): value = get_parameters() print("value1 = " + value) return value # Echo back the first key value

Related topics

For an example of how to create and use a Secure String parameter, see Create a Secure String Parameter and Join an Instance to a Domain (PowerShell). For more information about using Systems Manager parameters with other AWS services, see the following blogpost.