Discuss this help topic in SecureBlackbox Forum

OAuth: Use the OAuth client with external browser

For the first authorization (when we don't have a refresh token or it is not valid anymore) using the browser, external to into your application, you need to take the following steps:

  1. Create an instance of TElHTTPSClient class, which will be used as a transport:


    // 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 all needed parameters using AuthURL, ClientID, ClientSecret, RedirectURL, Scope, TokenURL properties:


    // 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

  3. Add an event handler for OnLaunchBrowser event:


    // the event is fired when itís 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)

  4. Call Authorize() method. This method activates the built-in local server, that listens for the incoming connections on the port, specified in RedirectURL property, and waits for the redirect from the authorization server afer successful authentication of the user in the browser occurs. From time to time the method fires OnWait event, where you can find via TimeLeft parameter, how much time left until the timeout happens, or cancel waiting by setting Stop parameter to true (in this case Authorise() method will return false). The maximal waiting time is specified via Timeout property (in milliseconds). If timeout happens, EElSimpleOAuth2ClientError exception with the error code of SB_SIMPLE_OAUTH2_ERROR_TIMEOUT is thrown.

    After receiving the redirect and obtaining the authorization code from it, Authorize() method will send the html page to the browser. The text of this page is set via SuccessResponse. After that the authorization code will be automatically exchanged to get the access token, and Authorize() will return true. After that you can read AccessToken property to get the token, which will be used as a password during further connections.

    If the user doesn't provide the application access to its data, then Authorize() method sends the html page to the browser, with the text, specified in FailureResponse property, and will return false.

    As an alternative to using Authorize() method within one application session one can use the automatic refresh approach. To do this you need to set AutoRefresh property to true, then read the access token from AccessToken property. Each time when you read from AccessToken property, its validity is checked by checking the expiration time (available in ExpiresAt property). If the access token is not valid, the token refresh will be initiated automatically according to the following:

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

  5. The results of the authentication process are:
    • AccessToken - the access token, which is usually used as a password during further protocol (HTTP, SMTP etc.) connections;
    • ExpiresAt - the date and time (in UTC) when the token becomes invalid. Different servers have different expiration times, from one hour to one year.
    • RefreshToken - the token, which is used to refresh the access token. You need to save it between sessions (application starts) and put back to TElSimpleOAuth2Client on the next start so that the component could retrieve the new access token.

How To articles about client-side OAuth questions

Discuss this help topic in SecureBlackbox Forum