OAuth 2.0 is the industry-standard protocol for authorization, designed to simplify client development while offering specific authorization flows for applications. By integrating OAuth through providers, developers can decouple the authorization as well as the authentication layers from their applications, delegating these responsibilities to trusted providers. This approach allows developers to focus on core business logic while ensuring secure access management.

The cfoauth tag is the implementation of Oauth 2.0 specification in ColdFusion which allows you to integrate with these trusted providers into your application easily. Additionally, ColdFusion offers a built-in function, GetOauthAccessToken, which provides similar functionality. Currently, It has inbuilt support for Microsoft, Google and Facebook which allows ColdFusion users to easily integrate with these identity providers.

Understanding Oauth Workflows

To understand these workflows better, let’s take the example of Modern healthcare and insurance claim applications that provide services such as online doctor consultations, health checkups, telemedicine, medical insurance processing, and corporate healthcare benefits. Authentication & Authorization workflows in these applications involve secure and seamless access for both individual users and enterprises (corporate clients, insurance providers, and hospitals).

1. End-user login and access → Users sign in to access personal healthcare data, claims history, and insurance policies.
2. Enterprise onboarding and data sharing → Companies register employees for healthcare and insurance benefits without requiring individual logins.

End-User Login

This blog focuses on using Microsoft as the OAuth provider, so all references will be specific to Microsoft services. When an individual logs into a healthcare or insurance application, Authorization Code Flow ensures secure authentication before granting access to personal health or policy-related data. This approach requires the user to explicitly authenticate and approve access.

<cfscript>
    function updateUserSession(){
        authorizationCodeResponse = GetOauthAccessToken({
            type: "Microsoft",
            providerConfig: {
                tenant: "#application.tenantId#"
            },
            clientid: "#application.clientId#",
            secretKey: "#application.clientSecret#",
            scope: "offline_access user.read"
        });
        session.user = getUserCredentials(authorizationCodeResponse.access_token)
    }

    try {
        if(!structKeyExists(session, "user")) {
            updateUserSession();
        }
        buildTheUI(session.user.accessToken);
    }
    catch (any e) {
        writeLog("Token is expired!! Refresh it")
        try {
            refreshTokenResponse = GetOauthAccessToken({
                type: "Microsoft",
                providerConfig: {
                    tenant: "#application.tenantId#"
                },
                clientid: "#application.clientId#",
                secretKey: "#application.clientSecret#",
                refreshToken: "#session.user.refreshToken#",
                grantType: "refresh_token"
            });
            session.user.accessToken = refreshTokenResponse.access_token;
        }
        catch (any e) {
            updateUserSession();
        }
    }

    // Make the api call to the Microsoft server to retrieve user details
    function getUserCredentials(token){
    }

    function buildTheUI(userDetails) {
    }

    // Use those credentials and build your UI as per your need.
    buildTheUI(session.user);

</cfscript>

As you can in the above code, If the token expires we use refresh token flow to update the access token.

How It Works:

1. User initiates login → The application redirects the user to the Microsoft OAuth authorization server.
2. User authenticates → The user enters their credentials and grants permission to the application.
3. Application exchanges code for an access token →
   • If authentication is successful, Microsoft redirects the user back with an authorization code.
   • The application exchanges this code along with its credentials to obtain an Access Token.
4. Access Token is used → The application uses this token to retrieve the user’s profile, medical records, or insurance details.
5. Access Token refreshes automatically → Since Microsoft’s access tokens expire in 3600 seconds (1 hour), the application uses the Refresh Token (valid for 365 days) to request a new access token without requiring the user to log in again.

Note: The offline_access scope is required to receive a refresh token, and it is only granted if the user explicitly allows it.

Why Use Authorization Code Flow?

• Ensures secure authentication before granting access.
• Uses a server-to-server token exchange, reducing the risk of exposing credentials.
• Refresh tokens improve user experience, preventing frequent logins.
• Access can be revoked if necessary, maintaining security.

Enterprise Integration

Many healthcare and insurance applications allow enterprises (e.g., corporations, hospitals, and insurance providers) to onboard their employees or customers without requiring individual logins. This is where Client Credentials Flow is used, as it allows server-to-server authentication without user interaction.

<cfscript>
    clientCredentialsResponse = GetOauthAccessToken({
        type: "Microsoft",
        providerConfig: {
            tenant: "#application.tenantId#"
        },
        clientid: "#application.clientId#",
        secretKey: "#application.clientSecret#",
        scope: "https://graph.microsoft.com/.default",
        grantType: "client_credentials"
    });
   
    pullAllTheUsersAndUpdateDetails(clientCredentialsResponse.access_token);
</cfscript>

How It Works:

1. Enterprise registers with the application →
   • A company (HR, Admin, or Insurance Provider) creates an account.
   • The system generates API credentials (Client ID & Client Secret).
2. Application requests an Access Token → The backend requests an Access Token using the Client Credentials Flow.
3. OAuth server issues an Access Token → This token grants restricted API access to the enterprise.
4. Enterprise shares user data → The system uses the token to send employee/customer details, registering them for healthcare or insurance benefits.

Why Use Client Credentials Flow?

• No user interaction required – Ideal for automated server-to-server authentication.
• Secure enterprise access – Only authorized businesses can access data.
• Controlled API access – Limits what enterprises can do based on their role.

In ColdFusion, you can use the cfoauth tag or the GetOauthAccessToken function to integrate with any OAuth service provider and access their services, for more information refer to cfoauth.