Scopes

Apply the principle of least privilege when using OAuth scopes. You should only use the scopes necessary for your workload. This can reduce the data that is available to an OAuth Application or Access Token in the event that it becomes compromised.

Storing the Client Secret and tokens

You should treat the client secret and access/refresh tokens as sensitive data, like a password. They should not be disclosed and should be stored securely. The following best practices should be followed:

• Use secret storage services for storing client secrets and tokens. For example AWS provides Secrets Manager, and Azure provides Key Vault.
• If you cannot use a secret storage service, consider encryption instead.
• Use a password manager like 1Password if you need to share the client secret amongst colleagues.
• Don't commit client secrets or access tokens to source control tools like Git.
• Don't share client secrets or access tokens through email, instant messaging or other similar channels.
• Do not send the client secret or tokens over plain text. For example you should use HTTPS instead of HTTP.

Token expiry

Access tokens are valid for 1 hour. This helps to mitigate the risks if a malicious actor manages to obtain an access token; it will be valid for at most 1 hour and new access tokens will require the Client Secret.

The Authorization Code Grant can be coupled with the Refresh Token Grant to allow new access tokens to be obtained without forcing the user through the browser redirect flow.

Validating access tokens

Access tokens issued by the Bipsync API are in the JSON Web Token (JWT) format. These are cryptographically signed tokens that contain claims about the user or application they were issued to.

If you are simply passing the access token to the Bipsync API to authenticate then it's not necessary to validate the token yourself. If however you use the token to extract basic user profile information, like ID or name, then you will need to validate it.

You should use a JWT library for your language/framework to validate the JWT.

It is important to check that the token signature is valid. This ensures that the token has not been tampered with and that it is genuine. We sign all tokens using the RS256 algorithm. This is an asymmetric algorithm which means that we sign the token with a private key and the signature must be verified with a different public key.

We expose the public keys for verifying signatures at https://{client}-api.bipsync.com/v1/oauth/jwks. This uses the JWKS format to return an array of keys. Your JWT library should include support for using JWKS.

We regularly rotate public keys for security reasons. As such the public keys should be fetched dynamically from applications, rather then being hard coded or set via static configuration.