Client security measures, good practices for a secure integration of Orange APIs

This document presents a list of important security measures that need to be taken into account when implementing clients that integrate Orange APIs.

Please note all resources need authorization. OAuth v2 framework (see RFC 6749) has been used in order to authenticate all calls.

See this article for a complete description of our integration of OAuth v2 framework.

Usage of Orange APIs by mobile apps is not covered in this technical guide. Nevertheless see OWASP Mobile Security Project – Top Ten Mobile Risks to have a clear understanding of vulnerabilities, threats, impacts and countermeasures related to this usage of third party APIs.

## Store secrets securely

### Client ID
The client ID is considered public, and there are no requirements on how to store it.

### Client secret
You will get a client secret issued by the authorization server to be used to authenticate your app to the authorization server. The client secret must be stored in a way that it is not available for third parties.

### Authorization code
This is a short-lived provisional token with one-time usage restriction for fetching other tokens. The authorization code should not be stored at all, but rather exchanged for access/refresh tokens as soon as the app gets hold of it.

### Access/refresh token
The access token must be stored securely. However, since it is short-lived, it may be kept only in memory. As an example, none of these tokens should be stored in cookies.

## Encrypt all communication to and from clients

Encryption must be done e.g. using HTTPS. Orange APIs only allows use of HTTPS with TLS 1.2 for requests towards its authorization server and resource servers. TLS 1.0 and 1.1 has been deprecated by IETF due to security vulnerabilities (see What is TLS). Service providers need to make sure that all other communication to and from the clients, e.g. with service-specific resource servers, is encrypted appropriately.

## Handle personal data responsibly

See our Orange Apis General Terms and any Specific Terms for the APIs you are using to ensure you deal with personal data of your clients appropriately (especially if these sensitive data have been provided by our services).

## Protect client callback endpoints against CSRF attacks

The recommended way to avoid cross-site request forgery (CSRF) attacks is to supply a cryptographically random value in the state parameter for the authorization request and verify it for the response in the client callback endpoint. Please see section 10.12 in the OAuth specification (RFC 6749) for details. Note that no confidential data should be passed in the state parameter.

## Go further?

RFC 6819 must be read in order to have a complete view on the threat model of OAuth v2 framework.