FieldView Security

Climate FieldView relies on multiple layers of security to protect our partners, our shared users, and their data. The primary components of this security are:

  • Communication encryption - Transport Layer Security (TLS) also known as HTTPS.
  • Authentication/authorizationOAuth 2.0 to standardize the authentication process and for verifying access to services and data.
  • Denial of service (DoS/DDoS) protection - Using API keys to ensure availability for all partners.
Communication Encryption

All Climate FieldView APIs are accessed with Secure HTTP (HTTPS). This ensures that all data including usernames, passwords, email addresses, yield data, etc. is protected during transport to and from Climate systems. The latest Transport Layer Security protocol (TLS) 1.2 is used.

Climate also uses OAuth2 as a standard for delegated authorization which requires HTTPS.

Authentication/Authorization

All Climate FieldView APIs use the delegated authorization framework OAuth2. The tokens generated during the OAuth2 process are used throughout Climate services to ensure the partner and user are authorized to access requested resources. This maintains data integrity and protects our shared users’ sensitive data. Of the many authorization frameworks available, OAuth2 was chosen because it is lightweight, it works well with JSON REST APIs, and it was built to support many different types of clients such as web apps, mobile apps, IoT devices, and backend services.

Every call to Climate FieldView APIs requires an access token. Access tokens are generated using an OAuth2 Authorization Grant, typically the authorization_code, client_credentials, or refresh_token grants.

Authorization Code Grant

To generate an access token, your webapp will need to redirect users to the Log in With FieldView page. Once users authenticate on the Climate FieldView site, they will be redirected back to your webapp with a code which you will use to make a backend call to retrieve the required access_token. After which point, you may call Climate FieldView APIs on behalf of the user.

Interactive login is accomplished using this flow:

  1. Log In with FieldView (Authorization Request)
    1. The user arrives at your site and clicks the Log in With FieldView button. Clicking this button navigates the user's browser to the Climate's FieldView login page on climate.com.
    2. The user enters their Climate FieldView username and password and clicks the Log In button.
    3. The user is then prompted to confirm that they wish to allow access to the partner app. This prompt is branded with your logo. The user clicks "Allow".
  2. Redirect back to partner site (Authorization Response)
    1. The user's browser is redirected back to your site.
    2. The URL to which the user is redirected will contain a code parameter used in step 3.
    3. This temporary code is used to generate the initial access token.
  3. Access Token Request & Response
    1. Your application requests an access token and refresh token pair using the code provided in step 2 (plus some other information, see below).
    2. Your application provides the access token on each subsequent call to the API as the means of identifying the user on whose behalf the call is being made and authorizing the resource request.

1. Log In with FieldView (Authorization Request)
When the user clicks the Log in With FieldView button, redirect the user to the following URL (whitespace added for clarity):

https://climate.com/static/app-login/index.html
 ?scope=${scope}
 &page=oidcauthn
 &response_type=code
 &redirect_uri=${redirect_uri}
 &client_id=${client_id}
  • scope: This is the list of scopes that correspond to the endpoints you intend to call after authenticating. This list should be as specific as possible, as the user will be asked to grant permissions for each requested scope. The value must be a space-delimited, url-encoded list (e.g. fields:read+imagery:write). Click the Authorize button on the API documentation page for the scopes that correspond to each resource/endpoint.
  • redirect_uri: The redirect_uri in the above query must be a fully-qualified, url-encoded uri, which exists on your server. After the user authenticates and allows access to the partner app, the redirect_uri callback will receive a single query parameter named code.
  • client_id: This is the OAuth2 client ID provided to you by The Climate Corporation.

2. Redirect back to partner site (Authorization Response)
The redirect_uri specified in the authorization request will receive a single query parameter named code. You will use this code to request an access token from Climate, via a backend web service call. Note that the authorization code expires within approximately one minute.

3. Access Token Request & Response
POST with content type application/x-www-form-urlencoded the following information to https://api.climate.com/api/oauth/token. NOTE that this is NOT a JSON payload.

grant_type=authorization_code&redirect_uri=${redirect_uri}&code=${code}

The redirect_uri parameter must be the same redirect_uri parameter used in the initial redirect. The code is the parameter value received by the callback URI (redirect_uri) in step 2.

