This is the new *CloudFormation Template Reference Guide*. Please update your bookmarks and links. For help getting started with CloudFormation, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).

# `AWS::CloudFormation::Authentication`
<a name="aws-resource-authentication"></a>

Use the `AWS::CloudFormation::Authentication` metadata type to specify authentication credentials for files or sources that you specify with the [`AWS::CloudFormation::Init`](aws-resource-init.md) metadata type.

To include authentication information for a file or source that you specify with `AWS::CloudFormation::Init`, use the `uris` property if the source is a URI or the `buckets` property if the source is an Amazon S3 bucket. For more information about files, see [Files](aws-resource-init.md#aws-resource-init-files). For more information about sources, see [Sources](aws-resource-init.md#aws-resource-init-sources).

You can also specify authentication information for files directly in the `AWS::CloudFormation::Init` metadata type. The files key of the resource contains a property named `authentication`. You can use the `authentication` property to associate authentication information defined in the `AWS::CloudFormation::Authentication` metadata type directly with a file.

For files, CloudFormation looks for authentication information in the following order:

1. The `authentication` property of the `AWS::CloudFormation::Init` `files` key.

1. The `uris` or `buckets` property of the `AWS::CloudFormation::Authentication` metadata.

For sources, CloudFormation looks for authentication information in the `uris` or `buckets` property of the `AWS::CloudFormation::Authentication` metadata.

**Topics**
+ [Syntax](#aws-resource-cloudformation-authentication-syntax)
+ [Properties](#w2aac19c23c15c19)
+ [Examples](#aws-resource-authentication-examples)

## Syntax
<a name="aws-resource-cloudformation-authentication-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

Be aware of the following considerations when using the `AWS::CloudFormation::Authentication` metadata type:
+ Unlike most CloudFormation resources, the `AWS::CloudFormation::Authentication` metadata type doesn't contain a block called *Properties*, but instead contains a list of user-named blocks, each containing its own authentication properties.

  Not all properties pertain to each authentication type. For more information, see the [type](#cfn-cloudformation-authentication-type) property.
+ Unlike most CloudFormation resources, `AWS::CloudFormation::Authentication` property names use lower camel case.

### JSON
<a name="aws-resource-cloudformation-authentication-syntax.json"></a>

```
{
  "AWS::CloudFormation::Authentication" {
    "String" : {
      "accessKeyId" : String,
      "buckets" : [ String, ... ],
      "password" : String,
      "secretKey" : String,
      "type" : String,
      "uris" : [ String, ... ],
      "username" : String,
      "roleName" : String
    }
  }
}
```

### YAML
<a name="aws-resource-cloudformation-authentication-syntax.yaml"></a>

```
AWS::CloudFormation::Authentication
String:
  accessKeyId: String
  buckets:
    - String
  password: String
  secretKey: String
  type: String
  uris:
    - String
  username: String
  roleName: String
```

## Properties
<a name="w2aac19c23c15c19"></a>

`accessKeyId`  <a name="cfn-cloudformation-authentication-accesskeyid"></a>
Specifies the access key ID for S3 authentication.  
*Required*: Conditional. Can be specified only if the `type` property is set to `S3`.  
*Type*: String

`buckets`  <a name="cfn-cloudformation-authentication-buckets"></a>
A comma-delimited list of Amazon S3 buckets to be associated with the S3 authentication credentials.  
*Required*: Conditional. Can be specified only if the `type` property is set to `S3`.  
*Type*: List of String values

`password`  <a name="cfn-cloudformation-authentication-password"></a>
Specifies the password for basic authentication.  
*Required*: Conditional. Can be specified only if the type property is set to `basic`.  
*Type*: String

`secretKey`  <a name="cfn-cloudformation-authentication-secretkey"></a>
Specifies the secret key for S3 authentication.  
*Required*: Conditional. Can be specified only if the `type` property is set to `S3`.  
*Type*: String

`type`  <a name="cfn-cloudformation-authentication-type"></a>
Specifies whether the authentication scheme uses a user name and password (basic) or an access key ID and secret key (S3).  
If you specify `basic`, specify the `username`, `password`, and `uris` properties.  
If you specify `S3`, specify the `accessKeyId`, `secretKey`, and `buckets` (optional) properties.  
*Required*: Yes  
*Valid values*: `basic` \$1 `S3`

`uris`  <a name="cfn-cloudformation-authentication-uris"></a>
A comma-delimited list of URIs to be associated with the basic authentication credentials. The authorization applies to the specified URIs and any more specific URI. For example, if you specify `http://www.example.com`, the authorization will also apply to `http://www.example.com/test`.  
*Required*: Conditional. Can be specified only if the `type` property is set to `basic`.  
*Type*: List of String values

`username`  <a name="cfn-cloudformation-authentication-username"></a>
Specifies the user name for basic authentication.  
*Required*: Conditional. Can be specified only if the type property is set to `basic`.  
*Type*: String

`roleName`  <a name="cfn-cloudformation-authentication-rolename"></a>
Describes the role for role-based authentication.  
This role must be contained within the instance profile that's attached to the EC2 instance. An instance profile can only contain one IAM role.
*Required*: Conditional. Can be specified only if the `type` property is set to `S3`.  
*Type*: String.

## Examples
<a name="aws-resource-authentication-examples"></a>

**Topics**
+ [EC2 web server authentication](#aws-resource-cloudformation-authentication-example1)
+ [Specifying both basic and S3 authentication](#aws-resource-cloudformation-authentication-example2)
+ [IAM roles](#aws-resource-cloudformation-authentication-example3)

### EC2 web server authentication
<a name="aws-resource-cloudformation-authentication-example1"></a>

This template snippet shows how to get a file from a private S3 bucket within an EC2 instance. The credentials used for authentication are defined in the `AWS::CloudFormation::Authentication` metadata, and referenced by the `AWS::CloudFormation::Init` metadata in the *files* section.

#### JSON
<a name="aws-resource-cloudformation-authentication-example1.json"></a>

```
"WebServer": {
   "Type": "AWS::EC2::Instance",
   "DependsOn" : "BucketPolicy",
   "Metadata" : {
      "AWS::CloudFormation::Init" : {
         "config" : {
            "packages" : { "yum" : { "httpd" : [] } },
            "files" : {
               "/var/www/html/index.html" : {
                  "source" : {
                     "Fn::Join" : [
                        "", [ "http://s3.amazonaws.com/", { "Ref" : "BucketName" }, "/index.html" ]
                     ]
                  },
                  "mode"   : "000400",
                  "owner"  : "apache",
                  "group"  : "apache",
                  "authentication" : "S3AccessCreds"
               }
            },
            "services" : {
               "sysvinit" : {
                  "httpd" : { "enabled" : "true", "ensureRunning" : "true" }
               }
            }
         }
      },
      "AWS::CloudFormation::Authentication" : {
         "S3AccessCreds" : {
            "type" : "S3",
            "accessKeyId" : { "Ref" : "AccessKeyID" },
            "secretKey" : { "Ref" : "SecretAccessKey" }
         }
      }
   },
   "Properties": {
   EC2 Resource Properties ...
   }
}
```

#### YAML
<a name="aws-resource-cloudformation-authentication-example1.yaml"></a>

```
WebServer: 
  Type: AWS::EC2::Instance
  DependsOn: BucketPolicy
  Metadata: 
    AWS::CloudFormation::Init: 
      config: 
        packages: 
          yum: 
            httpd: []
        files: 
          /var/www/html/index.html: 
            source: !Join
              - ''
              - - 'http://s3.amazonaws.com/'
                - !Ref BucketName
                - '/index.html'
            mode: '000400'
            owner: apache
            group: apache
            authentication: S3AccessCreds
        services: 
          sysvinit: 
            httpd: 
              enabled: 'true'
              ensureRunning: 'true'
    AWS::CloudFormation::Authentication: 
      S3AccessCreds: 
        type: S3
        accessKeyId: !Ref AccessKeyID
        secretKey: !Ref SecretAccessKey
  Properties: 
  EC2 Resource Properties ...
```

### Specifying both basic and S3 authentication
<a name="aws-resource-cloudformation-authentication-example2"></a>

The following example template snippet includes both *basic* and *S3* authentication types.

#### JSON
<a name="aws-resource-cloudformation-authentication-example2.json"></a>

```
"AWS::CloudFormation::Authentication" : {
   "testBasic" : {
      "type" : "basic",
      "username" : { "Ref" : "UserName" },
      "password" : { "Ref" : "Password" },
      "uris" : [ "example.com/test" ]
   },
   "testS3" : {
      "type" : "S3",
      "accessKeyId" : { "Ref" : "AccessKeyID" },
      "secretKey" : { "Ref" : "SecretAccessKey" },
      "buckets" : [{ "Fn::Sub": "${BucketName}" }]
   }
}
```

#### YAML
<a name="aws-resource-cloudformation-authentication-example2.yaml"></a>

```
AWS::CloudFormation::Authentication: 
  testBasic: 
    type: basic
    username: !Ref UserName
    password: !Ref Password
    uris: 
      - 'example.com/test'
  testS3: 
    type: S3
    accessKeyId: !Ref AccessKeyID
    secretKey: !Ref SecretAccessKey
    buckets: 
      - !Sub ${BucketName}
```

### IAM roles
<a name="aws-resource-cloudformation-authentication-example3"></a>

The following example shows how to use IAM roles:
+ `myRole` is an [AWS::IAM::Role](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-iam-role.html) resource.
+ The Amazon EC2 instance that runs `cfn-init` is associated with `myRole` through an instance profile.
+ The example specifies the authentication by using the `buckets` property, like in Amazon S3 authentication. You can also specify authentication by name.

#### JSON
<a name="aws-resource-cloudformation-authentication-example3.json"></a>

```
"AWS::CloudFormation::Authentication": {
    "rolebased" : {
        "type": "S3",
        "buckets": [{ "Fn::Sub": "${BucketName}" }],
        "roleName": { "Ref": "myRole" }
    }
}
```

#### YAML
<a name="aws-resource-cloudformation-authentication-example3.yaml"></a>

```
AWS::CloudFormation::Authentication:
  rolebased:
    type: S3
    buckets:
      - !Sub ${BucketName}
    roleName: !Ref myRole
```