Credential Rotation¶
It’s good practice to rotate all credentials regularly:
- OAuth service user passwords should be rotated frequently, e.g. every two hours.
- OAuth client credentials (client ID and secret for confidential clients) might be rotated every month.
The Provider allows rotating both user and client credentials via its /raw-sync/
REST API.
Service Users¶
To rotate an application’s user credentials, do:
- Add a new password by sending a POST request to
/raw-sync/users/{realm}/{id}/password
. - Distribute the new password (e.g. via a S3 Mint Bucket).
- Wait at least 10 minutes to give the application time to pick up the new password. Both old and new password will be active during this grace period.
- Commit the new password by overwriting the user’s passwords via a PATCH request to
/raw-sync/users/{realm}/{id}
.
Clients¶
OAuth client credentials can be rotated by creating a new client and deactivating or deleting the old one:
- Create a new client by sending a PUT request to
/raw-sync/clients/{realm}/{id}
(see below). - Distribute the new client credentials (e.g. via a S3 Mint Bucket).
- Wait at least 10 minutes to give the application time to pick up the new client credentials. Both old and new client will be active during this grace period.
- Reset the old client’s secret to some random string or delete the old client completely.
Example REST call to create a new client in the /services
realm using HTTPie:
$ SECRET_HASH=$(python3 -c "import bcrypt; print(bcrypt.hashpw(b'test', bcrypt.gensalt(4)).decode('ascii'))")
$ TOK='mytoken' # valid OAuth token
$ http PUT https://planb-provider.example.org/raw-sync/clients/services/myclient-123 \
is_confidential:=true \
name='Example Client'\
secret_hash=$SECRET_HASH \
"Authorization:Bearer $TOK"