--- schema_version: "1" id: 2a8f4e407df2ff602f31bd6d3c29c36f9c8cddd250b9d96d5065a854383f3cd9 title: ConnectedAppPlugin Class collection: legacydeveloper version: current locale: en-us portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/apexref/apex_class_Auth_ConnectedAppPlugin.md canonical_url: https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm source_site: developer.salesforce.com content_type: documentation content_hash: ee5157716fcc35d223ff5eceb668a82ec5dc2e4c02efb975dd5d2b84f0becfd7 description: Contains methods for extending the behavior of a connected app, for example, customizing how a connected app is invoked depending on the protocol used. This class gives you more control over the interaction between Salesforce and your connected app.Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use authorize(userId, connectedAppId, isAdminApproved, context) instead.Authorizes the specified user to access the connected app. If the connected app is set for users to self-authorize, this method isn’t invoked.Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use customAttributes(userId, connectedAppId, formulaDefinedAttributes, context) instead.Sets new attributes for the specified user. When the connected app gets the user’s attributes from the UserInfo endpoint or through a SAML assertion, use this method to update the attribute values.Modifies the XML generated by the Salesforce SAML Identity Provider (IDP) before it’s sent to the service provider.Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use refresh(userId, connectedAppId, context) instead.Salesforce calls this method during a refresh token exchange. --- # ConnectedAppPlugin Class Contains methods for extending the behavior of a connected app, for example, customizing how a connected app is invoked depending on the protocol used. This class gives you more control over the interaction between Salesforce and your connected 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 a connected app, you specify general information about the app and settings for OAuth, web apps, mobile apps, and canvas apps. To customize how the app is invoked, create a connected app handler with this ConnectedAppPlugin Apex class. For example, use this class to support new authentication protocols or respond to user attributes in a way that benefits a business process. When you create a connected app handler, you also configure the ConnectedAppPlugin class to run as an execution user. The execution user authorizes access for the connected app. For example, when you use the authorize method, the execution user authorizes the connected 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 ConnectedAppPlugin methods require that you specify an execution user, with the exception of the customAttributes method. For more information, see [Create a Custom Connected App Handler](https://help.salesforce.com/articleView?id=xcloud.connected_app_create_custom_handler.htm&type=5&language=en_US "HTML (New Window)"). ## Example This example authorizes the connected app user to use the connected app if the context is SAML and the user has reached the quota tracked in a custom field. It returns the user’s permission set assignments. The example uses Auth.InvocationContext to modify a SAML assertion before it’s sent to the service provider. global without sharing class ConnectedAppPluginExample extends Auth.ConnectedAppPlugin { // Authorize the app if the user has achieved quota tracked in a custom field global override Boolean authorize(Id userId, Id connectedAppId, Boolean isAdminApproved, Auth.InvocationContext context) { // Create a custom boolean field HasAchievedQuota\_\_c on the user record // and then uncomment the block below // User u = \[select id, HasAchievedQuota\_\_c from User where id =: userId WITH SYSTEM\_MODE\].get(0); // return u.HasAchievedQuota\_\_c; return isAdminApproved; } // Call a flow during refresh global override void refresh(Id userId, Id connectedAppId, Auth.InvocationContext context) { try { Map inputVariables = new Map(); inputVariables.put('userId', userId); inputVariables.put('connectedAppId', connectedAppId); // Create a custom trigger ready flow and uncomment the block below // Flow.Interview.MyCustomFlow interview = new Flow.Interview.MyCustomFlow(inputVariables); // interview.start(); } catch ( Exception e ) { System.debug('FLOW Exception:' + e); } } // Return a user’s permission set assignments global override Map customAttributes(Id userId, Id connectedAppId, Map formulaDefinedAttributes, Auth.InvocationContext context) { List psas = \[SELECT id, PermissionSet.Name FROM PermissionSetAssignment WHERE PermissionSet.IsOwnedByProfile = false AND (AssigneeId = :userId) WITH SYSTEM\_MODE\]; String permsets = '\['; for (PermissionSetAssignment psa :psas) { permsets += psa.PermissionSet.Name + ';'; } permsets += '\]'; formulaDefinedAttributes.put('PermissionSets', permsets); return formulaDefinedAttributes; } } - **[ConnectedAppPlugin Methods](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_methods)** ## ConnectedAppPlugin Methods The following are methods for ConnectedAppPlugin. - **[authorize(userId, connectedAppId, isAdminApproved)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_authorize)** Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use authorize(userId, connectedAppId, isAdminApproved, context) instead. - **[authorize(userId, connectedAppId, isAdminApproved, context)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_authorize_2)** Authorizes the specified user to access the connected app. If the connected app is set for users to self-authorize, this method isn’t invoked. - **[customAttributes(userId, connectedAppId, formulaDefinedAttributes)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_customAttributes)** Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use customAttributes(userId, connectedAppId, formulaDefinedAttributes, context) instead. - **[customAttributes(userId, connectedAppId, formulaDefinedAttributes, context)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_customAttributes_2)** Sets new attributes for the specified user. When the connected app gets the user’s attributes from the UserInfo endpoint or through a SAML assertion, use this method to update the attribute values. - **[modifySAMLResponse(authSession, connectedAppId, samlResponse)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_modifySAMLResponse)** Modifies the XML generated by the Salesforce SAML Identity Provider (IDP) before it’s sent to the service provider. - **[refresh(userId, connectedAppId)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_refresh)** Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use refresh(userId, connectedAppId, context) instead. - **[refresh(userId, connectedAppId, context)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Auth_ConnectedAppPlugin.htm#apex_Auth_ConnectedAppPlugin_refresh_2)** Salesforce calls this method during a refresh token exchange. ### authorize(userId, connectedAppId, isAdminApproved) Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use authorize(userId, connectedAppId, isAdminApproved, context) instead. #### Signature public Boolean authorize(Id userId, Id connectedAppId, Boolean isAdminApproved) #### 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 connected app. - **connectedAppId**: 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.") The 15-character ID of the connected 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 connected app requires approval. #### 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.") If the connected app requires admin approval, a returned value of true indicates that the current user is approved. ### authorize(userId, connectedAppId, isAdminApproved, context) Authorizes the specified user to access the connected app. If the connected app is set for users to self-authorize, this method isn’t invoked. #### Signature public Boolean authorize(Id userId, Id connectedAppId, 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 connected app. - **connectedAppId**: 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 connected 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 connected app requires approval. - **context**: Type: [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 connected 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.") If the connected app requires admin approval, a returned value of true indicates that the user is approved. #### Usage ConnectedAppPlugin runs on behalf of the current user. But the user must have permission to use the connected app for the plug-in to work. Use this method to authorize the user. ### customAttributes(userId, connectedAppId, formulaDefinedAttributes) Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use customAttributes(userId, connectedAppId, formulaDefinedAttributes, context) instead. #### Signature public Map customAttributes(Id userId, Id connectedAppId, Map formulaDefinedAttributes,) #### 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 connected app. - **connectedAppId**: 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 connected 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 new set of attributes from the UserInfo endpoint (OAuth) or from a SAML assertion. For more information, see [The UserInfo Endpoint](https://help.salesforce.com/HTViewHelpDoc?id=remoteaccess_using_userinfo_endpoint.htm&language=en_US "HTML (New Window)") in the online help. #### 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. ### customAttributes(userId, connectedAppId, formulaDefinedAttributes, context) Sets new attributes for the specified user. When the connected app gets the user’s attributes from the UserInfo endpoint or through a SAML assertion, use this method to update the attribute values. #### Signature public Map customAttributes(Id userId, Id connectedAppId, Map 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 connected app. - **connectedAppId**: 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 connected 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](https://help.salesforce.com/HTViewHelpDoc?id=remoteaccess_using_userinfo_endpoint.htm&language=en_US "HTML (New Window)") in the online help. - **context**: Type: [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 connected 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. ### modifySAMLResponse(authSession, connectedAppId, samlResponse) Modifies the XML generated by the Salesforce SAML Identity Provider (IDP) before it’s sent to the service provider. #### Signature public dom.XmlNode modifySAMLResponse(Map authSession, Id connectedAppId, dom.XmlNode samlResponse) #### Parameters - **authSession**: 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.")\> The attributes for the authorized user’s session. The map includes the 15-character ID of the authorized user who’s accessing the connected app. - **connectedAppId**: 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 connected app. - **samlResponse**: Type: [Dom.XmlNode](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_xml_dom_xmlnode.htm#apex_classes_xml_dom_xmlnode "Use the XmlNode class to work with a node in an XML document.") Contains the SAML XML response generated by the IDP. #### Return Value Type: [Dom.XmlNode](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_xml_dom_xmlnode.htm#apex_classes_xml_dom_xmlnode "Use the XmlNode class to work with a node in an XML document.") Returns an instance of Dom.XmlNode containing the modified SAML XML response. #### Usage Use this method to modify the XML SAML response to perform an action based on the context of the SAML request before it’s verified, signed, and sent to the target service provider. This method enables developers to extend the connected app plug-in to meet their specific needs. The developer assumes full responsibility for changes made within the connected app plug-in. The plug-in must include validation and error handling. If the plug-in throws an exception, catch it, log it, and stop the process. Don’t send anything to the target service provider. ### refresh(userId, connectedAppId) Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use refresh(userId, connectedAppId, context) instead. #### Signature public void refresh(Id userId, Id connectedAppId) #### 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. - **connectedAppId**: 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 connected app. #### Return Value Type: void ### refresh(userId, connectedAppId, context) Salesforce calls this method during a refresh token exchange. #### Signature public void refresh(Id userId, Id connectedAppId, 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. - **connectedAppId**: 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 connected app. - **context**: Type: [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 connected app is invoked. #### Return Value Type: void