+ +

Oauth2 Authentication

+ +

This tutorial demonstrates how you can create a request for OAuth2 authentication and authorization grant from a server, obtain the access token using manager handle, and retrieve this info from the response handle returned in the callback.

+ +

API Usage

Become familiar with the OAtuh2 API basics by learning about:

Initializing the OAuth2 Manager +
Initialize the oauth2 manager for use.
Creating and Managing an OAuth2 Request +
Create a request, set its parameters, and pass it to oauth2 manager for requesting token.
+
- Creating Request Handle +
  Create a oauth2 request handle.
- Setting Request Parameters +
  Add parameters needed to make a request oauth2 token/ grant.
- Retrieving Request Parameters +
  Retrieve the various request parameters set.
- Destroying Request Handle +
  Delete and free the request handle.
+
Request server for Grant/ Token +
Request the authorization server for the required oauth2 grant or token.
+
- Requesting Authorization Code +
  Request the authorization code to obtain access or refresh tokens.
- Requesting Access Token +
  Request an access token from the authorization server.
- Refreshing Access Token +
  Refresh an access token using refresh token.
+
Managing an OAuth2 Response +
Obtain information the oauth2 response handle returned in callback.
+
- Retrieving Response Parameters +
  Retrieve the response parameters from handle.
- Error Handling in Response +
  Handling an error response from the server.
- Destroying Response Handle +
  Delete and free the response handle.
+
Destroying the Oauth2 Manager Handle +
Destroy the manager handle.

+ +

Show All
Hide All

+ +

+
+
Initializing the Oauth2 Manager
+Hide +
+
+
To initialize the oauth2 manager:
+
1. To use the functions and data types of the Oauth2 Manager API, include the <oauth2.h> header file in your application:
  +
```
+#include <oauth2.h>
+
```
2. Declare the necessary global variables and create the manager handle using oauth2_manager_create(). To know, whether a function has been executed properly, see that the return is equal to OAUTH2_ERROR_NONE.
  + +
```
+static oauth2_manager_h mgr = NULL;
+int ret = OAUTH2_ERROR_NONE;
+ret = oauth2_manager_create(&mgr)
+
```
3. Set up the required privileges for your application:
  + +
  - To use APIs for oauth2 authentication and connecting to the web servers, add the http://tizen.org/privilege/internet privilege to the manifest file. +
+
+
+
+
Creating and Managing an Oauth2 Request
+Hide +
+
+
To make a request with oauth2 manager, create a request, set it properties, and pass it as a parameter in the oauth2 manager API:
+
+
+
+
Creating Request Handle
+Hide +
+
+
Define an oauth2_request_h handle.
+
- Create an oauth2 request using the oauth2_request_create() function after defining the above mentioned request handle: + +
```
+oauth2_request_h request = NULL;
+ret = oauth2_request_create(&request);
+
```
  +
+
+

Setting Request Parameters

+Hide +

Set all the parameters needed for making an oauth2 request.

When the request is created, you can set its properties, such as end points for authentication and token, grant type, user name, and password: + +

+char* auth_url = "https://accounts.google.com/o/oauth2/auth";
+char* token_url = "https://accounts.google.com/o/oauth2/token";
+char* user_name = "username";
+char* password = "password";
+
+ret = oauth2_request_set_auth_end_point_url(request, auth_url);
+
+ret = oauth2_request_set_token_end_point_url(request, token_url);
+
+ret = oauth2_request_set_grant_type(request, OAUTH2_GRANT_TYPE_AUTH_CODE);
+
+ret = oauth2_request_set_user_name(request, user_name);
+
+ret = oauth2_request_set_password(request, password);request
+
+

Retrieving Request Parameters

+Hide +

Retrieve information for an existing request handle.

To get request information, such as end points for authentication and token, grant type, user name, and password: + +

+char* auth_url = NULL;
+char* token_url = NULL;
+char* user_name = NULL;
+char* password = NULL;
+oauth2_grant_type_e grant_type;
+
+ret = oauth2_request_get_auth_end_point_url(request, &auth_url);
+
+ret = oauth2_request_get_token_end_point_url(request, &token_url);
+
+ret = oauth2_request_get_grant_type(request, &grant_type)
+
+ret = oauth2_request_get_user_name(request, &user_name);
+
+ret = oauth2_request_get_password(request, &password);
+

