Discuss this help topic in SecureBlackbox Forum

OAuth: Use the OAuth client with external browser

This article explains, how to perform first OAuth authorization (when refresh token is not available or not valid) using the web-browser external to your application.

1. First, create an instance of TElHTTPSClient class which will be used for transport

   C#:

   
   // create and setup the http transport to be used to talk to
   // the authorization server
   TElHTTPSClient oauthTransport = new TElHTTPSClient();
   
   // assign an event handler to validate SSL certificate(s)
   oauthTransport.OnCertificateValidate += ...;
   

2. Create an instance of TElSimpleOAuth2Client class and set the following properties: AuthURL, ClientID, ClientSecret, RedirectURL, Scope, TokenURL.

   C#:

   
   // create a OAuth 2.0 client
   TElSimpleOAuth2Client oauth = new TElSimpleOAuth2Client();
   
   // assign the created HTTPS transport
   oauth.HTTPClient = https;
   
   // set the local URL to be used during authorization;
   // the specified port must be free and the application
   // has to be allowed to open a listening socket on that port
   oauth.RedirectURL = @"http://localhost:5050/";
   
   // authorization server URLs
   oauth.AuthURL = @"https://accounts.google.com/o/oauth2/auth";
   oauth.TokenURL = @"https://accounts.google.com/o/oauth2/token";
   
   // copy the client id and the client secret of your app
   // registered in Google Developers Console
   oauth.ClientID = @"your_client_id";
   oauth.ClientSecret = @"your_client_secret";
   
   // tell the authorization server what access is needed
   oauth.Scope = @"https://www.googleapis.com/auth/userinfo.email
                   https://www.googleapis.com/auth/userinfo.profile";
   

3. Create a handler for the OnLaunchBrowser event

   C#:

   
   // the event is fired when it is needed to open the web page
   // to login in the browser; here the event handler just starts
   // the default web browser and opens the passed URL in it
   oauth.OnLaunchBrowser += delegate (object Sender, string URL)
   {
       System.Diagnostics.Process.Start(URL);
   };
   

4. Call Authorize() method. When user has authenticated in the web browser, this method activates the built-in local server that listens for the incoming connections on the port, specified in the RedirectURL property. It is waiting until a redirect from the authorization server is received. From time to time the component fires the OnWait event which shows the remaining waiting time. You can cancel waiting by setting its Stop parameter to true (in this case Authorize() will return false). The maximum waiting time (in milliseconds) is specified by Timeout property. If no response is received until timeout, EElSimpleOAuth2ClientError exception is thrown with error code SB_SIMPLE_OAUTH2_ERROR_TIMEOUT.

   When redirect response is received, Authorize() extracts the authorization code from it, and sends the html page to the browser. The text of this page is specified by SuccessResponse. The authorization code is then exchanged for access token, and Authorize() returns true. After this, AccessToken property will contain the token which will be used as password to access the protected resource.

   If user doesn't want to grant the application access to protected data, Authorize() method sends the FailureResponse html page to the browser, and returns false.

   Automatic refresh could be used as an alternative to Authorize() method within one application session. Activate AutoRefresh, and read the AccessToken property. Each time when you read AccessToken, its validity is checked against expiration time, specified by ExpiresAt property. If access token is not valid, token refresh will be initiated automatically.

   • If a refresh token is available, it is used to retrieve new access token without user intervention;
   • If a refresh token is not available or could not be used for some reason, the authentication process will be initiated from the beginning, including OnLaunchBrowser event and waiting for new authorization code.

5. The results of the authentication process are:
   • AccessToken - access token which is usually used as a password during further HTTP, SMTP, etc., connections;
   • ExpiresAt - date and time (in UTC) when access token becomes invalid. Different servers provide different token lifetimes, from one hour to one year.
   • RefreshToken - token which can be used to get a new access token without user interaction. Save it when current session is over, and load it again into TElSimpleOAuth2Client on the next start.

How To articles about client-side OAuth questions

Discuss this help topic in SecureBlackbox Forum