User Guide Cancel

cfoauth

 

The <cfoauth> tag allows you to easily integrate third-party OAuth 2 authentication providers in your application. This tag currently supports Facebook, Microsoft, and Google authentication. Also, this tag supports OAuth providers that support the OAuth 2 protocols. For instance, Okta and Github.

Syntax

<cfoauth
type = "Facebook|Google|Microsoft"
grantType=""
refreshtoken=""
providerConfig=""
clientid = ""
scope = ""
state = ""
authendpoint = ""
secretkey = ""
accesstokenendpoint = ""
result = ""
redirecturi = ""
urlparams = ""
>
<cfoauth type = "Facebook|Google|Microsoft" grantType="" refreshtoken="" providerConfig="" clientid = "" scope = "" state = "" authendpoint = "" secretkey = "" accesstokenendpoint = "" result = "" redirecturi = "" urlparams = "" >
<cfoauth 
type = "Facebook|Google|Microsoft" 
grantType=""
refreshtoken=""
providerConfig=""
clientid = "" 
scope = "" 
state = ""
authendpoint = ""
secretkey = "" 
accesstokenendpoint = "" 
result = "" 
redirecturi = ""
urlparams = ""
>

History

  • ColdFusion (2025 release): The cfoauth tag has been updated to support enhanced workflows and configurations which include,
    • Script based function getOauthAccessToken: This built-in function accepts details as struct and returns the token.
    • Addition of the grantType attribute: A new optional grantType attribute has been introduced to specify the type of authorization workflow. The supported values are:
      • authorization_code (default)
      • refresh_token
      • client_credentials
    • This release also introduces Microsoft as a new auth type along with Google and Facebook. See the examples for more information.
  • ColdFusion 11: Added the function.

Attributes

Attribute

Req/Opt

Default

Description

Type="microsoft"

Type="facebook"
Type="google"

One of the following is required:

type or 
accesstokenendpoint and authendpoint combination

Either type can be specified or endpoints combination but not both

 

Currently supported values are Mic rosoft, Facebook and Google. Implicitly supports the authentication workflow
of Microsoft, Facebook, and Google.

grantType Optional authorization_code

Specifies the type of authorization workflow.Supported values are:

  • authorization_code (default): The standard user authentication flow.
  • refresh_token: Enables token renewal without requiring reauthentication. If grantType is not provided, the tag defaults to the existing authorization_code workflow. 
  • client_credentials: Allows application-level access without user involvement, typically for admin-consented APIs.
refreshtoken

Required

Only for refresh_token grant flow

  refresh_token grant flow accepts refreshtoken to retrieve a new access_token.
providerConfig

Required

Only to specify provider-specific configuration.

 

Accepts the following provider-specific details as struct:

  • tenant: Accepts tenant id for Microsoft which is unique to an organization registered with Microsoft.
  • apiVersion: Version of the Facebook API.

clientid

required

 

Unique ID generated while registering your application with the OAuth provider.

scope

optional

For Facebook:
No default. Facebook defaults to
public_profile when scope is not specified.

For Google: https://www.googleapis.com
/auth/userinfo.profile+profile

Scopes are the permissions that a
developer seeks from the users. These
are usually comma separated values
of permissions. For Google, they are
space separated.

Refer to the Oauth provider's
documentations for more information.

For example, after Facebook
authentication, if a developer wants to
access an email address and then the
friend lists of a user, the developer will
use: scope="email,read_friendlists".

For another example, after Google
authentication, if a developer wants
read-only access to the contacts and
calendars of a user, the developer will
use: scope="https://www.googleapis.com
/auth/contacts.readonly https://www.googleapis.com/auth
/calendar.readonly".

Note: The scope name varies for different OAuth providers. 

state

optional

 

The state variable is used to pass back any information to your web application after the authentication and redirection are completed. Any value passed to this attribute is returned to the web application after authentication. This is useful for CSRF (Cross-site request forgery) protection. You can use ColdFusion’s security-related CSRF functions for this attribute.

authendpoint

One of the following is required:

type or 
accesstokenendpoint and authendpoint combination

Either type can be specified or endpoints combination but not both

For Facebook:
https://www.facebook.com
/dialog/oauth

For Google:
https://accounts.google.com/
o/oauth2/auth

If type is not specified, this will be used as end point URL to be invoked for user authentication.

secretkey

optional

 

Parameter is the App Secret as displayed in your social media app's settings.

accesstoken
endpoint

One of the following is required:

type or 
accesstokenendpoint and authendpoint combination

Either type can be specified or endpoints combination but not both

 

 If type is not specified this will be used as end point URL to be invoked for app authentication.

result

optional

 

A struct which will have login info of the user including login success/failure, failure reason, user name, user id.

redirecturi

optional

This will default to the URL which is executing the code.
So if in OAuth settings user has given app URL as :

http://domainname
/appname

And the file executing the code is :

http://domainname
/appname/login.cfm

The redirect URI will be : http://domainname
/appname/login.cfm

To redirect once user authentication is done.

urlparams

optional

 

Extra options which will be passed as URL query string to authendpoint.

Step 1: Register with the OAuth 2 provider

