AuthToken (Type of variable)

ONLINE HELP
FOR WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Management of OAuth 2.0 protocol

AuthToken

Presentation

Example

Properties specific to the description of AuthToken variables

Operating mode of OAuth 2.0 authentication

Using the AuthToken variables

See also

AuthToken (Type of variable)

In french: AuthToken

The AuthToken type contains the characteristics of a token to access a Web service. This access token was requested beforehand:

by AuthIdentify.
by an HTTP request. In this case, the request returns the token in JSON format.

The characteristics of this access token can be defined and modified by several WLanguage properties.

Note: See Declaring a variable for more details.

Versions 23 and later

This type of variable is now available for iPhone/iPad applications.

New in version 23

This type of variable is now available for iPhone/iPad applications.

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"

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

// Run the request
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..URLAuth = PAYPAL_ACCESS_BASEURL
oAuth2Param..Scope = PAYPAL_SCOPES
oAuth2Param..URLToken = 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 OAuth2Parameters variable containing the information required to authenticate on a service implementing the OAuth 2.0 standard.

<Token>: Character string (with quotes)

String in JSON or UTF8 format containing the token. Corresponds to the token returned by the service.

Remarks

Properties specific to the description of AuthToken variables

The following properties can be used to handle a token for accessing a Webservice:

Property name	Type used	Effect

ServerResponse	Buffer	Value returned by the server during the request made by the access token. This property is available in read-only.
Value	Character string	Access token. Value automatically filled when using AuthIdentify. This value can be used to send authenticated requests onto the relevant Web service.
Valid	Boolean	Validity of access token: True if the access token is valid. False otherwise. This property is available in read-only.

Note: These properties can be handled by using one of the following syntaxes:

<Variable name>..<Property name>
<Variable name>.<Property name>

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 a window for user identification according to the OAuth 2.0 protocol. The identification interface is given by the service accessed.
After identification, the server returns a first authorization code allowing you to ask the resources for an access token. This code is added in 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 things, the access token ("access_token") that will be used for the authenticated requests. The AuthToken variable contains the information found in this JSON buffer. This access token will be used by the calls to the APIs of Web service.

To use the APIs of Web service, all you have to do is call HTTPSend with an httpRequest variable defining the request to run.
The AuthToken variable will have to be assigned to the ..AuthToken property of httpRequest variable (see the 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 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.
- 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
- Code sample for Facebook:
  
  MyToken is AuthToken
  MyTokenParam is OAuth2Parameters
  MyTokenParam..ClientID = "1705548803004741"
  MyTokenParam..ClientSecret = "7b3305a5aa1687ef04af001ec3388ecc"
  MyTokenParam..AuthURL = "https://www.facebook.com/dialog/oauth"
  MyTokenParam..TokenURL = "https://graph.facebook.com/oauth/access_token"
  MyTokenParam..RedirectionURL = "fb1705548803004741://authorize/"
  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 in the functions:

standard syntax:


Versions 22 and later AuthIdentify New in version 22 AuthIdentify AuthIdentify	Performs an authentication using the OAuth 2.0 protocol on any webservice.
Versions 24 and later OpenIDReadIdentity New in version 24 OpenIDReadIdentity OpenIDReadIdentity	Retrieves the identity of a user contained in an AuthToken variable.

object syntax:


Versions 24 and later <AuthToken variable>.OpenIDReadIdentity New in version 24 <AuthToken variable>.OpenIDReadIdentity <AuthToken variable>.OpenIDReadIdentity	Retrieves the identity of a user contained in an AuthToken variable.