+
+
Destroying Request Handle
+Hide +
+
+
To free the request handle.
+
- Use the oauth2_request_destroy() function to destroy the request handle: + +
```
+ret = oauth2_request_destroy(request);
+
```
  +
+
+
+
+
Request server for Grant/ Token
+Hide +
+
+
Obtain the required authorization code or access token.
+
+

Requesting Authorization Code

+Hide +

The authorization code grant type is used to obtain both access tokens and refresh tokens. It is a redirection-based flow that requires the client to +interact with the server and receiving the incoming requests (via redirection) from the authorization server. +

Use the oauth2_manager_request_authorization_grant() function to request for authorization code: + +

+void
+grant_response_cb(oauth2_response_h response, void* user_data)
+{
+   // authorization code response callback
+   char *auth_code = NULL;
+   oauth2_response_get_authorization_code(response, &auth_code);
+}
+
+void
+request_auth_code(void)
+{
+   oauth2_manager_h mgr = NULL;
+   int ret = oauth2_manager_create(&mgr);
+
+   oauth2_request_h request = NULL;
+   ret = oauth2_request_create(&request);
+
+   /*
+    * Set all the required parameters needed as per the web server's
+    * OAuth2 authentication policy before making the request.
+    */
+
+   // Setting the response_type as "code"
+   ret = oauth2_request_set_response_type(request, OAUTH2_RESPONSE_TYPE_CODE);
+
+   // Setting the applications client_id registered in server
+   ret = oauth2_request_set_client_id(request, "app_client_id");
+
+   // Setting the redirect_uri for the server to redirect flow after authentication
+   ret = oauth2_request_set_redirection_url(request, "https://developer.tizen.org");
+
+   // Request server for authorization grant. The reponse from server is returned in the callback.
+   ret = oauth2_manager_request_authorization_grant(mgr, request, grant_response_cb, user_data);
+}
+

+
+
Requesting Access Token
+Hide +
+
+
Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server.
+
+

Requesting access token with the authorization code obtained

+Hide +

In the authorization code grant type, instead of requesting authorization directly from the resource owner, the client directs the resource owner to an + authorization server, which in turn directs the resource owner back to the client with the authorization code. +

Authorization code can be requested by using oauth2_manager_request_authorization_grant() API. +After authentication, the response from the server is returned in the oauth2_auth_grant_cb callback function as shown in the previous section.

Once authorization code is obtained, we can reuqest for the access token using this code by calling the oauth2_manager_request_access_token() API. The reponse from server is returned in the oauth2_access_token_cb callback function where access token can be retrieved: + +

+void
+access_token_cb(oauth2_response_h response, void* user_data)
+{
+   // access token response callback
+
+   char *access_token = NULL;
+   oauth2_response_get_access_token(response, &access_token);
+}
+
+void
+grant_response_cb(oauth2_response_h response, void* user_data)
+{
+   // authorization code response callback
+   char *auth_code = NULL;
+   oauth2_response_get_authorization_code(response, &auth_code);
+
+   if (auth_code)
+   {
+      oauth2_manager_h mgr = NULL;
+      int ret = oauth2_manager_create(&mgr);
+
+      // request handle was passed as the user data
+      oauth2_request_h request = (oauth2_request_h) user_data;
+
+      ret = oauth2_request_set_authorization_code(request, auth_code);
+
+      if (mgr && request)
+      {
+       ret = oauth2_manager_request_access_token(mgr, request, access_token_cb, NULL);
+      }
+   }
+}
+
+void
+request_auth_code(void)
+{
+   oauth2_manager_h mgr = NULL;
+   int ret = oauth2_manager_create(&mgr);
+
+   oauth2_request_h request = NULL;
+   ret = oauth2_request_create(&request);
+
+   /*
+    * Set all the required parameters needed as per the web server's
+    * OAuth2 authentication policy before making the request.
+    */
+
+   ret = oauth2_request_set_auth_end_point_url(request, "https://login.live.com/oauth20_authorize.srf");
+
+   ret = oauth2_request_set_token_end_point_url(request, "https://login.live.com/oauth20_token.srf");
+
+   ret = oauth2_request_set_redirection_url(request, "https://developer.tizen.org");
+
+   ret = oauth2_request_set_client_id(request, "WINDOWS_CLIENT_ID");
+
+   ret = oauth2_request_set_client_secret(request, "WINDOWS_CLIENT_SECRET");
+
+   ret = oauth2_request_set_scope(request, "wl.basic");
+
+   ret = oauth2_request_set_response_type(request, OAUTH2_RESPONSE_TYPE_CODE);
+
+   if (mgr && request)
+   {
+      ret = oauth2_manager_request_authorization_grant(mgr, request, grant_response_cb, request);
+   }
+}
+