Additionally, an Authorization header will need to be sent with the POST. A Climate Corporation employee will need to create an OAuth2 client ID and secret pair for use in your app. The value of the Authorization header must be ‘Basic ${base64_encode($clientId:$clientSecret)}’ Note the single space between ‘Basic’ and the base64-encoded value. An example of the basic authentication header (taken from Wikipedia https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side):

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

The Climate OAuth2 token API will return a JSON response containing an access_token and a user. The access_token will be required for all future Climate FieldView API calls. Use the access_token in the Authorize header on all calls to Climate FieldView APIs with the following format: 'Bearer $access_token’:

Authorization: Bearer 435a5f91-617a-427d-8609-3b43f5ad52d4

If the Authorization header is missing, a 401 HTTP status code will be returned with the following response body:

{"message": "Unauthorized"}
Access Token Lifespan

Access tokens will expire 4 hours from the time they are issued. To generate a new access token, your application will make a request similar to step 3 (Access Token Request & Response) but will provide the refresh token instead of the code.

Refresh Tokens

The /token endpoint returns a refresh_token (along with the access_token). The refresh token can be exchanged for a new access_token (and a new refresh_token) using the same /token endpoint. While the access token is good for 4 hours, the refresh token is good for 30 days or until it is exchanged. The old refresh token should be considered expired at this point and discarded.  Refresh tokens can only be used once.  Use the newly issued refresh token the next time you need an access token.  By exchanging the refresh token for a new one at least every 30 days, your application can extend a user session as long as needed.  If you wish to avoid the user having to Log in With FieldView in the future, update the access/refresh token pair at least every 30 days so the refresh token is never allowed to expire.

You’ll still need to supply your Basic Authorization header, composed from your client ID and secret.

To trade in the refresh_token, make the same POST request to https://api.climate.com/api/oauth/token that you make initially with the activation code, but with a new grant type. The body of the request should look like:

grant_type=refresh_token&refresh_token=${your_refresh_token}

Note: Currently there is a one hour grace period during which the old refresh token will remain valid, but this is not guaranteed and should not be depended upon.

Flow Diagram

FieldView OAuth 2 Flow Diagram

OAuth2 recommendations & potential pitfalls

The first access token and refresh token (always in a pair) are generated after the user authenticates with FieldView as part of the Access Token Request & Response. The refresh token should be stored in persistent storage. This is important because without the refresh token the user will have to log in again when the access token expires

The access token is used for all Climate FieldView API calls. This is during a user session which may be initiated by the user or through a backend service. When the next user session is started (assuming it's more than 4 hours later), the refresh token is used to generate a new access and refresh token pair. Store the new refresh token and use the access token to perform all subsequent Climate FieldView API calls. Repeat this process each time a user session is needed to make a batch of API calls. To ensure users do not need to Log in With FieldView again, make sure to exchange the refresh token for a new one at least every 30 days, even if no API calls are required during this time.

Here are some important tips to keep in mind when working with access and refresh tokens:

  • Refresh tokens are single use items. Once a refresh token is exchanged, it is no longer valid.
  • If a refresh token is lost by failing to record it in persistent storage, the only solution is to have require users to log in again using the Log in With FieldView process.
  • Ensure only one process or thread handles the token refresh for a given user. Multiple processes handling the token refresh can result in losing the current refresh token.
  • Access tokens are valid for 4 hours from when they are issued. Access tokens can be proactively refreshed before they expire or wait for a failure and refresh as needed. Either approach is acceptable.
Denial of Service (DoS/DDoS) Protection

Climate FieldView APIs are protected from denial of service attacks through several layers. This ensures availability for all partners during an attack which may be intentional or unintentional such as a runaway process. Throttling (rate limiting) is accomplished by the use of API keys.

In addition to the OAuth client ID and secret pair, an API key will also be provided by a Climate Corporation employee during onboarding. The API key is used to control throttling (429 responses) and record usage metrics.

The following header is required on all calls to the Climate FieldView APIs:

X-Api-Key: partner-name-b6b21726-a1db-46b9-be56-16532a0452d2

If the X-Api-Key header is missing or invalid, a 403 HTTP status code will be returned with the following response body:

{"message": "Forbidden"}