3/25/2019: Updated examples of authentication server URLs
To access and communicate with any of the My Cloud Home REST APIs, your application should get an access token using the standard OAuth 2.0 protocol. This section describes the My Cloud Home authorization flow.
The following flow diagram explains the different steps in the authorization flow to communicate with the My Cloud Home REST APIs.
Step 1: Get authentication server endpoint URL from config service response
To get the authentication server endpoint URL, view the Get Configuration API. The authentication server URL will be returned in the key "service.auth0.url":
"service.auth0.url": Endpoint for applications to log in, get user information, change password, etc. All the My Cloud Home APIs enforce authentication and require auth token in request.
Step 2: Send a request to authorization server with authorization URI
To obtain user authorization, open browser and send a request to authorization server with authorization URI. This endpoint will handle an active session lookup, authenticate the user, and obtain user consent. Format the URI based on the following example.
If your application is a mobile app, then you can use localhost as the redirect URL and extract the authorization code from redirected URL. If your application is an off-device web application, then you should provide the same redirect URL you provided at the application submission time.
Step 3: Request token using an authorization code
Once application gets the authorization code, it can make a POST call to My Cloud Home Authentication server to obtain an Access Token and a Refresh Token (optional).
If your app requires Refresh Access Token for later use, then you should request offline access to the scopes associated with the token. The token request will return Refresh Token in addition to Access Token.
Your application may want to get user details such as name, user_id, profile picture, etc. which would require authorization by the user. Use scope values in the authorization request to get additional user details. My Cloud Home uses OpenID Connect specifications for allowed user scopes. Refer http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims for more information on using scope values.
A typical My Cloud Home application requires the following scopes: openid, email, profile, nas_read_only, and nas_read_write.
Once the user completes the authentication and the app receives the Access Token, the app can request user details using the received access_token. In the example given below the value in 'sub' is the user_id. ‘Sub’ is an essential parameter that the app will require for later use.