OAuth2

Type

command

Summary

Present an authorization dialog for any web service that supports OAuth2 Authorization Code Flow

Syntax

OAuth2 <pAuthURL>,<pTokenURL>,<pClientID>,<pClientSecret>,<pScopes>,<pPortOrRedirectURI>,<pParams>,<pCompletionURL>

Description

On mobile platforms the authorization page will be presented to the user in a browser tab without leaving the app where possible. On desktop platforms and mobile system versions that do not support presenting browser tabs the authorization url will be launched in the user's default browser.

Mobile platforms support using a custom URI scheme in the redirect URI. This must be configured in the standalone settings. If not using a custom URI scheme the library accepts socket connections on localhost. While the port to accept connections on is configurable OAuth 2.0 servers supporting localhost redirects are required to permit any port so it is best practice to leave the pPortOrRedirectURI parameter empty to allow a port to be assigned in the ephemeral range. Many OAuth endpoints do not allow configuring multiple redirect URIs so it may be required to create separate mobile application and desktop application in order to use custom URI schemes on mobile.

The redirect URI configured when setting up your application with the web service for desktop should be http://127.0.0.1:port/ where port is the port that can be configured with the pPortOrRedirectURI. On mobile platforms use a reverse domain name based custom uri scheme such as com.example.myapp://myapp where com.example is a domain that you control.

*Warning

• The client secret should be kept securely when distributing an application in order to protect your application from malicious use. The recommended way to do this is to include the client secret into a script in a password protected stack. If that is not possible allow users to configure their own application with the web service and enter their own client id and secret into a preference instead of distributing your client id and secret.

Parameters

Name	Type	Description
pAuthURL		The URL to present for the authorization page. This can be obtained from the API documentation of the service being authorized.
pTokenURL		The URL to obtain the authorization token from once an authorization code is sent to the redirect uri. This can be obtained from the API documentation of the service being authorized.
pClientID		The application client ID obtained when setting up your application with the web service.
pClientSecret		The application client secret obtained when setting up your application with the web service.
pScopes		A space delimited list of authorization scopes. Valid scopes will be found in the API documentation of the service being authorized. If empty the scope parameter will be omitted.
pPortOrRedirectURI		The port to accept connections on or the full redirect uri if using a custom scheme to handle the URI redirect. If an integer > 0 the library will attempt to accept HTTP connections on the loopback address on that port. If 0 or empty a port will be assigned in the ephemeral range.
pParams		An array of additional key -> value pairs of extra parameters to be sent to the authorization url. Some services implement additional options that require extra parameters.
pCompletionURL		The URL to redirect the user's browser to on desktop systems after the library handles the OAuth redirect.

Examples

constant kAuthURL = "https://slack.com/oauth/authorize"
constant kTokenURL = "https://slack.com/api/oauth.access"
constant kClientID = "XXXXXXXXX.XXXXXXXX"
constant kClientSecret = "XXXXXXXXXXXXXXXXXXXXX"
constant kScopes = "incoming-webhook"

OAuth2 kAuthURL, kTokenURL, kClientID, kClientSecret, kScopes, 54303
if the result is not empty then
   answer error "Not authorized!"
else
   local tAuth
   put it into tAuth
   local tMessage
   ask question "What do you want to send?"
   if it is empty then
      exit mouseUp
   end if

   put it into tMessage["text"]
   put ArrayToJSON(tMessage) into tMessage

   set the httpHeaders to "Content-type: application/json" & \
         return & "Authorization: token " & sAuth["access_token"]
   post tMessage to url tAuth["incoming_webhook"]["url"]
end if

constant kAuthURL = "https://github.com/login/oauth/authorize"
constant kTokenURL = "https://github.com/login/oauth/access_token"
constant kMobileClientID = "XXXXXXXXX.XXXXXXXX"
constant kMobileClientSecret = "XXXXXXXXXXXXXXXXXXXXX"
constant kDesktopClientID = "XXXXXXXXX.XXXXXXXX"
constant kDesktopClientSecret = "XXXXXXXXXXXXXXXXXXXXX"
constant kScopes = "user repo"

if the environment is "mobile" then
   OAuth2 \
         kAuthURL, \
         kTokenURL, \
         kMobileClientID, \
         kMobileClientSecret, \
         kScopes, \
         "com.livecode.github://github"
else
   OAuth2 \
         kAuthURL, \
         kTokenURL, \
         kDesktopClientID, \
         kDesktopClientSecret, \
         kScopes, \
         empty, \
         empty, \
         "https://livecode.com/github-auth-complete.html"
end if

if the result is not empty then
   answer error "Not authorized!"
else
   set the httpHeaders to "Accept: application/vnd.github.v3+json" & \
         return & "Authorization: token " & it["access_token"]
   local tUser
   put JSONToArray(url "https://api.github.com/user") into tUser
   answer "Hello" && tUser["name"]
end if