ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

This content has been translated automatically.  Click here  to view the French version.
Help / WLanguage / WLanguage functions / Communication / Managing the OAuth 2.0 protocol
  • Operating mode of OAuth 2.0 authentication
  • How OpenID authentication works
  • Application in the background: Specific case from Android 10
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
Performs an authentication using:
  • the OAuth 2.0 protocol on any web service.
  • WindowsLinuxiPhone/iPadIOS WidgetMac Catalyst the OpenID protocol on any web service.
  • New in version 2024
    WindowsLinuxiPhone/iPadIOS WidgetMac Catalyst a JWT token.
AndroidiPhone/iPadIOS WidgetMac Catalyst This function is not available in the simulator.
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...
Syntax
IOS WidgetMac Catalyst This syntax is not available for applications in iOS widget or Catalyst mode

Authentication via the OAuth 2.0 protocol Hide the details

<Result> = AuthIdentify(<Authentication parameters>)
<Result>: AuthToken variable
AuthToken variable corresponding to the token containing the access information for the next requests that require authentication.
<Authentication parameters>: OAuth2Parameters variable
Name of the OAuth2Parameters variable containing the parameters describing the elements required to retrieve the access token.

Authentication via the OAuth 2.0 protocol (asynchronous syntax) Hide the details

AuthIdentify(<Authentication parameters> , <WLanguage procedure>)
<Authentication parameters>: OAuth2Parameters variable
Name of the OAuth2Parameters variable containing the parameters describing the elements required to retrieve the access token.
<WLanguage procedure>: Procedure name
Name of the WLanguage procedure ("callback") called during the authentication. For more details on this procedure, see Parameters of the procedure used by AuthIdentify.
WindowsLinuxiPhone/iPad

Authentication via the OpenID protocol Hide the details

<Result> = AuthIdentify(<Authentication parameters>)
<Result>: AuthToken variable
AuthToken variable corresponding to the token containing the access information for the next requests that require authentication.
<Authentication parameters>: OpenIDParameters variable
Name of the OpenIDParameters variable containing the parameters describing the elements required to retrieve the access token.
WindowsLinuxiPhone/iPadIOS WidgetMac Catalyst

Authentication via the OpenID protocol (asynchronous syntax) Hide the details

AuthIdentify(<Authentication parameters> , <WLanguage procedure>)
<Authentication parameters>: OpenIDParameters variable
Name of the OpenIDParameters variable containing the parameters describing the elements required to retrieve the access token.
<WLanguage procedure>: Procedure name
Name of the WLanguage procedure ("callback") called during the authentication. For more details on this procedure, see Parameters of the procedure used by AuthIdentify.
New in version 2024
WindowsLinuxiPhone/iPadIOS WidgetMac Catalyst

Using a JWT authentication Hide the details

<Result> = AuthIdentify(<Authentication parameters>)
<Result>: AuthToken variable
AuthToken variable corresponding to the token containing the access information for the next requests that require authentication.
<Authentication parameters>: JWTParameters variable
Name of the JWTParameters variable containing the parameters describing the elements required to retrieve the access token.
New in version 2024
WindowsLinuxiPhone/iPadIOS WidgetMac Catalyst

Using a JWT authentication (asynchronous syntax) Hide the details

AuthIdentify(<Authentication parameters> , <WLanguage procedure>)
<Authentication parameters>: JWTParameters variable
Name of the JWTParameters variable containing the parameters describing the elements required to retrieve the access token.
<WLanguage procedure>: Procedure name
Name of the WLanguage procedure ("callback") called during the authentication. For more details on this procedure, see Parameters of the procedure used by AuthIdentify.
Remarks

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.
    • WINDEVAndroid 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
    • iPhone/iPad 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

How OpenID authentication works

The following are OpenID authentication steps performed by AuthIdentify:
  • Running a first HTTP request to ask for an authorization (authorization URL specified in the OpenIDParameters variable).
  • Opening an OpenID authentication window. The authentication window is defined by each service.
  • Executing a second HTTP request to get the access token after the authentication. 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 authenticate the user, simply use OpenIDReadIdentity and specify the AuthToken variable.
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.
Android

Application in the background: Specific case from Android 10

From Android 10, it is no longer possible to open a window when the application is in the background.
AuthIdentify can open a window. If this function is used while the application is in the background, a fatal error will occur.
Tips:
  • It is possible to determine if the application is in the background using InBackgroundMode.
  • If an application needs to interact with the user while it is in the background, the solution is to display a notification (via the Notification type). The application will be brought back to the foreground when the notification is clicked, if the ActivateApplication property is set to True. You can also open a window from the procedure passed to the ActionClick property.
Related Examples:
WD OAuth Training (WINDEV): WD OAuth
[ + ] OAuth allows you to act as user of an external platform without knowing the identifiers (user name and password) of this user.
Several external platforms (among which Google, Twitter, Facebook) propose APIs for which you have the ability to connect with the information belonging to one of their users. This identification is performed via OAuth. Therefore, all the requests performed on their services (API, ...) will require an access token identifying both the application (the "client") and the user.
The example proposes to connect to Google and Microsoft via the AuthConnect function and the OAuth2Parameter type.
Business / UI classification: Business Logic
Component: wd290ggl.dll
Minimum version required
  • Version 22
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 01/18/2024

Send a report | Local help