AUTHORIZATION Flow - Medisana/vitadock-api GitHub Wiki

Getting Authorization for a Consumer

• To access the data on VitaDock Online the Consumer has to acquire a so-called Access Token/Secret pair. This is accomplished by requesting an Unauthorized Access, redirecting the user to the VitaDock Online login page (within a safe browser environment) and waiting for a callback (identified by the Unauthorized Access Token) by VitaDock Online when the VitaDock Online User was authenticated.

Overview

• After the application was registered the Consumer can request an Access Token/Secret pair.
• Figure 1 shows the steps necessary to acquire an Access Token/Secret pair. Mobile/Desktop applications need a separate step because their instance has to be registered separately

Figure 1 - Steps to acquire an Access Token/Secret pair

Mobile/Desktop applications

• Consumers running on Smart Phones or as Desktop applications are potentially insecure as their Application Token/Secret pair can be retrieved by an Attacker by disassembling the application.
• In addition, the VitaDock Online User might want to give individual Access Rights for different instances of the application (e.g. allowing reading and writing with the VitaDock Application on his iPhone while restricting a certain Consumer on his iPad to read only the last 30 entries).
• To accomplish this, the Consumer has to exchange its Application Token/Secret pair for an individual Device Token/Secret pair which will then be used instead (see Figure 2). o An Attacker that has obtained the Application Secret can still generate an own Device Token/Secret pair and pose as the Consumer but it will have to be separately authenticated by the VitaDock Online User (i.e. the VitaDock Online User can only authenticate individual instances but never the corresponding application in general) and it will have no access to existing Access Tokens. o The Attacker is also unable to decipher encrypted data flows or launch successful man-in-the-middle attacks somewhere along the flow.

Figure 2 - Registration of a new device

Unauthorized Access Token

• Using the Application/Device Token/Secret pair the Consumer can now access the Unauthorized Access Token/Secret pair.
• Figure 3 shows this request (starting with the 3rd party application/website)

Figure 3 - Request of an Unauthorized Access Token/Secret pair

Redirect to Login

• After acquiring the Unauthorized Access Token/Secret pair the Consumer has to redirect the system browser to the login page (https://cloud.vitadock.com, see Figure 4)
• The Consumer MUST NOT use an insecure embedded browser which does not support a possibility for the VitaDock Online User to check the validity of the page.
• The Consumer MUST NOT use an own Login screen or acquire the VitaDock Online User credentials in any other way.

Figure 4 - Login screen

Give device name (disabled)

When logging in using a mobile device or desktop application the first time the user has to assign a device name to the Device Token. Ideally the user should recognize that device name (same principle as for example with facebook when you log into your account from a new computer: The user is asked to give the device a name in order to recognize it and be able to notice break-ins by a 3rd party from a different device) when administering his Access Tokens. Currently this feature is disabled and the device of the user is automatically determined by the user agent.

Access Rights

• After the VitaDock Online User has logged in successfully, he is transferred to an access mask. In this access mask the VitaDock Online User all access information about the application demanding permission to access the user’s data will be shown.
• The VitaDock Online User will have the possibility to adapt the access limits/rights of the request or deny the access to the data (see Figure 5), currently it is only possible to either allow or deny the access.
• After the access is granted a Verifier Token (together with the Unauthorized Access Token) will be sent to the Consumer’s callback URL (this will be done via a redirect from the browser back to the Application or the web site of the Consumer.
• If no callback URL was set up for the application then the Verifier Token is displayed to the VitaDock Online User on the screen.
• If the VitaDock Online User denied the request for permission the string “denied=true” (together with the Unauthorized Access Token) will be sent to the Consumer’s callback URL (this will be done via a redirect from the browser back to the Application or the web site of the Consumer o If no callback URL was set up for the application then a message is displayed to the VitaDock Online User.

Figure 5 - Permission Request screen after user authentication

Acquiring the Access Token

• With the Verifier Token the Consumer can now request the corresponding Access Token/Secret pair from VitaDock Online.
• This step is necessary in order to prevent the possibility for a so-called “Session Fixation Attack” where an Attacker has acquired a valid Unauthorized Access Token/Secret pair.
• Figure 6 shows both steps (starting with the VitaDock Online)

Figure 6 - Request of an Authorized Access Token/Secret pair