Requesting access token directly

+Hide +

We can also request for an access token in a single step without obtaining authorization code explicitly in this method. The code is obtained after authentication and passed to the server to obtain the access token internally in case of Authorization Code grant type. In case of Implicit, Resourse Owner Password Credentials and Client Credentials grant type, we can obtain the access token directly as follows. +

Use the oauth2_manager_request_token() API to request for access token as shown below. We can check the response from the server in the oauth2_token_cb callback function: + +

+void
+token_response_cb(oauth2_response_h response, void* user_data)
+{
+   // access token response callback
+   char *access_token = NULL;
+   oauth2_response_get_access_token(response, &access_token);
+}
+
+void
+request_access_token(void)
+{
+   oauth2_manager_h mgr = NULL;
+   int ret = oauth2_manager_create(&mgr);
+
+   oauth2_request_h request = NULL;
+   ret = oauth2_request_create(&request);
+
+   /*
+    * Set all the required parameters needed as per the web server's
+    * OAuth2 authentication policy before making the request.
+    */
+
+   ret = oauth2_request_set_auth_end_point_url(request, "https://www.facebook.com/dialog/oauth");
+
+   ret = oauth2_request_set_redirection_url(request, "https://developer.tizen.org");
+
+   ret = oauth2_request_set_client_id(request, "SAMPLE_CLIENT_ID");
+
+   ret = oauth2_request_set_scope(request, "read_stream");
+
+   ret = oauth2_request_set_response_type(request, OAUTH2_RESPONSE_TYPE_TOKEN);
+
+   if (mgr && request)
+   {
+      ret = oauth2_manager_request_token(mgr, request, token_response_cb, request);
+      if (ret != OAUTH2_ERROR_NONE)
+      { 
+         LOGE("Access Token request failed"); 
+      }
+   }
+}
+

Refreshing Access Token

+Hide +

Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.

Use the oauth2_manager_refresh_access_token() API to refresh an access token as shown below. We can check the response from the server in the oauth2_refresh_token_cb callback function: + +

