GETTING STARTED

AUTHENTICATION

 

IMPORTANT
Make sure all requests are https and POSTs.

 

 

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].

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

 

 

 

 

 

 

 

 

  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.

This is really only to deal with backwards compatibility with UIs that aren't dealing with "logonToken" in hash - if you have full control over the app namespace then you can skip this step.

3 React to authentication level

 

Use SETUP_USER_MANAGE to control level and also delivery (Email or SMS) 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_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])

     
         
  USER PASSWORD (SETUP_USER_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.