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