| IMPORTANT Make sure all requests are https and POSTs. |
Note: This help page is currently being updated to recommend the use of SHA256/512 instead of MD5 and TOTP as the 2nd Factor.
Any references to MD5 should be read as SHA256/512 and any references to 2FA by SMS should be read as by TOTP.
You can authenticate using a logon/password combination or get a secure access token
If you are not using a secure access token – then you need to authenticate via the logon endpoint (/rpc/logon)
If you are using a “user-agent” like a web-browser that supports cookies, then the session ID will be stored automatically and used for subsequent requests (POSTs) – if the “user-agent”/client does not support cookies then you need to record the returned session ID (sid) and logonKey and append it to each subsequent request – eg &sid=[sid]&logonkey=[logonkey returned by LOGON method].
You can also use "auth-" http headers to pass the authentication data - see the "HTTP HEADERS" section on this page.
To authenticate you need to POST to /rpc/logon/:
&logon=
&password=
or
&passwordhash=md5([logonname][password])
It is best practice to POST (not GET) all requests via https (not http) to ensure all data is encrypted and use passwordhash.
| Our approach to security |
| Reward for reporting an issue |
| LOGON endpoint |
| SAML 2.0 |
| JSON Web Tokens (JWT) |
| Single sign-on (SAML 2.0) & mydigitalstructure |
| OAuth 2.0 |
| Using TOTP as 2nd Factor |
| 1 | Find out about current user | /rpc/core/?method=CORE_GET_USER_DETAILS |
| 2 | If no current user then found out what their authentication level is | /rpc/logon/?method=LOGON_GET_USER_AUTHENTICATION_LEVEL &logon=[logonname] &passwordhash=md5([logonname][password]) This is re-playable but not an issue, as only gives up authentication level. |
| 3 | React to authentication level
Use SETUP_USER_MANAGE to control level and also delivery (Send as Email, Send as SMS or user generated using TOTP Client) if 2nd Factor. |
#1 - Basic /rpc/logon/?method=LOGON &logon=[logonname] &passwordhash=md5([logonname][password]) #2 - Logon Key (logonkey) #3 - Logon Key & Password Code (passwordcode) - 2nd Factor then: display input for the password code. then: If authenticationdelivery=3 (TOTP) then you need to add: &passwordcode=[passwordcode] If will then get validated by the LOGON method based on the user. |
| 1 | Minimum Password Strength
&password |
A point score from 1 to 7. If length = 6, then 1 point. If length >= 8, then plus 1 point. If length >= 12, then plus 1 point. If special character, then plus 1 point. If lower case, then plus 1 point. If upper case, then plus 1 point. if a number, then plus 1 point. An example of 7 point score would be S%venFunkyMonk1es |
| 2 | Minimum Password Length
&minimum |
Can not be less than 6. |
| 3 | Lost Password
&password |
1 = Send (sends the current password) 2 = Reset (resets to new password and sends) |
You can generate a token for a user using:
/rpc/core/?method=CORE_SECURE_TOKEN_MANAGE&user=[userid]
You can then pass the generated token as &access_token= with each API call.
Access tokens can be disabled as and when required.
Security note: Given that this token gives privileged access (outside of the multi-token authorisation process), make sure you protect this token and be wary of using it in the URL query string, as data in the query string is not encrypted during transmission (even if using SSL). It is recommended that the user associated with this token has limited access to methods.
You can use http headers to pass the authentication data.
- "auth-sid" = "sid"
- "auth-logonkey" = "logonkey"
- "auth-passwordhash" = "passwordhash"
- "auth-logon" = "logon"
- "auth-password"= "password"
- "auth-identityprovideryype"= "identityprovideryype"
- "auth-samlresponse" = "samlresponse"
- "auth-data" = "data"