+void
+token_response_cb(oauth2_response_h response, void* user_data)
+{
+   // access token response callback
+   char *access_token = NULL;
+   oauth2_response_get_access_token(response, &access_token);
+}
+
+void
+refresh_token_response_cb(oauth2_response_h response, void* user_data)
+{
+   char *acc_token = NULL;
+   oauth2_response_get_access_token(response, &acc_token);
+
+   char *ref_token = NULL;
+   oauth2_response_get_refresh_token(response, &ref_token);
+
+   char *auth_code = NULL;
+   oauth2_response_get_authorization_code(response, &auth_code);
+   if (auth_code)
+   {
+      oauth2_manager_h mgr = (oauth2_manager_h) user_data;
+
+      oauth2_request_h request = NULL;
+
+      int ret = oauth2_request_create(&request);
+
+      /*
+       * Set all the required parameters needed as per the web server's
+       * OAuth2 authentication policy before making the request.
+       */
+
+      ret = oauth2_request_set_refresh_token_url(request, "https://www.googleapis.com/oauth2/v3/token");
+
+      ret = oauth2_request_set_refresh_token(request, ref_token);
+
+      ret = oauth2_request_set_client_id(request, "GOOGLE_CLIENT_ID");
+
+      ret = oauth2_request_set_client_secret(request, "GOOGLE_CLIENT_SECRET");
+
+      ret = oauth2_request_set_grant_type(request, OAUTH2_GRANT_TYPE_REFRESH);
+
+      ret = oauth2_request_set_client_authentication_type(request, OAUTH2_CLIENT_AUTHENTICATION_TYPE_REQUEST_BODY);
+
+      if (mgr && request)
+      {
+         ret = oauth2_manager_refresh_access_token(mgr, request, token_response_cb, NULL);
+      }
+   }
+}
+
+void
+request_access_token(void)
+{
+   oauth2_manager_h mgr = NULL;
+   int ret = oauth2_manager_create(&mgr);
+
+   oauth2_request_h request = NULL;
+   ret = oauth2_request_create(&request);
+
+   /*
+    * Set all the required parameters needed as per the web server's
+    * OAuth2 authentication policy before making the request.
+    */
+
+   ret = oauth2_request_set_auth_end_point_url(request, "https://accounts.google.com/o/oauth2/auth");
+
+   ret = oauth2_request_set_token_end_point_url(request, "https://accounts.google.com/o/oauth2/token");
+
+   ret = oauth2_request_set_redirection_url(request, "https://localhost:8080");
+
+   ret = oauth2_request_set_client_id(request, "GOOGLE_CLIENT_ID");
+
+   ret = oauth2_request_set_client_secret(request, "GOOGLE_CLIENT_SECRET");
+
+   ret = oauth2_request_set_scope(request, "email");
+
+   ret = oauth2_request_set_response_type(request, OAUTH2_RESPONSE_TYPE_CODE);
+
+   if (mgr && request)
+   {
+      ret = oauth2_manager_request_token(mgr, request, refresh_token_response_cb, mgr);
+   }
+}
+

+
+
Managing an Oauth2 Response
+Hide +
+
+
The response from server is bundled in the oauth2_response_h handle and returned in the callbacks, +from which all the various response parameters can be obtained. +
+
+

Retrieving Response Parameters

+Hide +

Retrieve information for the response handle.

To get response information, such as authorization code, access token, state, token type: + +

+char* auth_code = NULL;
+char* access_token = NULL;
+char* state = NULL;
+char* token_type = NULL;
+
+ret = oauth2_response_get_authorization_code(response, &auth_code);
+
+ret = oauth2_response_get_access_token(response, &access_token);
+
+ret = oauth2_response_get_state(response, &state);
+
+ret = oauth2_response_get_token_type(response, &token_type);
+

Error Hanlding in Response

+Hide +

If the request created is incorrect or the required permissions are not present, then there is an in response from server.

We can retrieve the error information from the response handle to check the issue: + +

+oauth2_error_h e_handle =  NULL;
+int error_code = 0;
+int platform_error_code = 0;
+char *description = NULL;
+char *uri = NULL;
+char *error_val = NULL;
+
+oauth2_response_get_error(response, &e_handle);
+
+oauth2_error_get_code(e_handle, &error_code, &platform_error_code);
+
+oauth2_error_get_description(e_handle, &description);
+
+oauth2_error_get_uri(e_handle, &uri);
+
+oauth2_error_get_custom_data(e_handle, "error", &error_val);
+
+

+
+
Destroying Response Handle
+Hide +
+
+
To free the response handle.
+
- Use the oauth2_response_destroy() function to destroy the response handle: + +
```
+ret = oauth2_response_destroy(response);
+
```
  +
+
+
+
+
Destroying Oauth2 Manager Handle
+Hide +
+
+
To free the oauth2 manager handle.
+
- Use the oauth2_manager_destroy() function to destroy the manager handle: + +
```
+ret = oauth2_manager_destroy(mgr);
+
```
  +
+
+

+ + + + +

OAuth 2.0 Authentication

Authorization Grant

Authorization Code

Implicit

Resource Owner Password Credentials

Client Credentials

Oauth2 Authentication

API Usage

Initializing the Oauth2 Manager

Creating and Managing an Oauth2 Request

Creating Request Handle

Setting Request Parameters

Retrieving Request Parameters

Destroying Request Handle

Request server for Grant/ Token

Requesting Authorization Code

Requesting Access Token

Requesting access token with the authorization code obtained

Requesting access token directly

Refreshing Access Token

Managing an Oauth2 Response

Retrieving Response Parameters

Error Hanlding in Response

Destroying Response Handle

Destroying Oauth2 Manager Handle