Do's and don'ts

Helpful do's and don'ts for your implementation.

Do's

• Even if you do not use OAuth2 to retrieve user data, you SHOULD call the access token endpoint to validate that the authorization code was generated by DocCheck. You SHOULD reject users if the response returns “invalid token”.
• Use the state parameter to pass a unique value through the process. While it could be forged with effort, it prevents typical issues where a link is shared. If you use an encrypted timestamp to reject calls to the same URL at a later point, you further reduce the risk of link sharing.
• When calling an OAuth endpoint, you MUST handle documented error responses. Your login process SHOULD NOT fail silently or uncontrollably when, for example, an access token has expired or been revoked. You SHOULD show an error page and escalate the issue within your IT systems.

Don'ts

• Access tokens or other sensitive information MUST NOT be stored in a cookie. Keep in mind that an access token is all that is needed to access user data.
• You SHOULD NOT verify whether a user came via DocCheck using referrer checks. Referrers are fully under user control, can be forged, are often unreliable, and DocCheck server domains/IPs can change without notice.
• Do NOT rely on anything that is not explicitly documented in this documentation. The presence or absence of URL parameters MUST NOT be used to decide whether a user is accepted or rejected.
• The presence of undocumented or additional parameters MUST NOT break your login process. For example, if you call the user data endpoint and receive more parameters than expected, this MUST NOT result in an error. Such parameters SHOULD be ignored.

Info

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.