Trusted providers

Our Trusted providers feature lets your ReachFive setup integrate with external Identity providers using OAuth 2.0 Token Exchange (RFC 8693). This feature allows your site to accept access tokens issued by a trusted provider and exchange them for tokens issued by ReachFive. By enabling seamless user session retrieval, trusted providers support single sign-on (SSO), simplify migrations, and enhance interoperability with partner ecosystems.

This feature is particularly valuable for organizations using Akamai or other custom providers for authentication, as it eliminates the need for users to re-authenticate when accessing resources protected by ReachFive. It also supports hybrid deployments and phased migrations, allowing you to leverage both the trusted provider and ReachFive Identity services simultaneously.

By exchanging external tokens for internal ones, you maintain full control over authorization policies, ensuring security and consistency.

trusted device flow

Token exchange grant type

To exchange an external provider’s access token (e.g., from Akamai) for a ReachFive token, use the token_exchange grant type with the /oauth/token endpoint. This grant type, part of the OAuth 2.0 Token Exchange protocol, is available for trusted providers configured in the ReachFive Console. It enables seamless authentication by validating the external token and issuing a new token for use within your ReachFive ecosystem.

Prerequisites

  • The feature must be enabled on your account by a ReachFive administrator.

  • You must enable the Allow token exchange from trusted external provider option on applicable First-party Identity clients.

  • You must have a Developer, Manager, or Administrator role.

Register a trusted provider

To configure a trusted provider in the ReachFive Console, you must enable the Token Exchange option and provide the necessary settings for the external provider.

Once configured, ReachFive can accept opaque access tokens from the trusted provider, validate them via the provider’s applicable user information endpoint, and issue new tokens for use within your ecosystem.

Follow these steps to register a provider.

  1. In your ReachFive Console, go to Settings  Trusted providers.

  2. Click Akamai (or Custom trusted provider).

    click akamai

    • Akamai

    • Custom trusted provider

    1. In the dialog, enter the following details:

      View from the ReachFive Console

      akamai details

      1. Client ID: The client identifier issued by the trusted provider.

      2. Client Secret: The corresponding secret for the client ID, used to authenticate token exchange requests.

      3. Base URL: The HTTPs URL of the provider’s OAuth 2.0 endpoint (e.g., https://auth.akamai.com/userinfo). Ensure the URL is valid and matches the provider’s domain.

    1. In the dialog, enter the following details:

      View from the ReachFive Console

      custom details

      1. Client ID: The client identifier issued by the trusted provider.

      2. Client Secret: The corresponding secret for the client ID, used to authenticate token exchange requests.

      3. User info URL: The HTTPs URL of the provider’s equivalent user information URL (e.g., https://auth.example.com/userinfo). Ensure the URL is valid and matches the provider’s domain.

      4. Refresh Token URL: The HTTPs URL of the provider’s equivalent endpoint where the refresh token is obtained (e.g., https://auth.example.com/refreshToken). Ensure the URL is valid and matches the provider’s domain.

  1. Don’t forget to Save your input.

Add trusted provider variants

Variants allow you to configure multiple instances of a trusted provider (e.g., Akamai) for different environments, regions, or use cases, each with unique settings. Use variants to manage separate configurations, such as akamai_emea for EMEA-based services or akamai_apac for APAC-based services, to support regional endpoints, compliance, or testing.

You configure a variants in the same way as specified in the default instructions. The only different is you need to click the icon and name the variaent in snake_case (e.g., akamai_emea).

akamai variant

User events

A login user event is generated after a token exchange with a custom provider. When the event is emitted, it is added to the auth_types array on the user profile. The user event also appears on the user’s Recent activity filter and is present in the user profile’s provider_details.

{
  "date": "2025-06-09T16:17:00.183123Z",
  "auth_type": "token_exchange", (1)
  "id": "AWUTz0naD6KwGSiAAIMO",
  "type": "login",
  "canal": "identity_third_party",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile_id": "121146661725694",
  "login_time": "2025-06-09T16:17:00.183123Z",
  "client_id": "sg48CdAYohRPeRWZ9j1H",
  "provider": "akamai_emea", (2)
  "device": "desktop",
  "origin": "www.example.fr/login",
  "ip": "127.0.0.1",
  "host": "https://example.io",
  "job_execution_id": "iKUTe3lBd1MwSSbAmUJq",
  "job_type": "import",
  "job_name": "Daily imports",
  "login_as_profile_id": "AWUTz0JBD6KwGSiAAIMH",
  "updated_keys": [
    "login"
  ],
  "identifier_type": "email",
  "risk_score": 30,
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60"
}
1 Indicates a token exchange for authentication type authType.
2 Specifies it was through Akamai with an EMEA variant in this example akamai_emea.