# SailPoint AWS Secrets Manager Credential Provider Documentation > AWS Secrets Manager Credential Provider Documentation # Documentation # Adding a New Credential Provider in SailPoint Create a new credential provider integration in SailPoint to automatically rotate refreshed authentication credentials for configured sources. To create a new credential provider: 1. Go to **Admin \> Connections \> Credential Providers**. 2. Select **Create New**. > **Screenshot** > > [![Credential Providers landing page with the Create New button highlighted]()]() 3. Search for the credential provider type and select **Configure**. > **Note** > > For a list of the available types of credential providers, as well as access to the documentation for each type, refer to the [Identity Security Connectors]() landing page. 4. Enter the following in the provided fields: - Enter a unique **Credential Provider Name** to help administrators differentiate it from others. - Enter a **Credential Provider Description**. - Select a **Credential Provider Owner** who is responsible for the credential provider's operations. - Select a **Virtual Appliance Cluster** with connectivity to the credential provider. 5. Select **Continue** to create the new credential provider with your selections. 6. (Optional) Enable credential caching. For more information, refer to [Caching Credentials](). # Configure a Source to Use a Credential Provider After you create a credential provider, you can begin configuring your sources to use it for authentication. When you use a credential provider in a source configuration, any authentication fields you need to configure allow you to use the credential provider or use static authentication credentials. To configure your source to use a credential provider: 1. In the source's **Base Configuration** tab, select **Use a Credential Provider**. > **Note** > > Enabling a credential provider in your connector adds an additional 30-second timeout for each connector operation. 2. Toggle every secret field in the configuration pages which should use the credential provider to **Credential Path**. The field changes to accept the secret path expression for the credential provider instead of the static value. > **Screenshot** > > **Static Value** > > [![Static Value field selected]()]() > > **Credential Path** > > [![Credential Path field selected]()]() 3. Enter the secret path expression for the credential provider into the **Credential Path** field. > [!NOTE] > > For a list of all available SailPoint credential provider path expressions, refer to [Credential Provider Secret Path Expressions](). # Configuring AWS Secrets Manager ## Base Configuration Provide the base configuration parameters. Information you entered during the initial creation of the credential provider is automatically entered into the fields in the **Base Configuration** page. You can edit this information if necessary. > [!NOTE] > > **Screenshot** > > [![Base Configuration]()]() > [!NOTE] > > Ensure that the name and description of each credential provider is unique. 1. Go to **Admin \> Connections \> Credential Providers**. 2. Search for the credential provider you want to edit. 3. Enter a unique **Credential Provider Name**. 4. Enter a **Credential Provider Description** that provides details necessary to distinguish it from similar credential providers. 5. Select a **Credential Provider Owner** by typing the owner's name into the field provided. Matches display after you type at least two letters. Select the credential provider owner as required. 6. Select a **Virtual Appliance Cluster** with connectivity to the credential provider. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](). 7. Select **Save**. ## Authentication Settings Configure your authentication method. There are two ways to authenticate: ### IAM User > [!NOTE] > > **Screenshot** > > [![IAM User]()]() 1. Enter the **Access Key ID** for the service account. 2. Enter the **Secret Access Key** to authenticate the service account. 3. Enter the **Role's Amazon Resource Name**. 4. Enter the **Role's Session Name** used to log in to the AWS account. 5. Enter the **Role Session Duration in Seconds**. You can set this from 900 to 43,200 seconds. The default is 900 seconds. 6. Enter the **AWS Secret Manager Region** name for the AWS Secret Manager. ### IAM Role > [!NOTE] > > IAM Role requires a virtual appliance on the AWS EC2 instance. > [!NOTE] > > **Screenshot** > > [![IAM Role]()]() 1. Enter the **AWS Secret Manager Region** name for the AWS Secret Manager. 2. (Optional) Enable credential caching. For more information, refer to [Caching Credentials](). 3. Select **Save**. ## Retry Configuration The AWS Secrets Manager credential provider comes with the following default retry mechanism: - **No. of retries**: Defines the number of retries when encountered with an error like timeout. The default value is 2. - **Base Delay (Milliseconds)**: Defines the interval after which a retry attempt must be made. The base delay exponentially increases after every retry attempt. For example, if the default base delay is 10 seconds, subsequent retry attempts will be 20 seconds, then 40 seconds, and so on. The default value is 500 ms. - **Throttled Base Delay (Milliseconds)**: Defines the interval to wait before retrying after the first retry attempt. This value automatically increases exponentially with each failed attempt. The default value is 1000 ms. - **Maximum Backoff Time (Milliseconds)**: After the delay reaches this maximum limit, the time between retries stops increasing. The default is 2000 ms. If you need to override this configuration, add the attributes you need to the application XML using the SailPoint REST APIs. | Configuration Field | Attribute | Unit | | --- | --- | --- | | Number of retries | `maxRetries` | Whole number | | Base Delay | `baseDelay` | Milliseconds | | Throttled Base Delay | `throttledBaseDelay` | Milliseconds | | Maximum Backoff Time | `maxBackoffTime` | Milliseconds | > [!NOTE] > > Increasing the values for any of the above fields may trigger a timeout exception for the connector. # Caching Credentials SailPoint credential providers can save the credentials it receives from the systems they manage to cache. Cached credentials may expire after a period of time and need to be refreshed. Credential providers can't use expired credentials saved to cache. > [!NOTE] > > **Screenshot** > > [![Enable Credentials Caching checkbox]()]() To enable credential caching for credential providers: 1. Sign in to SailPoint. 2. Go to **Admin \> Connections \> Credential Providers**. 3. Search for the credential provider that you want to enable caching on and select its name. 4. Select **Edit Configuration**. 5. Select the **Enable Credentials Caching** checkbox. > **Note** > > The option to enable this feature may be in a different configuration tab depending on your selected credential provider. 6. Select **Save**. ## Credentials Expiration Depending on the managed system the credential provider is connected to, the credentials may have an expiration time limit. The credential provider uses the following hierarchy to determine expiration, with the highest priority first and the lowest priority last: 1. If the credentials received from the managed system contain an expiration time, then they are cached until that expiration time. 2. If the credentials received from the managed system don't contain an expiration time, then you can add one by configuring the `expirationTimeInSeconds` attribute in the source of credential provider using APIs. > **Note** > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. 3. If the credentials received from the managed system don't contain an expiration time and you don't create one via APIs, then by default the credentials expire after one day. # AWS Secrets Manager Credential Provider The SailPoint AWS Secrets Manager Credential Provider provides credential cycling functionality to fetch credentials from AWS Secrets Manager to authenticate sources in SailPoint. This credential provider fetches the latest credentials for the connectors to transact with source systems for identity security operations in SailPoint. For information on creating a new AWS Secrets Manager credential provider, refer to [Adding a New Credential Provider in SailPoint](). ## Prerequisites Before you configure your credential provider, you must consider the following prerequisite items. - For VA-based Deep Governance connectors, the source and credential provider virtual appliances must be in the same cluster. - VA-based Deep Governance connectors, SaaS-based Deep Governance, Discovery, and Quick Compliance connectors now support the use of credential providers. Secrets Manager uses [AWS Identity and Access Management (IAM)]() to secure access to secrets. IAM provides authentication and access control. By using IAM permission policies, you control which users or services have access to your secrets. A permissions policy describes who can perform which actions on which resources. You can: - [Attach a permissions policy to an identity]() (IAM User/Role). - [Attach a permissions policy to a secret](). The `GetSecretValue` permission is necessary to retrieve secrets from AWS Secrets Manager. The IMDS hop limit should be set to 2 as shown. If set to 1, the connection fails with a 401 error. ```text aws ec2 --profile dev describe-instances --instance-id i-0c42f9be78225a897 --query 'Reservations[].Instances[].MetadataOptions' [ { "State": "applied", "HttpTokens": "required", "HttpPutResponseHopLimit": 2, "HttpEndpoint": "enabled", "HttpProtocolIpv6": "disabled", "InstanceMetadataTags": "disabled" } ] ``` ### Identity-Based Policy You can attach permissions policies to [IAM identities: users, user groups, and roles](). In an identity-based policy, you can specify which secrets the identity can access and the actions the identity can perform on the secrets. The following is an example of the identity-based policy for the `user` or `role` to access a secret that uses a custom KMS key. ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "statement1", "Effect": "Allow", "Action": ["secretsmanager:GetSecretValue"], "Resource": "*" }, { "Sid": "statement2", "Effect": "Allow", "Action": ["kms:Decrypt"], "Resource": ["arn:aws:kms:us-east-1:441113549707:key/6326462b-0ea3-4ad5-ad2f-32447ec4387a"] } ] } ``` #### Resource-Based Policy In a resource-based policy, you can specify who can access the secret and the actions they can perform on the secret. The following is an example of the resource-based policy for the user or role to access the secret that uses a custom KMS key. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::{AccountID}:role/{RoleName}" }, "Action": "secretsmanager:GetSecretValue", "Resource": "*" } ] } ``` - Principal: Who to grant access to. - Action: What they can do. For more information, refer to [Secrets Manager Actions](). - Resource: Which secrets they can access. For more information, refer to [Secrets Manager Resources](). The wildcard character (\*) has different meanings depending on what you attach the policy to: - In a policy attached to a secret, the wildcard character (\*) means the policy applies to this secret. - In a policy attached to an identity, the wildcard character (\*) means the policy applies to all resources, including secrets, in the account. For more information about resource-based policies for AWS Secrets Manager, refer to [Resource-based Policies](). ## Supported Platforms This credential provider supports the following platforms: - AWS Secrets Manager # AWS Secrets Manager Credential Provider Secret Path Expressions Use the path expressions listed in this topic to use the AWS Secrets Manager credential providers in your source authentication configurations. The AWS Secrets Manager Credential Provider can provide any field supported by AWS Secrets Manager, such as **username** and **password** secrets. ## Username Path syntax: `{Secret ARN}/{secretKey}` For example: **Before Encoding** Using Secret ARN: ```text secrets://aws-vault/arn:aws:secretsmanager:us-east-1:441113549707:secret:orgName/cred/applicationName/directoryName/username ``` > [!IMPORTANT] > > The URL path should always start with the prefix, `secrets://`. Each attribute in the URL path must be URL-encoded. Each URL attribute in the path is case-sensitive. **After Encoding** After you encode the URL path, it should appear as follows: Using Secret ARN: ```text secrets://aws-vault/arn%3Aaws%3Asecretsmanager%3Aus-east-1%3A441113549707%3Asecret%3AorgName%2Fcred%2FapplicationName%2FdirectoryName/username ``` The following is an explanation of the attributes of this URL: - `aws-vault` - Configured Credential Provider in the Credential Provider Section. - `arn:aws:secretsmanager:us-east-1:441113549707:secret:orgName/cred/applicationName/directoryName` - Secret Path ARN. - `username` - Secret Key which needs to be fetched from the AWS Secrets Manager. > [!TIP] > > Use [urlencoder.org]() to encode your URL attributes. ## Password Path syntax: `{Secret ARN}/{secretKey}` For example: **Before Encoding** Using Secret ARN: ```text secrets://aws-vault/arn:aws:secretsmanager:us-east-1:441113549707:secret:orgName/cred/applicationName/directoryName/password ``` > [!IMPORTANT] > > The URL path should always start with the prefix, `secrets://`. Each attribute in the URL path must be URL-encoded. Each URL attribute in the path is case-sensitive. **After Encoding** After you encode the URL path, it should appear as follows: Using Secret ARN: ```text secrets://aws-vault/arn%3Aaws%3Asecretsmanager%3Aus-east-1%3A441113549707%3Asecret%3AorgName%2Fcred%2FapplicationName%2FdirectoryName/password ``` The following is an explanation of the components of this URL: - `aws-vault` - Configured Credential Provider in the Credential Provider Section. - `arn:aws:secretsmanager:us-east-1:441113549707:secret:orgName/cred/applicationName/directoryName` - Secret Path ARN. - `password` - Secret Key which needs to be fetched from the AWS Secrets Manager. > [!TIP] > > Use [urlencoder.org]() to encode your URL attributes. ## Prefixes and Suffixes If any secret paths have a prefix or a suffix, you must append a query parameter to the secret path as follows: - To add a prefix - `?prefix=`. For example, if the secret value returned after evaluation is `LocalAdmin`, but the complete value required by the secret field is `DomainOne\LocalAdmin` then the secret path expression will be as follows to add the required prefix: ```text secrets://aws-vault/arn%3Aaws%3Asecretsmanager%3Aus-east-1%3A441113549707%3Asecret%3AorgName%2Fcred%2FapplicationName%2FdirectoryName/password?prefix=DomainOne%5C ``` - To add a suffix - `?suffix=`. For example, if the secret value returned after evaluation is `localadministrator`, but the complete value required by the secret field is `localadminstrator@sp.com` then the secret path expression will be as follows to add the required suffix: ```text secrets://aws-vault/arn:aws:secretsmanager:us-east-1:441113549707:secret:orgName/cred/applicationName/directoryName/password?suffix=%40sp.com ``` - To add a prefix and suffix - `?prefix=&suffix=`. For example, if the secret value returned after evaluation is `LocalAdmin`, but the complete value required by the secret field is `DomainOne\LocalAdmin@sp.com` then the secret path expression will be as follows to add the required prefix and suffix: ```text secrets://aws-vault/arn:aws:secretsmanager:us-east-1:441113549707:secret:orgName/cred/applicationName/directoryName/password?prefix=DomainOne%5C&suffix=%40sp.com ``` > [!IMPORTANT] > > All input parameters must be encoded. Standard format for credential path: ```text secrets://{vault-name}/{secret ARN}/{secretKey}?prefix=someValue&suffix=someValue2&versionId=123&versionStage=PREVIOUS ``` > [!IMPORTANT] > > Prefix, suffix, versionId, and versionStage are optional. The AWS Secrets Manager has provision to store secrets in two ways: 1. In key value / JSON / map format. 2. Plain text format. > [!NOTE] > > For secrets which are stored in plain text format, there is no need to provide the secret key in the credential path. For example: **Before Encoding** Using Secret ARN: ```text secrets://aws-vault/arn:aws:secretsmanager:us-east-1:441113549707:secret:orgName/cred/applicationName/directoryName ``` > [!IMPORTANT] > > The URL path should always start with the prefix, `secrets://`. Each attribute in the URL path must be URL-encoded. Each URL attribute in the path is case-sensitive. **After Encoding** After you encode the URL path, it should appear as follows: Using Secret ARN: ```text secrets://aws-vault/arn%3Aaws%3Asecretsmanager%3Aus-east-1%3A441113549707%3Asecret%3AorgName%2Fcred%2FapplicationName%2FdirectoryName ``` ### Other Query Parameters - **versionId** - The unique identifier of the version of the secret to retrieve. If you include both this parameter and `versionStage`, the two parameters must refer to the same secret version. If you don't specify both `versionStage` and `versionId`, then Secrets Manager returns the `AWSCURRENT` version. Example: ```text secrets://aws-vault/arn%3Aaws%3Asecretsmanager%3Aus-east-1%3A441113549707%3Asecret%3AorgName%2Fcred%2FapplicationName%2FdirectoryName/password?versionId=123 ``` - **versionStage** - The staging label of the version of the secret to retrieve. Secrets Manager uses staging labels to keep track of different versions during the rotation process. If you include both this parameter and `versionId`, the two parameters must refer to the same secret version. If you don't specify both `versionStage` and `versionId`, Secrets Manager returns the `AWSCURRENT` version. Example: ```text secrets://aws-vault/arn%3Aaws%3Asecretsmanager%3Aus-east-1%3A441113549707%3Asecret%3AorgName%2Fcred%2FapplicationName%2FdirectoryName/password?versionStage=AWSCURRENT ``` - **versionId and versionStage** - If you include both the `versionStage` and `versionId` parameters, the two parameters must refer to the same secret version. If you don't specify both `versionStage` and `versionId`, Secrets Manager returns the `AWSCURRENT` version. Example: ```text secrets://aws-vault/arn%3Aaws%3Asecretsmanager%3Aus-east-1%3A441113549707%3Asecret%3AorgName%2Fcred%2FapplicationName%2FdirectoryName/password?versionId=123&versionStage=AWSCURRENT ```