> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/privileged-access-manager/universal-secrets-sync/discovery-basics.md).
# Universal Secrets Sync Basics
This page covers prerequisites, enforcement policy, and PAM Configuration setup for USS across AWS, Azure, and Google Cloud. If you are migrating existing cloud secrets into Keeper first, see the [Migration Guide](/keeperpam/privileged-access-manager/universal-secrets-sync/universal-secrets-sync-migration-guide.md).
### **Prerequisites**
Prior to using USS, make sure to have the following:
* An active KeeperPAM license
* A Keeper Gateway installed and registered in your network — [Gateway setup guide](/keeperpam/privileged-access-manager/getting-started/gateways.md)
* A Keeper Secrets Manager application associated with the Gateway
* A PAM Configuration for your target cloud infrastructure (AWS, Azure, GCP) where secrets will be synced to
### **USS Enforcement Policy**
On the Admin Console, enable “Can configure universal secrets sync settings” enforcement policy to allow a user to configure universal secrets sync:
### **PAM Configuration**
A [PAM Configuration](/keeperpam/privileged-access-manager/getting-started/pam-configuration.md) must be set up for your target cloud infrastructure before USS can be used. The PAM Configuration tells the USS process where to persist secrets. The USS configuration process is:
* On a PAM Configuration, enable Universal Secrets Sync feature.
* Select one or more shared folders to link to the PAM Configuration. All the Keeper records from the selected folders will be synced.
* Specify a Sync Identity that Keeper Gateway can use to sync records to the cloud secrets storage. The Sync Identity should have read/write access to the secrets manager service in your cloud environment. If left unspecified, the Gateway will use the access keys specified in the PAM Configuration.
* If you want to allow users to preview the secrets before they are synced to the cloud, check the Dry-run option. If unchecked, USS automatically syncs Keeper record changes to the corresponding cloud secrets store.
### **AWS Secrets Manager Sync**
AWS secrets sync uses the AWS Role Policies granted to the Keeper Gateway to persist secrets. The PAM Configuration filters against the provided region names to explicitly specify which regions are used for secret persistence. Please refer to our [AWS Environment](/keeperpam/privileged-access-manager/getting-started/pam-configuration.md#aws-environment) documentation for the PAM Configuration data required for a successful sync.
PAM Configuration for Universal Secrets Sync
The Gateway's instance role must be permitted to assume the Sync Identity role. Add the following trust policy to the Sync Identity role, replacing the Principal ARN with the ARN of the Gateway's instance role:
```
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/gateway-instance-role"
},
"Action": "sts:AssumeRole"
}
```
The Sync Identity role (or the Gateway instance role if no Sync Identity is configured) must have the following permissions on AWS Secrets Manager:
```
{
"Effect": "Allow",
"Action": [
"secretsmanager:CreateSecret",
"secretsmanager:PutSecretValue",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"secretsmanager:RestoreSecret",
"secretsmanager:DeleteSecret",
"secretsmanager:TagResource"
],
"Resource": "*"
}
```
***
### **Azure Key Vault Secrets Sync**
Azure secrets sync uses the permissions granted to the role assigned to the Keeper Gateway to persist secrets in Azure Key Vault. Please refer to our [Azure Environment](/keeperpam/privileged-access-manager/getting-started/pam-configuration.md#azure-environment) documentation for the PAM Configuration data required for a successful sync.
Specify name of the Key Vault to sync secrets to. This vault gets created on the first sync if it doesn’t exist already.
{% hint style="info" %}
The gateway must be running on Azure infrastructure (VM, AKS, Azure Functions, etc.) with the specified user-assigned managed identity assigned to it. This mechanism does not work for on-premises gateways.
{% endhint %}
The Sync Identity for Azure is a user-assigned managed identity. Set the **Sync Identity** field in the PAM Configuration to the client ID (UUID) of the managed identity, for example:
```
a1b2c3d4-e5f6-7890-abcd-ef1234567890
```
Step 1 — Create the managed identity
Create a user-assigned managed identity in the Azure Portal or CLI:
```
az identity create --name keeper-uss-sync --resource-group my-rg
```
Step 2 — Assign the identity to the Gateway
Assign the managed identity to the VM or other resource running the Keeper Gateway:
```
az vm identity assign \
--name my-gateway-vm --resource-group my-rg \
--identities /subscriptions/SUB/resourceGroups/my-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/keeper-uss-sync
```
Step 3 — Grant Key Vault access
Grant the managed identity the necessary permissions on the target Key Vault:
```
az keyvault set-policy --name my-vault \
--object-id \
--secret-permissions get set list delete
```
Step 4 — Retrieve the client ID
Set the **Sync Identity** field in the PAM Configuration to the managed identity's client ID. Run the following to retrieve it:
```
az identity show --name keeper-uss-sync --resource-group my-rg \
--query clientId --output tsv
```
Use the returned UUID as the Sync Identity value — note this is the **client ID**, not the object ID.
***
### **Google Cloud Secrets Sync**
GCP secrets sync uses the Google Role Policies granted to the Keeper Gateway to persist secrets. Please refer to our [Google Cloud Environment](/keeperpam/privileged-access-manager/getting-started/pam-configuration.md#google-cloud-environment) documentation for the PAM Configuration data required for a successful sync.
The Sync Identity for GCP uses service account impersonation. The Gateway's service account (defined by the `service_account_key` in the PAM Configuration) impersonates the target service account for all Secret Manager calls. Set the **Sync Identity** field to the email address of the target service account, for example:
```
keeper-uss-sync@my-project.iam.gserviceaccount.com
```
Step 1 — Grant the Gateway service account the Token Creator role
This allows the Gateway's service account to impersonate the target service account:
```
gcloud iam service-accounts add-iam-policy-binding \
keeper-uss-sync@my-project.iam.gserviceaccount.com \
--member="serviceAccount:gateway-sa@my-project.iam.gserviceaccount.com" \
--role="roles/iam.serviceAccountTokenCreator"
```
Step 2 — Grant the target service account access to Secret Manager
Grant the target service account the necessary permissions on the project where secrets will be synced:
```
gcloud projects add-iam-policy-binding my-project \
--member="serviceAccount:keeper-uss-sync@my-project.iam.gserviceaccount.com" \
--role="roles/secretmanager.admin"
```
***
### **Universal Secrets Sync Workflow**
The basic workflow for running sync operations is:
* (optional) Perform a [one-time import](/keeperpam/privileged-access-manager/universal-secrets-sync/universal-secrets-sync-migration-guide.md) of existing secrets from AWS and/or Azure and/or GCP via Commander.
* Set up a Keeper Gateway with associated permissions to manage secret resources.
* Set up a PAM Configuration with the Gateway and the required USS settings.
* If "Dry run" is not selected, the sync jobs will execute automatically--workflow is done.
* If "Dry run" is selected, manually execute the sync via the [Commander CLI](/keeperpam/privileged-access-manager/universal-secrets-sync/discovery-using-commander.md) or the [Vault UI](/keeperpam/privileged-access-manager/universal-secrets-sync/discovery-using-the-vault.md).
### **Related pages:**
* [USS Overview](/keeperpam/privileged-access-manager/universal-secrets-sync.md#pdf-page-dqtjnnk6pra4mfdizdco-what-is-keeper-discovery) - Feature summary, architecture, and key capabilities
* [Migration Guide](/keeperpam/privileged-access-manager/universal-secrets-sync/universal-secrets-sync-migration-guide.md) - Import existing cloud secrets and configure USS in one workflow
* [Using Commander](/keeperpam/privileged-access-manager/universal-secrets-sync/discovery-using-commander.md) - CLI reference and dry-run workflow
* [Using the Vault](/keeperpam/privileged-access-manager/universal-secrets-sync/discovery-using-the-vault.md) - Step-by-step Vault UI walkthrough
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.keeper.io/keeperpam/privileged-access-manager/universal-secrets-sync/discovery-basics.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.