Table of Contents
Processes
API
The API request is a Http POST request.
A check request detects if
- the given application id exists
- the token is ok
- correct value
- timestamp is wihin 60 sec
- used only once
- a user
- needs to setup (first visit at MFA server)
- has a valid mfa challenge within the ttl (12 h)
- has an outdated mfa challenge
Request
The API request is an Http POST request.
🌐 Target url: url in key 'api' in your config file (given by mfa server)
📄 Data fields
| Name | Description |
|---|---|
| action | action to perform; one of “check”|“urls” |
| username | user id of logged in user |
| appid | application id from config (given by mfa server) |
| ip | ip address of the user request to the web application |
| request | url path and query string of traget url on mfa server |
| timestamp | timestamp (with milliseconds) |
| token | generated HAMC token using the fields “request” + “timestamp” plus “POST” - encrypted with the application secret (given by the mfa server) |
| useragent | user agent of the user visiting the web aplication |
Response
The response is JSON.
The basic fields are:
| Name | Description |
|---|---|
| status | http status code |
| error | on error: a clear text message (en) |
| message | message text |
Posiible Keys of “check” response:
| Name | Description |
|---|---|
| url | depending on status: url to jump in into mfa server (eg user needs to setup first or can solve a challenge). This field does not exist if the check failed and a user action is not possible. |
Posiible Keys of “urls” response:
| Name | Description |
|---|---|
| setup | url to open users mfa setup page |
| verify | url to solve a challenge |
Jump to MFA server
To jump in into the setup page or to solve a token an Http POST request is needed.
🌐 The target url is taken from the response of a “check” or “urls” request.
📄 The fields are mostly similiar to the api request.
| Name | Description |
|---|---|
| username | user id of logged in user |
| appid | application id from config (given by mfa server) |
| ip | ip address of the user request to the web application |
| request | url path and query string of traget url on mfa server |
| timestamp | timestamp (with milliseconds) |
| token | generated HAMC token using the fields “request” + “timestamp” plus “POST” - encrypted with the application secret (given by the mfa server) |
| backurl | url for mfa server where to jump back to the application |