Register your application in the OAuth 2 provider site with the relevant site-specific application details. (For instance, in Facebook  you must create the Facebook App ID and App Secret).

In ColdFusion, specify your ID and App Secret in the cfoauth tag.

Note:

ColdFusion implicitly supports Microsoft, Facebook, and Google. For other sites, use auth and access token endpoints and other attributes.

Syntax

<cfoauth
type = "Facebook|Google...."
clientid = ""
scope = ""
state = ""
authendpoint = ""
secretkey = ""
accesstokenendpoint = ""
result = ""
redirecturi = ""
urlparams = ""
>
<cfoauth type = "Facebook|Google...." clientid = "" scope = "" state = "" authendpoint = "" secretkey = "" accesstokenendpoint = "" result = "" redirecturi = "" urlparams = "" >
<cfoauth
type = "Facebook|Google...."
clientid = ""
scope = ""
state = ""
authendpoint = ""
secretkey = ""
accesstokenendpoint = ""
result = ""
redirecturi = ""
urlparams = ""
>

redirecturi will default to the URL which is executing the code. For example, if in OAuth settings user has entered the app URL as: http://domainname/appname and the file executing the code as  http://domainname/appname/login.cfm, the redirect URI will be: http://domainname/appname/login.cfm.

Also, register your domain details in your social media site.

Step 2: Understand the authentication process.

  • Once the user clicks the client site login button, the user will be prompted with a popup to grant the permissions.
  • If the user is not logged into the client site, they will be prompted to login.
  • If the user has already authorized your app and has already granted the permissions requested in scope, the user will be immediately redirected to your redirect_uri.
Note:

If the user has already authorized your application, but you are requesting additional permissions in the scope parameter, the user will be presented with a dialog which shows only the requested permissions that the user has not already granted your application.

Step 3: Implementing 

The following example shows a simple authentication:

<cflogin>
<cfoauth
type = "Facebook"
clientid = "YOUR_CLIENT_ID"
secretkey = "YOUR_SECRET_KEY"
result = "res"
redirecturi = "http://localhost:8500/doc/login.cfm" >
<cfloginuser name = "#res.other.username#" password = "#res.access_token#" roles = "user"/>
</cflogin>
<cflocation url="http://localhost:8500/doc/index.cfm" >
<cflogin> <cfoauth type = "Facebook" clientid = "YOUR_CLIENT_ID" secretkey = "YOUR_SECRET_KEY" result = "res" redirecturi = "http://localhost:8500/doc/login.cfm" > <cfloginuser name = "#res.other.username#" password = "#res.access_token#" roles = "user"/> </cflogin> <cflocation url="http://localhost:8500/doc/index.cfm" >
<cflogin>
<cfoauth
type = "Facebook"
clientid = "YOUR_CLIENT_ID"
secretkey = "YOUR_SECRET_KEY"
result = "res"
redirecturi = "http://localhost:8500/doc/login.cfm" >
<cfloginuser name = "#res.other.username#" password = "#res.access_token#" roles = "user"/>
</cflogin>
<cflocation url="http://localhost:8500/doc/index.cfm" >
Note:
  • Tokens and permissions for Microsoft APIs are configured via Microsoft Entra Admin Portal.
  • API Permissions are defined during application creation in Entra, controlling the scope of access granted to tokens.

Microsoft

Example 1- using grantType as Authorization_Code

<cfoauth clientid = "client-id" type = "Microsoft" providerconfig = #{tenant = "tenant-id"}# scope = "offline_access mail.read" secretkey = "secret-key" granttype = "Authorization_Code" result = "response">
<cfoauth clientid = "client-id" type = "Microsoft" providerconfig = #{tenant = "tenant-id"}# scope = "offline_access mail.read" secretkey = "secret-key" granttype = "Authorization_Code" result = "response">
<cfoauth clientid = "client-id" type = "Microsoft" providerconfig = #{tenant = "tenant-id"}# scope = "offline_access mail.read" secretkey = "secret-key" granttype = "Authorization_Code" result = "response">

Example 2- using refresh token

<cfoauth type = "microsoft" providerconfig = #{tenant = "tenant-id"}# granttype = "refresh_token" clientid = "client-id" secretKey = "secret-key" refreshtoken = "#response.refresh_token#" result = "response1">
<cfoauth type = "microsoft" providerconfig = #{tenant = "tenant-id"}# granttype = "refresh_token" clientid = "client-id" secretKey = "secret-key" refreshtoken = "#response.refresh_token#" result = "response1">
<cfoauth type = "microsoft" providerconfig = #{tenant = "tenant-id"}# granttype = "refresh_token" clientid = "client-id" secretKey = "secret-key" refreshtoken = "#response.refresh_token#" result = "response1">

Example 3- using client credentials grant

