Security

OpenGate security

This section describes how access to the OpenGate REST APIs is secured. It covers the two supported authentication mechanisms, JWT and API keys, and the user password reset procedure.

Authentication

OpenGate authentication

The OpenGate REST APIs, and device integration mechanisms are enabled by default on all accounts. You don’t have to do anything to turn on these features. However, JWT (JSON Web Token) and API keys are mandatory and are used to control the access to the resources via the REST APIs and connectors.

The OpenGate REST APIs allow third-party applications or back-office systems to communicate with OpenGate. All users in your organization can use third-party applications to access your entity’s data, such as iPhone apps, Android apps, or network-based communication built onto your server. The OpenGate authentication mechanisms ensure the proper access to the information.

JWT
API key

JWT

Authenticating using JWT

What is JWT (JSON Web Token)?

JSON Web Token (JWT) is an open standard RFC 7519 that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

A JWT consists of three strings separated by dots: the header, the payload and the signature as shown in the following text.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Part Name	Value
Header	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9`
Payload	`eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ`
Signature	`SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c`

Token structure

The header typically consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, such as HMAC SHA256 or RSA.

Payload

The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional data. There are three types of claims: registered, public, and private claims.

Registered claims: These are a set of predefined claims which are not mandatory but recommended, to provide a set of useful, interoperable claims. Some of them are: iss (issuer), exp (expiration time), sub (subject), aud (audience), and others.
Public claims: These can be defined at will by those using JWTs. But to avoid collisions they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision resistant namespace.
Private claims: These are the custom claims created to share information between parties that agree on using them and are neither registered nor public claims.

Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

Obtain a JWT with OpenGate

To obtain a JWT token with OpenGate platform, you should do login with the resource /provision/users/login in the next link JWT.

The JWT (JSON Web Token) can be sent using as a request header.

POST /north/v80/provision/organizations/{organizationId}
Host: [api.opengate.es]
Authorization: Bearer YOUR-JWT-HERE

It is sent using the Authorization HTTP header. An example of POST request may look like this:

curl --request POST \
     --verbose \
     --header "Authorization: Bearer YOUR-JWT-HERE" \
     --header "Content-type: application/json" \
     --data-binary @device.json \
     https://[your_opengate_address]/north/v80/provision/organizations/{organizationId}

API key

Authenticating using API keys

This option can be disabled through configuration in all interfaces, with the exception of those used for device integration. The API keys can be sent using one of the following methods:

As a request header
As a parameter in the request URL (with the former preferred for security reasons). This option is only available for device integration

Using an HTTP header

This is the recommended method of sending your API key. While it is not secure if sent over an unencrypted connection, it is less likely to be logged as part of the URL:

API Key in HTTP header example:

POST /south/v80/devices/YOUR-DEVICE-ID/collect/dmm
Host: [api.opengate.es]
X-ApiKey: YOUR-API-KEY-HERE

The API key is sent using the X-ApiKey HTTP header. An example of POST request may look like this:

curl --request POST \
     --verbose \
     --header "X-ApiKey: YOUR-API-KEY-HERE" \
     --header "Content-type: application/json" \
     --data-binary @device.json \
     https://api.opengate.es/north/v80/provision/organizations/{organizationName}/devices

As a request parameter

Parameter Name	Value
X-ApiKey	YOUR_API_KEY_HERE

https://api.opengate.es/south/v80/devices/{device.id}/collect/dmm?X-ApiKey=YOUR-API-KEY-HERE

API key as URL parameter example:

POST /south/v80/devices/{device.id}/collect/dmm?X-ApiKey=YOUR-API-KEY-HERE
Host: [api.opengate.es]

User password reset

Introduction

This API provides a secure procedure to change a user’s password when it has been lost or forgotten. The process has two steps: first, request a password reset for the user’s email, which sends a recovery email with a reset identifier; then, set the new password using that reset identifier.

Usage examples

Request a password reset for a user (the platform generates a token and sends a password recovery email):

curl --request POST \
     https://api.opengate.es/north/v80/provision/users/{userEmail}/reset

Set the new password using the reset identifier received by email:

curl --request POST \
     --header "Content-Type: application/json" \
     --data '{"password": "<new-password>"}' \
     https://api.opengate.es/north/v80/provision/users/{userEmail}/reset/{resetId}