ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Communication / Managing the OAuth 2.0 protocol
  • Properties specific to AuthToken variables
  • Operating mode of OAuth 2.0 authentication
  • Using the AuthToken variables
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
The AuthToken type contains the characteristics of a token used to access a web service. This access token was previously requested:
  • by the AuthIdentify function.
  • by an HTTP request. In this case, the request returns the token in JSON format.
You can define and change the characteristics of this access token using different WLanguage properties.
Remark: For more details on the declaration of this type of variable and the use of WLanguage properties, see Declaring a variable.
Example
// Example used to retrieve a token to perform a request on Dropbox
OAuth2Params is OAuth2Parameters
OAuth2Params.ClientID = "01234567890123456789" 
OAuth2Params.ClientSecret = "98765432109876543210"
OAuth2Params.AuthURL = "https://www.dropbox.com/oauth2/authorize"
OAuth2Params.TokenURL = "https://api.dropboxapi.com/oauth2/token"
OAuth2Params.AdditionalParameters = "force_reapprove=false"
<COMPILE IF ConfigurationType<>Site>
	// If you are not using a website, you need to specify a localhost redirect URL
	OAuth2Params.RedirectionURL = "http://localhost:9874/"
<END>

// Ask for authentication: opens the login window
MyToken is AuthToken = AuthIdentify(OAuth2Params)

// Request authenticated on a Dropbox API
req is httpRequest
req.Method = httpPost
req.URL = "https://api.dropboxapi.com/2/files/list_folder"
req.AuthToken = MyToken // Authentication token
req.ContentType = "application/json"
vAPIParam is Variant
vAPIParam.path = "/Homework/math"
vAPIParam.recursive = False
vAPIParam.include_media_info = False
vAPIParam.include_deleted = False
vAPIParam.include_has_explicit_shared_members = False
req.Content = VariantToJSON(vAPIParam)

HTTPresponse is httpResponse = HTTPSend(req)
let Data = JSONToVariant(HTTPresponse.Content)
// Use the incoming data...
// Retrieves the token (in JSON) via an HTTP request. The AuthIdentify function is not used
// Define the request
httpReq is httpRequest
httpReq.Method = httpPost
httpReq.URL = PAYPAL_TOKEN
httpReq.User = PAYPAL_APP_ID
httpReq.Password = PAYPAL_SECRET
httpReq.Content = "grant_type=client_credentials"
httpReq.ContentType = "application/x-www-form-urlencoded"

// Execute query
httpRep is httpResponse = HTTPSend(httpReq)

// Retrieve the token
IF httpRep.StatusCode = 200 THEN
// Declares the parameters, required to refresh the token
oAuth2Param is OAuth2Parameters
oAuth2Param.ClientID = PAYPAL_APP_ID
oAuth2Param.ClientSecret = PAYPAL_SECRET
oAuth2Param.AuthURL = PAYPAL_ACCESS_BASEURL
oAuth2Param.Scope = PAYPAL_SCOPES
oAuth2Param.TokenURL = PAYPAL_TOKEN

// Initializes the token with JSON
MyToken is AuthToken(oAuth2Param, httpRep.Content)
gMyToken <= MyToken
END
Syntax

Declaring an AuthToken variable Hide the details

MyVariable is AuthToken
In this case, AuthIdentify is used to retrieve the token parameters.

Declaring and describing an AuthToken variable (without using the AuthIdentify function) Hide the details

MyVariable is AuthToken(<OAuth2 parameter> , <Token>)
<OAuth2 parameter>: OAuthParameters variable
Name of the OAuth2Parameters variable containing the information required to authenticate on a service implementing the OAuth 2.0 standard.
<Token>: Character string
String in JSON or UTF-8 format containing the token. Corresponds to the token returned by the service.
Remarks

Properties specific to AuthToken variables

The following properties can be used to handle a token for accessing a web service:
Property nameType usedEffect
ExpirationDateDateTimeExpiration date and time of token.
RefreshCharacter stringValue returned by the server to determine if the token can be refreshed.
If this property is not specified, AuthRefreshToken cannot be used to refresh the token: you will have to request a new token..
ServerResponseBufferValue returned by the server when the access token is requested.
This property is read-only.
ValidBooleanValidity of the access token:
  • True if the access token is valid.
  • False otherwise.
This property is read-only.
ValueCharacter stringAccess token.
Value automatically filled when using AuthIdentify.
This value can be used to send authenticated requests to the relevant web service.

Operating mode of OAuth 2.0 authentication

The steps of OAuth 2.0 authentication performed by AuthIdentify are as follows:
  • Running a first HTTP request to ask for an authorization (authorization URL specified in the OAuth2Parameters variable).
  • Opening an OAuth 2.0 authentication window. The authentication window is defined by each service.
  • After the authentication, the server returns an authorization code to request an access token. This code is added as parameter of second URL (access token URL specified in the OAuth2Parameters variable).
  • Running the second HTTP request to ask for the access token. The result is a JSON buffer that contains, among other elements, the access token ("access_token") to be used for the requests that require authentication. The AuthToken variable contains the information found in this JSON buffer. This access token will be used by the calls to the APIs of the web service.
To use the APIs of the web service, simply use HTTPSend with a variable of type httpRequest defining the request to be executed.
The AuthToken variable will be assigned to the AuthToken property of the httpRequest variable (see example).
In this case, the server will receive the HTTP "Authorization" header with a value in the following format: "Authorization: Bearer xxx_access_token_xxx".
Caution:
  • If the server does not return the access token in the format of JSON code according to the OAuth2.0 standard, an error will occur and the token will not be retrieved. The server response can be retrieved via the ServerResponse property of the AuthToken variable.
  • If the server does not support the HTTP "Authorization" header for transmitting the access token, this transmission must be done by the developer according to the format expected by the requested service.
    The following example allows you to use the web service of Facebook. In this case, the access token must be specified on the request URL.
    • WINDEV Code sample for Facebook
      // Example used to retrieve the name of the Facebook account
      MyToken is AuthToken
      MyTokenParam is OAuth2Parameters
      
      MyTokenParam.ClientID = "123456789012345"
      MyTokenParam.ClientSecret = "45g8jh5kll45579021qsg5444j"
      MyTokenParam.AuthURL = "https://www.facebook.com/dialog/oauth"
      MyTokenParam.TokenURL = "https://graph.facebook.com/v2.3/oauth/access_token"
      MyTokenParam.RedirectionURL = "http://localhost:9874/"
      MyTokenParam.Scope = "email"
      
      MyToken = AuthIdentify(MyTokenParam)
      IF MyToken <> Null THEN
      	IF ErrorOccurred THEN
      		Error(ErrorInfo())
      	ELSE
      		// Token specified on the request URL
      		HTTPRequest("https://graph.facebook.com/me?access_token=" + MyToken.Value)
      		vMyRes is Variant = JSONToVariant(HTTPGetResult(httpResult))
      		// Retrieve the account name
      		Trace(vMyRes.name)
      	END
      END

Using the AuthToken variables

AuthToken variables can be used with the following functions:
Minimum version required
  • Version 22
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 06/25/2024

Send a report | Local help