To enhance security and simplify credential management, PlainID supports referencing secrets for authentication when configuring PIP Data Sources. Instead of embedding sensitive values directly in configuration files, you can store them in a supported Secret Store and reference them securely. This approach supports automated secret rotation and reduces the risk of credential exposure.
REST-based PIP Data Sources support two different authentication usage patterns, both of which rely on the same Secrets Management mechanism:
- Secrets used in OAuth configurations, such as Client Credentials authentication.
- Secrets used in fixed REST headers, for example when authenticating with an API key instead of OAuth.
The following sections describe each usage pattern and explain how secret management enables seamless updates without service interruption.
Using Secret Annotations in OAuth Configuration
When a REST PIP Data Source uses OAuth authentication, you can reference a secret from a Secret Store directly in the OAuth XML configuration. This is commonly used for sensitive values such as the client-secret.
The following example demonstrates how to reference a secret for the client-secret module option:
<application-policy name="ps-auth2-massive">
<authentication>
<login-module code="com.plainid.pip.auth.oauth.clientcredential.OAuth20ClientCredentialLoginModule" flag="required">
<module-option name="access-token-uri">
https://login.microsoftonline.com/cd6168ed-fe82-4528-b2eb-4e030d322878/oauth2/v2.0/token
</module-option>
<module-option name="client-id">
19f4ef6c-d0dd-42f0-844c-b529b609a171
</module-option>
<module-option name="client-secret">
{{ printf "{{store=AWS_SECRETS_MANAGER_STORE,key=path1/path2/key}}" }}
</module-option>
<module-option name="scope">
https://graph.microsoft.com/.default
</module-option>
</login-module>
</authentication>
</application-policy>
In this model, the OAuth flow retrieves access tokens dynamically, while the underlying secret is securely resolved from the Secret Store at runtime.
Secret Management and Rotation
OAuth Client Credentials configurations use a secret stored in Secrets Management for token retrieval. Secrets typically have a longer lifespan than access tokens, and integration with a Secret Store enables seamless rotation without downtime.
When rotating a secret, both the old and new values can coexist temporarily. This allows for graceful secret transitions, ensuring uninterrupted service while credentials are updated. The system automatically resolves the latest valid secret at runtime.
Note: The secrets-mgmt Redis password does not currently support secret rotation or replacement.
Using Secrets in REST Headers for API Key Authentication
In addition to OAuth-based authentication, REST PIP Data Sources may authenticate using fixed HTTP headers, such as an API key. In this scenario, secrets are referenced directly in the REST Translator configuration rather than in an OAuth login module.
For example, instead of using OAuth, a REST service may require an Authorization or X-API-Key header. The header value can reference a secret stored in the Secret Store using standard Secrets Management annotations.
This approach is functionally equivalent to OAuth secret usage in terms of security and lifecycle management, but it applies to REST header values rather than token retrieval.
Secret Management in REST-Based PIP Data Sources
REST-based PIP Data Sources use the same Secrets Management mechanism described in this section, regardless of whether authentication is performed using OAuth or fixed headers.
Secrets can be referenced in REST configurations such as authentication headers using standard Secrets Management annotations. Secret resolution, caching, rotation, masking, and error handling for REST integrations are handled by the REST Translator and follow the same behavior defined across the Authorization Platform.
For configuration details and examples, see
Secrets Management for REST Headers.