Docs

Execute an Authorization Code Grant Flow with PKCE

Pass Parameters to Identity Providers

You can pass provider-specific parameters to an Identity Provider, during authentication.

The values can either be static per connection or dynamic per user.

Note the following restrictions:

  • Only valid OAuth 2.0/OIDC parameters are accepted.
  • Not all Identity Providers support upstream parameters. Check with the specific Identity Provider before you proceed with your implementation.

1. Create a Code Verifier

Static parameters

You can configure static parameters per connection with the Connections endpoints of our Management API. Each time your connection is used, the specified parameters will be sent to the Identity Provider.

When you create or update a connection, use the upstream_params element of the options attribute.

2. Create a Code Challenge

Example: WordPress

As an example, let's use WordPress, which allows you to pass an optional blog parameter to its OAuth 2.0 authorization endpoint (for more information, see WordPress's OAuth 2.0 documentation).

Let's assume that you have a working WordPress connection and you want to always request that users have access to the myblog.wordpress.com blog when logging in with it. To do this, assign WordPress's blog parameter a default value of myblog.wordpress.com.

First, we will use the Get Connection endpoint, to retrieve the existing values of the options object. This is mandatory since the Update Connection endpoint, which we will use next, overrides this object will be overridden, so if parameters are missing they will be lost after the update.




Let's say that the options contents for our wordpress connection are the following:

Now we can send the update request, copying the existing options contents and adding also the blog parameter.




Now every time a user authenticates with this connection the request to Wordpress will include the query parameter blog=myblog.wordpress.com.

3. Get the User's Authorization

Dynamic parameters

You can configure upstream parameters per user. This way when a user authenticates, the parameters will be dynamically added to the authorization query.

To do this, use the upstream_params element of the options attribute to specify a mapping between one of the existing accepted parameters to the parameter accepted by the Identity Provider.

4. Exchange the Authorization Code for an Access Token

Field list

Here are fields available for the enum parameter:

  • acr_values
  • audience
  • client_id
  • display
  • id_token_hint
  • login_hint
  • max_age
  • max_age
  • prompt
  • resource
  • response_mode
  • response_type
  • ui_locales

5. Call the API

Example: Twitter

As an example, let's use Twitter, which allows you to pass an optional screen_name parameter to its OAuth authorization endpoint (for more information, see Twitter's API reference).

To continue, you should already have a working Twitter connection; to learn how to configure one, see Connect Your App to Twitter.

Twitter's screen_name parameter pre-fills the username input box of the login screen with the given value, so we want to map it to the existing accepted parameter of login_hint.

Let's assume that you already retrieved the contents of the options object (like we did in the previous paragraph) and they are the following:

Send the update request, copying the existing options contents and adding also the screen_name parameter.




Now, when you call the Authorize endpoint for a specific user, you can pass their email address in the login_hint parameter.

And that value will in turn be passed along to the Twitter authorization endpoint in the screen_name parameter.