Rotate credentials
Overview
Where your organization requires service account credentials to be changed on a cycle, every 90 days for example, this page is the place to start. It lists the credentials a CAST Imaging deployment holds, points to the procedure for changing each one, and gives the order to work through them in.
Accounts held in your own directory are out of scope. Where users are imported from LDAP or authenticated through SAML, their credential lifecycle is enforced by your identity provider, not by CAST Imaging or by the authentication system it embeds. Only the accounts below are CAST Imaging’s own.
Platform accounts
These are the accounts a rotation policy usually covers.
| Credential | Where it is held | How to change it | Restart needed |
|---|---|---|---|
CAST Imaging local admin |
The aip-realm of the authentication system |
CAST Imaging local users | None |
kcadmin |
The master realm. Used to sign in to the Keycloak Admin Console |
How do I change the kcadmin password? | None |
Internal service account admin |
The master realm, and the deployment’s own configuration. Used by the Auth Service to reach Keycloak, not for signing in |
Keycloak internal service account | SSO and Authentication |
PostgreSQL operator, postgres, guest |
PostgreSQL, and several CAST Imaging configuration files and database tables | Change a PostgreSQL user password | Most services |
| Neo4j | The imaging-viewer configuration |
Not documented yet - contact CAST Support | - |
| Microsoft Windows service logon account | The Windows Service Control Manager, not any CAST Imaging configuration file | See below | Every CAST Imaging service |
CAST Imaging 3.6.0-funcrel and later ships three distinct authentication system logins, not two: the kcadmin Admin Console account, the internal service account also called admin, and the CAST Imaging local admin user. They are separate credentials and each is rotated differently. Treating them as one has previously produced a Whitelabel error page - see Troubleshooting.
Integration credentials and keys
| Credential | Where it is held | How to change it |
|---|---|---|
| REST API key | Against an individual CAST Imaging user | Generate and use an API key. Generating a new key invalidates the previous one immediately |
| CAST Extend API key | CAST Extend, and in CAST Imaging | CAST Extend settings |
| AI provider keys | Your AI provider, and in CAST Imaging | AI Settings |
| SMTP password | The mail configuration | Email notifications |
| OIDC client secret | Your identity provider, and in the authentication configuration | Configure authentication |
| LDAP bind credentials | Your directory, and in the authentication configuration | LDAP |
| Proxy credentials | CAST Imaging | Proxy settings |
Certificates and keystores
- The keystore and key passwords created when HTTPS is configured - see HTTPS configuration.
- Certificate-based authentication for database connections, which replaces the database password rather than rotating it - see Configuring certificate-based authentication for database connections.
Encrypt a password before storing it
Several passwords can be held in encrypted form rather than in plain text, using the encryption tool shipped in the tools folder of the extracted installer. The procedure is given once, as part of the database password change - see Step 2 - Encrypt the new password.
Recommended order
Where you rotate several credentials in one maintenance window, work from the smallest impact to the largest:
kcadmin- nothing else holds this password, so no restart follows.- CAST Imaging local
admin- changed in the application, so no restart follows. - Internal service account
admin- held in configuration, so the SSO and Authentication services restart. - PostgreSQL - held in the most places and restarts the most services, so it goes last.
Taking them in this order means that if something stops working, only one credential has changed since the deployment was last known to be healthy.
Do not rotate during an update
Never change the PostgreSQL password and update CAST Imaging to a new release in the same maintenance window. The update does not encrypt a new password for you, so it continues to reference the previous value and fails part-way through. Complete the rotation, verify it, and update as a separate exercise afterwards.
This is set out in the update prerequisites - see In-place component update for Microsoft Windows.
Rotate the Microsoft Windows service logon account
Where the CAST Imaging Microsoft Windows services run under a dedicated account rather than LocalSystem, as CAST recommends in Software requirements, that account’s password is held by the Windows Service Control Manager and not by CAST Imaging. It is therefore stored once per service and must be updated for each of them:
- CAST Imaging Authentication
- CAST Imaging Console Service
- CAST Imaging Control Panel
- CAST Imaging Gateway Service
- CAST Imaging SSO Service
- CAST Imaging Analysis Node
- CAST Imaging Dashboards Service, where standalone CAST Dashboards is installed
Change the password at its source first, in Active Directory for a domain account or in Local Users and Groups for a local account. Then update the stored credential for each service, using the Log On tab of its properties in Services (services.msc), and restart it.
A service whose stored password was missed fails to start with a logon error, recorded as event 7000 or 7038 in the Windows System log. The account to use at installation time is set with the XXX_START_AS_USER and XXX_START_AS_PASSWORD variables - see Microsoft Windows installation variables.
Verify a rotation
After each credential, and again at the end of the window:
- Sign in to the component that owns the credential directly, for example to PostgreSQL with the new database password.
- Sign in to CAST Imaging and open an application’s results.
- Run an analysis end to end.
- Where standalone CAST Dashboards is installed, confirm it still loads data.
- On Microsoft Windows, confirm every CAST Imaging service is running.