Users

Introduction

  • For further details regarding role permissions, please refer to the section on user profiles.

  • For further details regarding the login process in OpenGate, please refer to the user LOG-IN section.

Two-Factor Authentication (2FA)

Two-Factor Authentication (2FA) can be configured at the user level.

The only possible value is “TOTP”. (Time-Based On-Time) as defined in [RFC-6238] (https://www.rfc-editor.org/rfc/rfc6238).

By default, this field will be set to “NONE”. If you wish to deactivate the 2FA, please set the property 2FaType to NONE and perform a PUT on the user.

Please refer to the schema for each attribute used.

Log in with Two-Factor Authentication (2FA)

In the event that two-factor authentication (2FA) has been enabled for a particular user, it is necessary to incorporate the code generated by the associated application into the “2FaCode” attribute of the JSON.

Configure your application

Upon initial login following the configuration of two-factor authentication (2FA), the LOGIN service will respond with a URL location in the headers containing the configuration parameters. These parameters should be used to configure your application to generate the codes.

The URL will be as follows: otpauth://totp/2FA?secret=CAX3VP5O7GWZXUDWQOK4267DGXXSFIDQ&issuer=OpenGate&algorithm=SHA1&digits=6&period=30

Description of the attributes of the URL

  • secret: Contains the secret key to generate codes.
  • period: Defines the time validation period of the code.
  • digits: Defines the length of the generated code.
  • algorithm: Defines the algorithm used to generate the codes.
  • issuer: Defines the subject, the name of the server.

Some applications only require the secret field, while others may need all parameters.

Comprehensive API actions

Reading a user

Please replace {id} with the email address of the user you wish to retrieve. There are two ways to use the GET method:

  1. Administrative: This is the standard use of the GET method as defined in HTTP. In this case, you use GET with the Apikey.
  2. Login: You can use the method GET to log in, adding the password in the field of the header X-ApiPass. The Apikey is not necessary.

Updating a user

An administrator is able to modify another user’s API key or password, update their own API key, or update their own password.

To update the ApiKey or password of another user by an administrator

Any user with administration role is allowed to change the ApiKey / password of any managed user (excluding himself), the same way as any other user’s field.

In this case, the ApiKey or password will be considered as any other basic user data. In this case, it’s allowed to change the ApiKey or password with any other user’s field. If the administrator needs to change his own ApiKey/password, it must be done as explained bellow.

To update your own ApiKey

Any user with an administrative role is permitted to modify the ApiKey/password of any managed user (excluding themselves), in a manner consistent with the process for modifying any other user’s field.

In this instance, the ApiKey or password will be treated in the same way as any other basic user data. It is therefore permitted to change the ApiKey or password with any other user’s field. If the administrator wishes to change their own ApiKey/password, this must be done in accordance with the instructions set out below.

To update your own password

As with updating your own ApiKey, any user is able to change their own password. This is the only method available, regardless of whether the user has an administration profile. In this case, the current user’s password must be included in the X-ApiPass field of the REQUEST HEADERS section (the X-ApiKey field is not required). Additionally, the JSON of the REQUEST BODY should include only the new password as shown in the “Change the user’s own password” option. Please note that it is not permitted to change any other user’s field.

When setting a password…

The password must meet the following criteria for both creating and updating users:

  • It must be between 12 and 25 characters long.
  • It must include upper case letters.
  • It must include lowercase letters.
  • It must include numbers.
  • It must include special characters: !"#$%&’()*+,-./:;<=>?@[]^_`{|}~

The password will have an expiration time of 6 months, by default.

Logging in OpenGate platform.

Note

It is not a requisite to include an API key or JWT token in the header of the request.

The JWT token will be validated by OpenGate under the following conditions:

  1. The JWT token will have an expiration time, typically 24 hours.
  2. The JWT token will be signed with an OpenGate encrypted key. If the token received is not signed with the same encrypted key or has been modified, it will be rejected.

API specification

Subsections of Users

User login

For you are authenticate in OpenGate you have to do LOG-IN to obtain a token JWT or an ApiKey:

Do login

Basic login

Do you need an email and password.

flowchart TD
    CU["CREATE User"] --> V{"Valid User"}
    V -- No --> E400["ERROR 400<br>Json malformed"]
    V -- "Yes, LOG-IN" --> LOGIN["Do LOG-IN<br>email and password"]
    LOGIN --> VC{"Valid<br>email and password"}
    VC -- No --> E401["ERROR 401<br>Bad credentials"]
    VC -- Yes --> OK["Return: 200 OK<br>Return data (JWT and ApiKey)"]

    classDef error fill:#f9d0d0,stroke:#c85a5a,color:#000
    classDef ok fill:#a8ecd0,stroke:#2b9c6e,color:#000
    class E400,E401 error
    class OK ok

Login with Two Factor Authentication

Do you need an email, password and an 2FA Code generated.

How can you generate the 2FA code?

First, you have to configure your application to generate codes.

Configure your application

When you do login in OpenGate, the first time after configuring 2FA, the LOG-IN service responds with an error code 401, but in the headers contains an URL in the attribute location with the parameters of configuration.

You have to use this parameters to configure your application to generate the codes.

The URL of location will be like this otpauth://totp/2FA?secret=CAX3VP5O7GWZXUDWQOK4267DGXXSFIDQ&issuer=OpenGate&algorithm=SHA1&digits=6&period=30

Description of the attributes of the URL:

  • secret: contain the secret key to generate codes.
  • period: define the time of validation of the code.
  • digits: define the length of the code generated.
  • algorithm: define the Algorithm used to generate the codes.
  • issuer: define the subject, the name of the server.

Some applications only need the secret field, and others need all parameters.

You can see the flow of this process in follow diagram:

flowchart TD
    CU["CREATE or UPDATE USER<br>with 2FA"] --> V{"Valid User<br>with 2FA type"}
    V -- No --> E400["ERROR 400<br>Json malformed"]
    V -- "Yes, LOG-IN" --> LOGIN["Do LOG-IN<br>without 2FA Code"]
    LOGIN --> FIRST{"First time"}
    FIRST -- No --> E401A["ERROR 401<br>Bad Credentials<br>or Bad 2Fa Code sent"]
    FIRST -- Yes --> HDR["Return: ERROR 401<br>Headers with URL 2FA"]
    HDR --> APP["With URL - Configure APP"]
    APP --> GEN["Generate 2FA code<br>with the application"]
    GEN --> LOGIN2["Do LOG-IN with 2FA"]
    LOGIN2 --> VC{"Valid<br>email and password"}
    VC -- No --> E401B["ERROR 401<br>Bad Credentials"]
    VC -- Yes --> EXP{"Code expired<br>Code invalid"}
    EXP -- No --> OK["Return 200 OK<br>Return data (JWT and ApiKey)"]
    EXP -- Yes --> E401C["401 ERROR<br>Invalid Code"]

    classDef error fill:#f9d0d0,stroke:#c85a5a,color:#000
    classDef ok fill:#a8ecd0,stroke:#2b9c6e,color:#000
    classDef step fill:#addcf8,stroke:#2b7cb8,color:#000
    class E400,E401A,E401B,E401C,HDR error
    class OK ok
    class LOGIN,APP,GEN,LOGIN2 step

2FA error responses

Every 2FA failure returns 401 Unauthorized, so the error code is what tells the cases apart:

Code Situation Context
0x000065 First login after configuring 2FA. Read the location header to configure your application. 2FA
0x000065 2FA is configured but no code was sent. 2FaCode is null
0x000066 The code sent is invalid or expired. 2FaCode
0x000067 A code was sent but the user has no 2FA configured. Log in without the TOTP code. 2FaCode

An expired password is a different case: it returns 403 with code 0x010063.

User profiles

OpenGate by default incorporates a set of user profiles which is listed below:

New adhoc user profiles can be added to adapt to specific needs.

Profiles

  • root
  • super_admin_domain
  • admin_domain
  • admin
  • advanced
  • viewer

root

Total control for managing all resources in the platform

super_admin_domain

super_admin_domain access to the Provision API

  • Domains (create, update, delete)
  • Subdomains (create and update)
  • Organizations (create, update, delete)
  • Work groups (create, update, delete)
  • Channels (create, update, delete)
  • Users (create, update, delete)
  • Certificates (create, update, delete, download)
  • Data models (create, update, delete)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • APNs (create)
  • Radius Clients (create)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Manufacturers (create, read, update, delete)
  • Models (create, read, update, delete)
  • Datasets (create, read, update, delete)
  • Provision processors (create, read, update, delete)
  • Timeseries (create, read, update, delete)
  • Artificial Intelligence (create, read, update, delete)

super_admin_domain access to the Search API

Full access.

super_admin_domain access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

admin_domain

admin_domain access to the Provision API

  • Domains (create, update, delete)
  • Subdomains (create and update)
  • Organizations (create, update, delete)
  • Work groups (create, update, delete)
  • Channels (create, update, delete)
  • Users (create, update, delete)
  • Certificates (create, update, delete, download)
  • Data models (create, update, delete)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • APNs (create)
  • Radius Clients (create)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Artificial Intelligence (read)

admin_domain access to the Search API

Full access.

admin_domain access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

admin

admin access to the Provision API

  • Work groups (create, update, delete)
  • Channels (create, update, delete)
  • Users (create, update, delete)
  • Certificates (create, update, delete, download)
  • Data models (create, update, delete)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • APNs (create)
  • Radius Clients (create)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Artificial Intelligence (read)

admin access to the Search APIs

Full access.

admin access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

advanced

advanced access to the Provision API

  • Users (update yourself)
  • Certificates (download)
  • Areas (create, read, update, delete)
  • Bulk of Assets, Devices, subscriptions (create, update, delete)
  • Assets entities (create, read, update, delete)
  • Devices entities (create, read, update, delete)
  • Subscriptions entities (create, read, update, delete)
  • Subscribers entities (create, read, update, delete)
  • Tags (create)
  • Tickets (create, read, update, delete)
  • Artificial Intelligence (read)

advanced access to the Search API

Full access.

advanced access to the Operation API

  • Jobs (create, read, update, delete)
  • Tasks (create, read, update, delete)
  • Alarms (read, attend, close)
  • Rules (read, update, clone, delete)
  • Bundles (create, read, update, delete, execute)
  • Download csv

viewer

viewer access to the Provision API

  • Users (update yourself)
  • Certificates (download)
  • Areas (read)
  • Assets entities (read)
  • Devices entities (read)
  • Subscriptions entities (read)
  • Subscribers entities (read)
  • Tickets (read)
  • Artificial Intelligence (read)

viewer access to the Search API

Full access.

viewer access to the Operation API

  • Jobs (read)
  • Tasks (read)
  • Alarms (read)
  • Rules (read)
  • Bundles (read)
  • Download csv