Dynamically Add Functionality to an Authentication Provider
For the most flexibility with authentication provider functionality, create your own URL parameter forwarding allowlist. With an allowlist, you can dynamically add allowlisted parameters to your client configuration URLs at runtime and forward them to the third-party provider. For example, forward the user's language preferences to the third-party provider so that the provider's login page displays in the user's desired language.
Required Editions
| Available in: Enterprise, Performance, Unlimited, and Developer Editions |
| User Permissions Needed | |
|---|---|
| To view authentication provider settings: | View Setup and Configuration |
| To edit authentication provider settings: | Customize Application AND Manage Auth. Providers |
When you initialize an authentication provider single sign-on flow by invoking a client configuration URL, Salesforce's generates an authorization URL where the user is redirected to log in to the third-party provider. When you allowlist a URL forwarding parameter, you can dynamically add it to the client configuration URL when you invoke it. The parameter then gets forwarded to the third-party provider as part of the authorization URL.
Because you can allowlist any URL parameter you want, there are many ways you can use this feature to dynamically invoke different experiences on third-party providers.
For example, use this feature to control the language for the third-party provider's login page.
Picture an Experience Cloud site where users select their language preference by clicking a
button. They're then redirected to your site's login page, where they have an option to log in
with Google via a third-party provider. You want to forward the user's language preference to
Google so that Google knows what language to display for the login page. So you allowlist the
ui_locales parameter. Then you develop your site so that
when the user selects their language preference, your site stores it in a cookie. If the user
chooses to log in with Google, your site pulls the value from the cookie, stores it in the
ui_locales parameter, and dynamically adds the parameter
to the authentication provider single sign-on initialization URL. The ui_locales parameter then gets forwarded as part of the
authorization URL from Salesforce to Google. At this point, the user is redirected to Google's
login page. Thanks to the ui_locales parameter, the login
page displays in their preferred language.
Here's another example of how you can use this feature to add functionality. Say that you have a
login page where users can optionally click a button to log in with Google. You know that some
users have multiple Google accounts and that Google can prompt them to select an account before
they can finish logging in. You want to help users skip this step, so you add an option on the
login page where they can enter their email address before logging in with Google. Then you
allowlist the login_hint parameter. If the user enters
their email address, you use the login_hint parameter to
store it. Then, when they click the option to log in with Google, you dynamically add the
login_hint parameter to the single sign-on initialization
URL. The parameter gets forwarded to the authorization URL. When the user is directed to Google,
Google already knows which account they want to use.
To allowlist an authentication provider forwarding parameter, use Metadata API. Here's an example
of how you can use Salesforce CLI to create a Google authentication provider via Metadata API
and allowlist ui_locales and login_hint parameters. Before you get started, make sure you install Salesforce CLI if you don't have it already.
- Enable your org as a Dev Hub.
- Create a Salesforce DX project.
- Authorize your org.
- Build a scratch org definition file.
- To verify that you created the scratch org correctly, run this CLI command.
.sf org open -o <your scratch org name> - In your Salesforce DX project directory, create a directory called AuthProviders.
- In the AuthProviders directory, create a file named
package.xmlwith this content.<Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>*</members> <name>AuthProvider</name> </types> <version>62.0</version> </Package> - In the AuthProviders directory, create a subdirectory named authproviders.
- In the authproviders subdirectory, create a file named
<yourauthprovidername>.authproviderwith this content.<AuthProvider xmlns="http://soap.sforce.com/2006/04/metadata"> <friendlyName>MyAuthProvider</friendlyName> <includeOrgIdInIdentifier>false</includeOrgIdInIdentifier> <isPkceEnabled>true</isPkceEnabled> <providerType>Google</providerType> <requireMfa>false</requireMfa> <sendAccessTokenInHeader>false</sendAccessTokenInHeader> <sendClientCredentialsInHeader>false</sendClientCredentialsInHeader> <sendSecretInApis>true</sendSecretInApis> <paramForwardAllowlist> <description>Stores the user's language preferences</description> <param>ui_locales</param> </paramForwardAllowlist> <paramForwardAllowlist> <description>Stores the user's email address</description> <param>login_hint</param> </paramForwardAllowlist> </AuthProvider> - To deploy the authentication provider to your scratch org, navigate back to the Salesforce
DX project directory and run this CLI command.
sf project deploy start --metadata dir AuthProvidersWhen the command is executed, it creates an authentication provider in your org with theui_localesandlogin_hintparameters allowlisted. Add these parameters to your client configuration URLs and customize your provider's functionality as desired.
