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

Parameter Usage Examples

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}}" } } ] }

Note

The runtimeConfig section of SSM documents use similar syntax for local parameters. A local parameter isn't 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":"0.aws:runShellScript", "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:

AWS CLI

$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

Use 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, see How AWS Systems Manager Parameter Store Uses AWS KMS in the AWS Key Management Service Developer Guide.

Important

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 CMK

Systems Manager includes a default AWS KMS customer master key (CMK). 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 CMK, 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 Custom KMS CMK

If you want to use a custom KMS CMK instead of the default CMK assigned to your account, then you must specify the custom KMS CMK by using the --key-id parameter. The parameter supports the following AWS KMS parameter formats.

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

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. To decrypt a Secure String value, a user must have permission to call the KMS Decrypt API action. For information about configuring KMS access control, see Authentication and Access Control for AWS KMS in the AWS Key Management Service Developer Guide.

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 Walkthrough: 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.