AuthToken (Variable type)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / WLanguage / WLanguage functions / Communication / Managing the OAuth 2.0 protocol

Properties specific to AuthToken variables
How OAuth 2.0 authentication works
Using the AuthToken variables

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

AuthToken (Variable type)

In french: AuthToken

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.

Note: For more details on the declaration of this type of variable and the use of WLanguage properties, see Declaring a variable.

Example

// Exemple permettant de récupérer un token pour effectuer une requête sur 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 TypeConfiguration <> Site>
	// Si ce n'est pas dans un site WEB il faut une URL de redirection en localhost
	OAuth2Params.RedirectionURL = "http://localhost:9874/"
<END>

// Demande d'authentification : ouvre la fenêtre de login
MonToken is AuthToken = AuthIdentify(OAuth2Params)

// Requête authentifiée sur une API de Dropbox
req is httpRequest
req.Method = httpPost
req.URL = "https://api.dropboxapi.com/2/files/list_folder"
req.AuthToken = MonToken // Token d'authentification
req.ContentType = "application/json"
vParamAPI is Variant
vParamAPI.path = "/Homework/math"
vParamAPI.recursive = False
vParamAPI.include_media_info = False
vParamAPI.include_deleted = False
vParamAPI.include_has_explicit_shared_members = False
req.Content = VariantToJSON(vParamAPI)

réponseHTTP is httpResponse = HTTPSend(req)
let Données = JSONToVariant(réponseHTTP.Content)
// Utilisation des données reçues ...

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

Properties

Properties specific to AuthToken variables

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

Property name	Type used	Effect

ExpirationDate	DateTime	Expiration date and time of token. This property is now available.
Refresh	Character string	Value 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 need to request a new token. This property is now available.
ServerResponse	Buffer	Value returned by the server when the access token is requested. This property is read-only.
Valid	Boolean	Validity of the access token: True if the access token is valid. False otherwise. This property is read-only.
Value	Character string	Access token. Value automatically filled when using AuthIdentify. This value can be used to send authenticated requests to the relevant web service.

Remarks

How OAuth 2.0 authentication works

AuthIdentify performs the following actions to implement OAuth 2.0 authentication:

Executing a first HTTP authorization request (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).
Executing a second HTTP request to obtain 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.

Note If the authentication window is closed using the "Cancel" button, an invalid token is returned. In this case, the Valid property of the token is False and the variable ErrorDetected variable is True. The ErrorInfo function returns ""OAuth 2.0 connection error: <authentication canceled by user>"."

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" request header with a value in the following format: "Authorization: Bearer xxx_access_token_xxx".

Caution:

If the server does not return the access token as JSON code as specified by the OAuth2.0 standard, an error will be generated 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.

Code sample for Facebook

// Exemple permettant de récupérer le nom du compte Facebook
MonToken is AuthToken
MonTokenParam is OAuth2Parameters

MonTokenParam.ClientID = "123456789012345"
MonTokenParam.ClientSecret = "45g8jh5kll45579021qsg5444j"
MonTokenParam.AuthURL = "https://www.facebook.com/dialog/oauth"
MonTokenParam.TokenURL = "https://graph.facebook.com/v2.3/oauth/access_token"
MonTokenParam.RedirectionURL = "http://localhost:9874/"
MonTokenParam.Scope = "email"

MonToken = AuthIdentify(MonTokenParam)
IF MonToken <> Null THEN
	IF ErrorOccurred THEN
		Error(ErrorInfo())
	ELSE
		// Token précisé sur l'URL de la requête
		HTTPRequest("https://graph.facebook.com/me?access_token=" + MonToken.Value)
		vMonRes is Variant = JSONToVariant(HTTPGetResult(httpResult))
		// Récupération du nom du compte
		Trace(vMonRes.name)
	END
END

Code sample for Facebook:

MonToken is AuthToken
MonTokenParam is OAuth2Parameters
MonTokenParam.ClientID = "1705548803004741"
MonTokenParam.ClientSecret = "7b3305a5aa1687ef04af001ec3388ecc"
MonTokenParam.AuthURL = "https://www.facebook.com/dialog/oauth"
MonTokenParam.TokenURL = "https://graph.facebook.com/oauth/access_token"
MonTokenParam.RedirectionURL = "fb1705548803004741://authorize/"
MonTokenParam.Scope = "email"

MonToken = AuthIdentify(MonTokenParam)
IF MonToken <> Null THEN
	IF ErrorOccurred THEN
		Error(ErrorInfo())
	ELSE
		// Token précisé sur l'URL de la requête
		HTTPRequest("https://graph.facebook.com/me?access_token=" + MonToken.Value)
		vMonRes is Variant = JSONToVariant(HTTPGetResult(httpResult))
		// Récupération du nom du compte
		Trace(vMonRes.name)
	END
END

Using the AuthToken variables

AuthToken variables can be used with the following functions:

standard syntax:
AuthIdentify Performs an authentication using the OAuth 2.0 protocol on any web service.
OpenIDReadIdentity Retrieves the identity of a user contained in an AuthToken variable.
prefix syntax:
<AuthToken variable>.OpenIDReadIdentity Retrieves the identity of a user contained in an AuthToken variable.