User Agent Flow

User Agent Flow

Introduction

User Agent Flow is an OAuth 2.0 authorization flow designed primarily for single-page applications (SPA) and mobile applications where a backend server is not available to securely store client secrets. This flow allows users to authenticate and authorize applications by directly interacting with the authorization server.

Learning Objectives

By the end of this article, you will learn:

  • What User Agent Flow is and how it works in Salesforce.
  • When to use User Agent Flow.
  • How it differs from other OAuth flows like Web Server Flow.
  • Step-by-step implementation of User Agent Flow in Salesforce.
  • Common mistakes and best practices.

What is User Agent Flow?

User Agent Flow is an OAuth 2.0 authorization flow that enables users to log in and authorize an application via a web browser or mobile app. The authorization server (Salesforce) directly returns an access token to the client application via the browser, eliminating the need for a backend server to exchange authorization codes.

Why Use User Agent Flow?

  • Best suited for applications that cannot securely store client secrets, such as JavaScript-based SPAs or mobile apps.
  • Provides a straightforward way to obtain an access token without requiring backend server interactions.
  • Reduces complexity for frontend-heavy applications.

When to Use User Agent Flow?

Use this flow when:

  • The application runs in a web browser or mobile environment.
  • You do not have a secure backend server to store client secrets.
  • You need to obtain access tokens quickly for API calls.

How User Agent Flow Works

The User Agent Flow follows these steps:

  1. User Initiates Authentication:
    The user clicks the login button in the client application, which redirects them to the Salesforce authorization endpoint.
  2. Authorization Request:
    The application sends an authorization request to Salesforce using a URL in the following format: https://login.salesforce.com/services/oauth2/authorize? response_type=token& client_id=YOUR_CLIENT_ID& redirect_uri=YOUR_REDIRECT_URI& scope=full& state=optional_state
  3. User Logs In & Grants Permission:
    • Salesforce prompts the user to log in.
    • If it’s the first time authorizing, the user must approve the requested permissions.
  4. Salesforce Redirects with Access Token:
    Once authorized, Salesforce redirects the user back to the redirect_uri with the access token included in the URL fragment: https://yourapp.com/callback#access_token=ACCESS_TOKEN&instance_url=INSTANCE_URL&expires_in=3600
  5. Client Parses the Access Token:
    The frontend application extracts the access token from the URL and uses it to make API requests to Salesforce.
  6. Using the Access Token:
    The application includes the access token in the Authorization header of API requests: Authorization: Bearer ACCESS_TOKEN

Implementation in Salesforce

Step 1: Create a Connected App in Salesforce
  1. Navigate to Setup > App Manager in Salesforce.
  2. Click New Connected App.
  3. Fill in the required details:
    • Connected App Name: My Web App
    • API Name: My_Web_App
    • Contact Email: your@email.com
  4. Enable OAuth Settings:
    • Check Enable OAuth Settings.
    • Set the Callback URL (e.g., https://yourapp.com/callback).
    • Select OAuth Scopes (Full access (full), Perform requests on your behalf at any time (refresh_token, offline_access)).
  5. Save the app and copy the Consumer Key.
Step 2: Build the Authorization URL

Construct the authorization URL using the Consumer Key:

https://login.salesforce.com/services/oauth2/authorize?
response_type=token&
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
scope=full
Step 3: Implement Redirect Handling in Your Application

In your frontend JavaScript application, extract the access token from the URL fragment:

function getAccessToken() {
    const hash = window.location.hash.substring(1);
    const params = new URLSearchParams(hash);
    return params.get('access_token');
}

const accessToken = getAccessToken();
console.log("Access Token:", accessToken);
Step 4: Make API Calls to Salesforce

Once you have the access token, use it to call Salesforce APIs:

fetch("https://yourInstance.salesforce.com/services/data/v60.0/sobjects/Account", {
    method: "GET",
    headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Content-Type": "application/json"
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Advantages and disadvantages

advantages

  1. Fast & Direct Access – No backend needed! The access token is received instantly, reducing complexity.
  2. Perfect for SPAs & Mobile – Ideal for browser-based and mobile apps where storing secrets securely is not an option.
  3. Simple Implementation – Just a frontend, a few redirects, and you’re set to call Salesforce APIs!

disadvantages

  1. Security Risks – Access token appears in the URL, making it prone to exposure and interception.
  2. No Refresh Token – Users must re-authenticate frequently since refresh tokens aren’t provided.
  3. Limited Control – Tokens are managed on the client-side, increasing the risk of misuse if not handled properly.

Common Mistakes and Tips

  • Mistake 1: Forgetting to Enable OAuth Settings:
    Without enabling OAuth settings in the Connected App, the flow won’t work.
    • Tip: Use HTTPS to prevent interception of access tokens.
  • Mistake 2: Incorrect Redirect URI:
    Ensure that the redirect_uri in your authorization request matches the one configured in the Connected App.
    • Tip: Store access tokens securely using browser storage mechanisms like sessionStorage.
  • Mistake 3: Not Handling Token Expiry:
    The access token expires after a certain period (typically 1 hour). Implement a refresh token strategy or re-authentication mechanism.
    • Tip: Implement logout functionality to revoke access tokens when needed.
  • Mistake 4: Exposing Sensitive Data in URLs:
    Since the access token is returned in the URL, avoid logging it or storing it in an insecure location.
    • Tip: Use the state parameter to mitigate CSRF attacks.

Summary

  • User Agent Flow is designed for SPAs and mobile applications where client secrets cannot be securely stored.
  • The flow involves user authentication via Salesforce, which redirects with an access token.
  • Implementation involves creating a Connected App, building an authorization URL, handling the access token in the frontend, and making API calls.
  • Common mistakes include misconfiguring the redirect URI, failing to handle token expiration, and exposing sensitive data.

Quiz / Self-Assessment

  1. What is the primary use case for User Agent Flow?
  2. Why doesn’t User Agent Flow require a client secret?
  3. What OAuth parameter is used to return the access token in the authorization response?
  4. How can you securely store the access token in a web application?
  5. What is a potential security risk of User Agent Flow, and how can you mitigate it?

Conclusion

User Agent Flow provides a straightforward way to authenticate and authorize users in browser-based applications. By following best practices, developers can implement it securely and efficiently in their Salesforce applications.

Additional Resources

https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_web_server_flow.htm&type=5

Scroll to Top