Resources

MY CLOUD HOME

Authentication

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.

Refer to the https://tools.ietf.org/html/rfc6749 link for a detailed OAuth 2.0 spec.

You can find many resources on the Internet for authorization grant flow. One of them is:

https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2

A few other OAuth providers for your reference are:

 

Understanding the API Authorization flow

The following flow diagram explains the different steps in the authorization flow to communicate with the My Cloud Home REST APIs.

 

 

Authorization Steps

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.

Format

https://<service.auth0.url>/authorize?
scope=<scope_string>
&response_type=code&connection=Username-Password-Authentication&sso=false
&audience=mycloud.com&state=<state_string>&protocol=oauth2
&client_id=<client_id>&redirect_uri=<redirect_uri>

Example

https://<service.auth0.url>/authorize?
scope=openid%20offline_access%20nas_read_write%20nas_read_only%20user_read%20device_read
&response_type=code&connection=Username-Password-Authentication&sso=false
&audience=mycloud.com&state=my-custom-state&protocol=oauth2
&client_id=PoWAstGBvHV1HMWI7hofM6yL653RR&redirect_uri=http%3A%2F%2Flocalhost

 

 

On successful user login and authorization of the app, the authentication server redirects the user to the registered redirect URL. A format and an example of redirect call are as follows:

Format

http://localhost/?code=&state=

Example

http://localhost/?code=SkHDedtFEdtGucx&state=my-custom-state

 

Note  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).

Request

POST /oauth/token HTTP/1.1
Host: <service.auth0.url>
Content-Type: application/json
{
  "audience": "mycloud.com",
  "client_id": "",
  "client_secret": "",
  "code": "authorize_code",
  "grant_type": "authorization_code",
  "redirect_uri": ""
}

The token API will return access_token for your client application.

Response

{
  "access_token": "",
  "expires_in": 86400,
  "token_type": "Bearer"
}

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.

{
  "access_token": "",
  "expires_in": 86400,
  "refresh_token": "",
  "token_type": "Bearer"
}

 

Step 4: Request Access Token using Refresh Token

Refresh Tokens can be used to obtain new Access Tokens when the current access token becomes invalid or expires. Refresh tokens can be requested with offline access to the scopes.

Request

POST /oauth/token HTTP/1.1
Host: <service.auth0.url>
Content-Type: application/json
{
  "audience": "mycloud.com",
  "client_id": "",
  "client_secret": "",
  "grant_type": "refresh_token",
  "refresh_token": ""
}

Response

{
  "access_token": "",
  "expires_in": 86400,
  "scope": "read-only openid nas_read_only nas_read_write offline_access device_read user_read",
  "token_type": "Bearer"
}

 

Step 5: Get User Details

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.

An example of authorization URL is as follows:

https://<service.auth0.url>/authorize?
scope=openid%20offline_access%20nas_read_write%20nas_read_only%20user_read%20device_read
&response_type=code&connection=Username-Password-Authentication&sso=false
&audience=mycloud.com&state=my-custom-state&protocol=oauth2
&client_id=my-client-id&redirect_uri=http%3A%2F%2Flocalhost

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.

Refer to the Authentication APIs page to get details of APIs used for authentication.

GET /userinfo HTTP/1.1
Host: <service.auth0.url>
Authorization: Bearer 
 
200 OK
{
"sub": "auth0|582641749a46021f65565df0",
"email": "developer@mycloud.com",
"name": "My Cloud Developer",
"nickname": "developer",
"picture": "https://s.gravatar.com/avatar/1f66371ef418799384ac404049ccf8dd?s=
480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fyo.png",
"updated_at": "2017-02-02T18:50:53.414Z"
}

 

 

Do more with the
My Cloud Home Off-Device API

Click the buttons below to visit the My Cloud Home Off-Device Developer Home & Workflow pages

 

Developer
Home

Get started, access the API, build your apps, & learn more


View Home

Developer
Workflow

Register & submit your app for review and contact support


View Workflow