There are multiple native and non-native apps from the Jira and Confluence product range that are available for smartphones and can be downloaded via the App Store or Play Store. However, those apps do not include a two-factor authentication for the login process. In order to implement this functionality in their apps, mobile app vendors have requested an API to support the second factor (which Secure Login provides) in their apps. To enable a two-factor authentication with Secure Login, the Secure Login API provided by syracom offers a set of necessary endpoints that allow an app to authenticate a second factor.
This authentication is linked with an HTTP session, which means that all of the apps requests must be done within the same session. In case the session has expired or was invalidated, the user has to do a new authentication. As all requests to the API must be authorized by the server, the API takes the username from the current HTTP session. The URL of the API depends on your installation, but generally follows the schema:
Provides information about the current state of the user.
Authenticates the user of the current HTTP session.
The usual call flow will first call /info to make sure the plugin is active and ready to work. If the plugin is inactive, nothing else needs to be done and the app proceeds. It is recommended to check from time to time if the plugin got activated. If the plugin is active, the app compares the timestamp that came with the response to see if there are any time drifts to consider.
The next call goes to /user, which delivers information about the users status from the perspective of Secure Login. The returned data indicates whether the user:
has to enter his or her PIN or
has to do the onboarding process or
is blocked (information about the reason for and duration of the block are provided)
If the user has to enter his or her PIN, then the next call will go to the endpoint /auth, which submits the PIN. On a correct PIN, Secure Login will validate the current HTTP session, and the user is authenticated.
Attention: If the app is installed on a phone that changes between different IP networks (for example if you connect to a different WiFi), then use the /info endpoint to check whether the user has to (re-)enter the PIN or is still authenticated.
What if the user enters a wrong PIN? After having entered a wrong PIN, the user can retry to enter the PIN as long as he or she has not been blocked. How many retries the user has until being blocked depends on the settings the administrator made.
The administrator can specify
after how many incorrect PINs the user is blocked and
Get information from Secure Login related to the current user.
Request - Query Parameters
The username is taken from the current HTTP session, so no parameter to submit.
Status 200 - application/json The request was completed successfully.
Status 410 - application/json The request was aborted, because the plugin is not active.
can take one of these values:
enter - the user has to enter the PIN bypass - no action is needed onboarding - the user has not completed the onboarding process yet. The onboarding process must be completed in a desktop browser. blocked - currently, the user cannot proceed because the account is blocked.
This is only available if status == blocked and contains details.
Structure fields: reason - Indicates why the account is blocked. Its only value is brute_force – too many PIN failures. until - Indicates until when the account is blocked. The timestamp format is in ISO- 8601 format and at time zone GMT.
Submit the PIN to authenticate the current HTTP session for the current user.
Request - Query Parameters
The username is taken from the current HTTP session. The PIN is posted with a Content-Type of text/plain as a sequence of numbers without any prefix or suffix and without any spacing. Just the string like 910817.
Status 200 - no response body The request was completed successfully and the session is authenticated.
Status 401 - no response body The authentication failed.
Status 406 - no response body The user still has onboarding status and cannot be authenticated yet.
Status 410 - no response body The request was aborted because the app is not active.