# SecretStringGenerator

Configuration to generate secrets such as passwords automatically.

- Source: [`aws-secretsmanager/lib/secret.ts`](https://github.com/aws/aws-cdk/blob/v2.278.0/packages/aws-cdk-lib/aws-secretsmanager/lib/secret.ts#L973)

## Example

TypeScript:

```ts
declare const vpc: ec2.IVpc;

const instance1 = new rds.DatabaseInstance(this, "PostgresInstance1", {
  engine: rds.DatabaseInstanceEngine.POSTGRES,
  // Generate the secret with admin username `postgres` and random password
  credentials: rds.Credentials.fromGeneratedSecret('postgres'),
  vpc
});
// Templated secret with username and password fields
const templatedSecret = new secretsmanager.Secret(this, 'TemplatedSecret', {
  generateSecretString: {
    secretStringTemplate: JSON.stringify({ username: 'postgres' }),
    generateStringKey: 'password',
    excludeCharacters: '/@"',
  },
});
// Using the templated secret as credentials
const instance2 = new rds.DatabaseInstance(this, "PostgresInstance2", {
  engine: rds.DatabaseInstanceEngine.POSTGRES,
  credentials: {
    username: templatedSecret.secretValueFromJson('username').toString(),
    password: templatedSecret.secretValueFromJson('password')
  },
  vpc
});
```

Python:

```python
# vpc: ec2.IVpc

instance1 = rds.DatabaseInstance(self, "PostgresInstance1",
    engine=rds.DatabaseInstanceEngine.POSTGRES,
    # Generate the secret with admin username `postgres` and random password
    credentials=rds.Credentials.from_generated_secret("postgres"),
    vpc=vpc
)
# Templated secret with username and password fields
templated_secret = secretsmanager.Secret(self, "TemplatedSecret",
    generate_secret_string=secretsmanager.SecretStringGenerator(
        secret_string_template=JSON.stringify({"username": "postgres"}),
        generate_string_key="password",
        exclude_characters="/@\""
    )
)
# Using the templated secret as credentials
instance2 = rds.DatabaseInstance(self, "PostgresInstance2",
    engine=rds.DatabaseInstanceEngine.POSTGRES,
    credentials={
        "username": templated_secret.secret_value_from_json("username").to_string(),
        "password": templated_secret.secret_value_from_json("password")
    },
    vpc=vpc
)
```

Java:

```java
IVpc vpc;

DatabaseInstance instance1 = DatabaseInstance.Builder.create(this, "PostgresInstance1")
        .engine(DatabaseInstanceEngine.POSTGRES)
        // Generate the secret with admin username `postgres` and random password
        .credentials(Credentials.fromGeneratedSecret("postgres"))
        .vpc(vpc)
        .build();
// Templated secret with username and password fields
Secret templatedSecret = Secret.Builder.create(this, "TemplatedSecret")
        .generateSecretString(SecretStringGenerator.builder()
                .secretStringTemplate(JSON.stringify(Map.of("username", "postgres")))
                .generateStringKey("password")
                .excludeCharacters("/@\"")
                .build())
        .build();
// Using the templated secret as credentials
DatabaseInstance instance2 = DatabaseInstance.Builder.create(this, "PostgresInstance2")
        .engine(DatabaseInstanceEngine.POSTGRES)
        .credentials(Map.of(
                "username", templatedSecret.secretValueFromJson("username").toString(),
                "password", templatedSecret.secretValueFromJson("password")))
        .vpc(vpc)
        .build();
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
IVpc vpc;

var instance1 = new DatabaseInstance(this, "PostgresInstance1", new DatabaseInstanceProps {
    Engine = DatabaseInstanceEngine.POSTGRES,
    // Generate the secret with admin username `postgres` and random password
    Credentials = Credentials.FromGeneratedSecret("postgres"),
    Vpc = vpc
});
// Templated secret with username and password fields
var templatedSecret = new Secret(this, "TemplatedSecret", new SecretProps {
    GenerateSecretString = new SecretStringGenerator {
        SecretStringTemplate = JSON.Stringify(new Dictionary<string, string> { { "username", "postgres" } }),
        GenerateStringKey = "password",
        ExcludeCharacters = "/@\""
    }
});
// Using the templated secret as credentials
var instance2 = new DatabaseInstance(this, "PostgresInstance2", new DatabaseInstanceProps {
    Engine = DatabaseInstanceEngine.POSTGRES,
    Credentials = new Dictionary<string, object> {
        { "username", templatedSecret.SecretValueFromJson("username").ToString() },
        { "password", templatedSecret.SecretValueFromJson("password") }
    },
    Vpc = vpc
});
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
var vpc IVpc

instance1 := rds.NewDatabaseInstance(this, jsii.String("PostgresInstance1"), &DatabaseInstanceProps{
	Engine: rds.DatabaseInstanceEngine_POSTGRES(),
	// Generate the secret with admin username `postgres` and random password
	Credentials: rds.Credentials_FromGeneratedSecret(jsii.String("postgres")),
	Vpc: Vpc,
})
// Templated secret with username and password fields
templatedSecret := secretsmanager.NewSecret(this, jsii.String("TemplatedSecret"), &SecretProps{
	GenerateSecretString: &SecretStringGenerator{
		SecretStringTemplate: jSON.stringify(map[string]*string{
			"username": jsii.String("postgres"),
		}),
		GenerateStringKey: jsii.String("password"),
		ExcludeCharacters: jsii.String("/@\""),
	},
})
// Using the templated secret as credentials
instance2 := rds.NewDatabaseInstance(this, jsii.String("PostgresInstance2"), &DatabaseInstanceProps{
	Engine: rds.DatabaseInstanceEngine_POSTGRES(),
	Credentials: map[string]interface{}{
		"username": templatedSecret.secretValueFromJson(jsii.String("username")).toString(),
		"password": templatedSecret.secretValueFromJson(jsii.String("password")),
	},
	Vpc: Vpc,
})
```

## Properties

- `excludeCharacters`: string — A string that includes characters that shouldn't be included in the generated password.

  **Default:** no exclusions

  The string can be a minimum
  of ``0`` and a maximum of ``4096`` characters long.

- `excludeLowercase`: boolean = false — Specifies that the generated password shouldn't include lowercase letters.

- `excludeNumbers`: boolean = false — Specifies that the generated password shouldn't include digits.

- `excludePunctuation`: boolean = false — Specifies that the generated password shouldn't include punctuation characters.

- `excludeUppercase`: boolean = false — Specifies that the generated password shouldn't include uppercase letters.

- `generateStringKey`: string — The JSON key name that's used to add the generated password to the JSON structure specified by the ``secretStringTemplate`` parameter.

  If you specify ``generateStringKey`` then ``secretStringTemplate``
  must be also be specified.

- `includeSpace`: boolean = false — Specifies that the generated password can include the space character.

- `passwordLength`: number = 32 — The desired length of the generated password.

- `requireEachIncludedType`: boolean = true — Specifies whether the generated password must include at least one of every allowed character type.

- `secretStringTemplate`: string — A properly structured JSON string that the generated password can be added to.

  The ``generateStringKey`` is
  combined with the generated random string and inserted into the JSON structure that's specified by this parameter.
  The merged JSON string is returned as the completed SecretString of the secret. If you specify ``secretStringTemplate``
  then ``generateStringKey`` must be also be specified.