<cfscript>
credentials = {type = "microsoft", providerConfig = {tenant: "tenant-id"},
clientid = "client-id",
scope = "offline_access mail.read",
secretKey = "secret-key",
granttype = "authorization_code"}
response = GetOauthAccessToken(credentials);
writeDump(response)
</cfscript>
<cfscript> credentials = {type = "microsoft", providerConfig = {tenant: "tenant-id"}, clientid = "client-id", scope = "offline_access mail.read", secretKey = "secret-key", granttype = "authorization_code"} response = GetOauthAccessToken(credentials); writeDump(response) </cfscript>
<cfscript> 
    credentials = {type = "microsoft", providerConfig = {tenant: "tenant-id"}, 
    clientid = "client-id", 
    scope = "offline_access mail.read", 
    secretKey = "secret-key", 
    granttype = "authorization_code"} 
    response = GetOauthAccessToken(credentials); 
    writeDump(response) 
</cfscript>

Google

Example 1- using grantType as Authorization_Code

<cfoauth
type="Google"
clientid="client-id"
scope="https://www.googleapis.com/auth/userinfo.profile https://www.google.com/calendar/feeds https://mail.google.com/ https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/devstorage.read_only"
secretKey="secret-key"
granttype="authorization_code"
redirecturi = "http://localhost:8503/oauth/authorization.cfm"
result="response"
urlparams="access_type=offline&prompt=consent"
>
<cfhttp url="https://storage.googleapis.com/storage/v1/b" method="GET" >
<cfhttpparam type="header" name="Authorization" value="Bearer #response.access_token#">
<cfhttpparam type="URL" name="project" value="value">
</cfhttp>
<cfdump var="#cfhttp#">
<cfoauth type="Google" clientid="client-id" scope="https://www.googleapis.com/auth/userinfo.profile https://www.google.com/calendar/feeds https://mail.google.com/ https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/devstorage.read_only" secretKey="secret-key" granttype="authorization_code" redirecturi = "http://localhost:8503/oauth/authorization.cfm" result="response" urlparams="access_type=offline&prompt=consent" > <cfhttp url="https://storage.googleapis.com/storage/v1/b" method="GET" > <cfhttpparam type="header" name="Authorization" value="Bearer #response.access_token#"> <cfhttpparam type="URL" name="project" value="value"> </cfhttp> <cfdump var="#cfhttp#">
<cfoauth
    type="Google"
    clientid="client-id"
    scope="https://www.googleapis.com/auth/userinfo.profile https://www.google.com/calendar/feeds https://mail.google.com/ https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/devstorage.read_only"
    secretKey="secret-key"
    granttype="authorization_code"
    redirecturi = "http://localhost:8503/oauth/authorization.cfm"
    result="response"
    urlparams="access_type=offline&prompt=consent"
>
<cfhttp url="https://storage.googleapis.com/storage/v1/b" method="GET" >
    <cfhttpparam type="header" name="Authorization" value="Bearer #response.access_token#">
    <cfhttpparam type="URL" name="project" value="value">
</cfhttp>
<cfdump var="#cfhttp#">

Example 2- get the refresh token

<cfoauth
type="Google"
clientid="3client-id" scope="https://www.googleapis.com/auth/userinfo.profile https://www.google.com/calendar/feeds"
secretKey="secret-id"
granttype="refresh_token"
result="response"
refreshtoken="refresh-token"
>
<cfdump var="#response#" >
<cfoauth type="Google" clientid="3client-id" scope="https://www.googleapis.com/auth/userinfo.profile https://www.google.com/calendar/feeds" secretKey="secret-id" granttype="refresh_token" result="response" refreshtoken="refresh-token" > <cfdump var="#response#" >
<cfoauth
    type="Google"
    clientid="3client-id" scope="https://www.googleapis.com/auth/userinfo.profile https://www.google.com/calendar/feeds"
    secretKey="secret-id"
    granttype="refresh_token"
    result="response"
    refreshtoken="refresh-token"
>
<cfdump var="#response#" >

Example 3- using script-based function, getOauthAccessToken

<cfscript>
credentials = {
type: "Google",
clientid: "client-idf,
scope: "https://www.googleapis.com/auth/userinfo.profile&https://www.google.com/calendar/feed",
secretKey: "secret-key",
redirecturi: "http://localhost:8503/oauth/authorizationScript.cfm",
granttype:"authorization_code",
urlparams:"access_type=offline&prompt=consent"
}
response = GetOauthAccessToken(credentials);
writeDump(response)
</cfscript>
<cfscript> credentials = { type: "Google", clientid: "client-idf, scope: "https://www.googleapis.com/auth/userinfo.profile&https://www.google.com/calendar/feed", secretKey: "secret-key", redirecturi: "http://localhost:8503/oauth/authorizationScript.cfm", granttype:"authorization_code", urlparams:"access_type=offline&prompt=consent" } response = GetOauthAccessToken(credentials); writeDump(response) </cfscript>
<cfscript>
    credentials = {
        type: "Google",
        clientid: "client-idf,
        scope: "https://www.googleapis.com/auth/userinfo.profile&https://www.google.com/calendar/feed",
        secretKey: "secret-key",
        redirecturi: "http://localhost:8503/oauth/authorizationScript.cfm",
        granttype:"authorization_code",
        urlparams:"access_type=offline&prompt=consent"
    }
    response = GetOauthAccessToken(credentials);
    writeDump(response)
</cfscript>

Get help faster and easier

New user?