GETTING STARTED

AUTHENTICATION

 

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.

ibCom_mydigitalstructure_authentication-1.0.svg

 
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

 

 

 

 

 

 

 

 

  TYPICAL AUTHENTICATION (LOG ON) FLOW      
 
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)

/rpc/logon/?method=LOGON
&logon=[logonname]
&passwordhash=md5([logonname][password][logonkey])

#3 - Logon Key & Password Code (passwordcode) - 2nd Factor

/rpc/logon/?method=LOGON_SEND_PASSWORD_CODE

&logon=[logonname]
&passwordhash=md5([logonname][password][logonkey])

then:

display input for the password code.

then:

/rpc/logon/?method=LOGON

&logon=[logonname]
&passwordhash=md5([logonname][password][logonkey][passwordcode])

If authenticationdelivery=3 (TOTP) then you need to add:

&passwordcode=[passwordcode]

If will then get validated by the LOGON method based on the user.

     
         
  USER PASSWORD (SETUP_SPACE_SETTINGS_MANAGE)      
 
1 Minimum Password Strength

&password
minimum
strength

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
password
length

Can not be less than 6. 
3 Lost Password

&password
lost

1 = Send (sends the current password)

2 = Reset (resets to new password and sends)

     
         
  TRUSTED PRIVILEGED ACCESS TOKENS      
  If you need to authenticate an user on a secure device that you have limited control over and you can not use the logon process described above, then you can use an access token.

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.

     
  USING HTTP HEADER      
 

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"