---
schema_version: "1"
id: 05b92816db601ebc1ce5bdd98754904c1711fa3dd3a528e6a3cd66b149993a84
title: ExternalClientAppOauthHandler Class
collection: legacydeveloper
version: current
locale: en-us
portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/apexref/apex_class_Auth_ExternalClientAppOauthHandler.md
canonical_url: https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ExternalClientAppOauthHandler.htm
source_site: developer.salesforce.com
content_type: documentation
content_hash: 63d7e58cd392e25dcc19e7cb9b924ab95882f2673fca57864ccb5feb4f0874a4
description: Contains methods for extending the behavior of an external client app. For example, customize how an external client app is invoked depending on the protocol used. This class gives you more control over the interaction between Salesforce and your external client app.Authorizes the specified user to access the external client app. If the external client app is set for users to self-authorize, this method isn’t invoked.Sets new attributes for the specified user. When the external client app gets the user’s attributes from the UserInfo endpoint, use this method to update the attribute values.Salesforce calls this method during a refresh token exchange.
---
# ExternalClientAppOauthHandler Class

Contains methods for extending the behavior of an external client app. For example, customize how an external client app is invoked depending on the protocol used. This class gives you more control over the interaction between Salesforce and your external client app.

## Namespace

[Auth](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_namespace_Auth.htm "The Auth namespace provides an interface and classes for single sign-on into Salesforce and session security management.")

## Usage

When you create an external client app, you specify general information about the app and settings for OAuth. To customize how the app is invoked, create a external client app handler with the ExternalClientAppOauthHandler Apex class. For example, use this class to support new authentication protocols or respond to user attributes in a way that benefits the business process.

When you create an external client app handler, you also configure the ExternalClientAppOauthHandler class to run as an execution user. The execution user authorizes access for the external client app. For example, when you use the authorize method, the execution user authorizes the external client app to access data.

If you don't specify an execution user, the plug-in runs as an Automated Process User, which is a system user that executes tasks behind the scenes. Most ExternalClientAppOauthHandler methods require that you specify an execution user, with the exception of the customAttributes method.

- **[ExternalClientAppOauthHandler Methods](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ExternalClientAppOauthHandler.htm#apex_Auth_ExternalClientAppOauthHandler_methods)**

## ExternalClientAppOauthHandler Methods

The following are methods for ExternalClientAppOauthHandler.

- **[authorize(userId, ecAppId, isAdminApproved, context)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ExternalClientAppOauthHandler.htm#apex_Auth_ExternalClientAppOauthHandler_authorize)**  
    Authorizes the specified user to access the external client app. If the external client app is set for users to self-authorize, this method isn’t invoked.
- **[customAttributes(userId, ecAppId, formulaDefinedAttributes, context)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ExternalClientAppOauthHandler.htm#apex_Auth_ExternalClientAppOauthHandler_customAttributes)**  
    Sets new attributes for the specified user. When the external client app gets the user’s attributes from the UserInfo endpoint, use this method to update the attribute values.
- **[refresh(userId, ecAppId, context)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ExternalClientAppOauthHandler.htm#apex_Auth_ExternalClientAppOauthHandler_refresh)**  
    Salesforce calls this method during a refresh token exchange.

### authorize(userId, ecAppId, isAdminApproved, context)

Authorizes the specified user to access the external client app. If the external client app is set for users to self-authorize, this method isn’t invoked.

#### Signature

public Boolean authorize(Id userId, Id ecAppId, Boolean isAdminApproved, Auth.InvocationContext context)

#### Parameters

- **userId**:
    
    Type: [Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm#apex_methods_system_id "Contains methods for the ID primitive data type.")
    
    The 15-character ID of the user attempting to use the external client app.
- **ecAppId**:
    
    Type: [Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm#apex_methods_system_id "Contains methods for the ID primitive data type.")
    
    The 15-character ID of the external client app.
- **isAdminApproved**:
    
    Type: [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm#apex_methods_system_boolean "Contains methods for the Boolean primitive data type.")
    
    The approval state of the specified user when the external client app requires approval.
- **context**:
    
    Type: [Auth.InvocationContext](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_enum_Auth_InvocationContext.htm "The context in which the connected app is invoked, such as the protocol flow used and the token type issued, if any. Developers can use the context information to write code that is unique to the type of invocation.")
    
    The context in which the external client app is invoked.

#### Return Value

Type: [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm#apex_methods_system_boolean "Contains methods for the Boolean primitive data type.")

A returned value of true indicates that the user is approved.

### customAttributes(userId, ecAppId, formulaDefinedAttributes, context)

Sets new attributes for the specified user. When the external client app gets the user’s attributes from the UserInfo endpoint, use this method to update the attribute values.

#### Signature

public Map<String,String> customAttributes(Id userId, Id ecAppId, Map<String,String> formulaDefinedAttributes, Auth.InvocationContext context)

#### Parameters

- **userId**:
    
    Type: [Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm#apex_methods_system_id "Contains methods for the ID primitive data type.")
    
    The 15-character ID of the user attempting to use the external client app.
- **ecAppId**:
    
    Type: [Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm#apex_methods_system_id "Contains methods for the ID primitive data type.")
    
    The 15-character ID for the external client app.
- **formulaDefinedAttributes**:
    
    Type: [Map](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_map.htm#apex_methods_system_map "Contains methods for the Map collection type.")<[String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm#apex_methods_system_string "Contains methods for the String primitive data type."),[String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm#apex_methods_system_string "Contains methods for the String primitive data type.")\>
    
    A map of the current set of attributes from the UserInfo endpoint (OAuth) or from a SAML assertion. For more information, see The UserInfo Endpoint in the online help.
- **context**:
    
    Type: Auth.InvocationContext
    
    The context in which the external client app is invoked.

#### Return Value

Type: [Map](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_map.htm#apex_methods_system_map "Contains methods for the Map collection type.")<[String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm#apex_methods_system_string "Contains methods for the String primitive data type."),[String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm#apex_methods_system_string "Contains methods for the String primitive data type.")\>

A map of the updated set of attributes.

### refresh(userId, ecAppId, context)

Salesforce calls this method during a refresh token exchange.

#### Signature

public void refresh(Id userId, Id ecAppId, Auth.InvocationContext context)

#### Parameters

- **userId**:
    
    Type: [Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm#apex_methods_system_id "Contains methods for the ID primitive data type.")
    
    The 15-character ID of the user requesting the refresh token.
- **ecAppId**:
    
    Type: [Id](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_id.htm#apex_methods_system_id "Contains methods for the ID primitive data type.")
    
    The 15-character ID of the external client app.
- **context**:
    
    Type: Auth.InvocationContext
    
    The context in which the external client app is invoked.

#### Return Value

Type: void