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.