Securely creating users for server-to-server use cases
Users are created via the /v1/signup endpoint. A user will receive an email (= username) and a password by the creating service. For server-to-server use cases, we strongly recommend to use a random hash as email / username instead of a real email address. This will greatly improve security against email dictionary attacks.
When creating the user, your mandator secret is required.
When is a user password assigned
A user password is assigned (by you) when you first signup a user. Note that a server-to-server signup process must provide the clientSecret in order to skip the otherwise mandatory email verification.
How to authenticate a user
User authentication is done either via username and password or via refresh token. Use the /oauth/access_token endpoint with the respective scope to either login-in or exchange a refresh token for an access token.
Note that both, login and token exchange will require your mandator credentials as a second authentication factor, as specified by the oauth standard - see our API documentation for details.
How to change a user’s password
A user may change his password using the current password via the changePassword operation:
https://sandbox.wealthapi.eu/apiDocumentation/swagger#/users/changePassword
This option may only be executed if the user is a) logged-in and b) knows his password.
How to reset a user password
A password can be reset by the users mandator, using mandator credentials. Alternatively, a user with role ROLE_USER_MANAGEMENT may reset a users password. In any case, resetting passwords is limited to users in the scope of the authenticated mandator.
For security reasons, editing users (including resetting the password) with mandator credentials is only possible by specifying the username / email. Note that in the case of server-to-server-users the email / username will typically be a random hash assigned by the creating service.
Resetting via ROLE_USER_MANAGEMENT
To so so, a user account in your organization must have ROLE_USER_MANAGEMENT. This account may then update the user with a new password user the update user endpoint. Again, an update can only be done via specifying the users email / username.
Resetting via mandator credentials
In order to reset a users password, via mandator credentials, you must provide the clientId and clientSecret in the request header using the following header parameters:
X-Mandator-Client-Id X-Mandator-Client-Secret
A request submitted with valid mandator credentials will be able to update the user with a new password user the update user endpoint.
Should I store user passwords?
When storing user credentials, these must always be stored encrypted. Due to the oauth implementation we consider encrypted storage of user credentials as secure.
An alternative to storing user credentials is to just store the refresh token. The refresh token may then be used to acquire a new user token once it expires. Note that the refresh token may also expire based on your mandator settings.
In case you did not store the user credentials and your refresh token expired, you must reset the users password. The process would then be
reset user password using mandator credentials
obtain a new token and refresh token using user credentials
store the new refresh token
Validity of token and refresh_token
The token is valid for 60 minutes.
The refresh_token has by default no restriction on token lifetime. A custom token validity period may be configured on mandator level.
Revoking refresh tokens
We use JWT which is a stateless token by design. The easiest way to revoke a JWT is by deleting it.
For added security, we provide a way to revoke all valid refresh tokens for a certain user. To revoke all valid refresh tokens, use the endpoint
Add Comment