Solution guides

11 mins read

Electronic Consent Based Verification Service - Accelerate Adoption with Cloudentity

The Electronic Consent Based Verification Service (eCBSV) is an electronic service launched by the US Social Security Administration (SSA) that offers registered entities, such as financial service providers, banks, etc the ability to confirm the social security number of their customers, with the customer consent.

eCBSV overview

Synthetic identity fraud happens when fraudulent financial accounts are opened by creating fake identities with a combination of real and fake identity information. eCBSV was launched by SSA to enable financial service providers to combat synthetic identity fraud by allowing the providers to confirm the ownership of Social Security Number (SSN).

eCBSV high level

Entities such as banks or financial institutions need to register with eCBSV to use the services. Once the registration is approved by SSA, the entities are referred to as permitted entities. With the consent of the SSN holder, permitted entities can use the eCBSV to verify if the details associated with SSN match the provided name and date of birth. The service responds with match/no match and does not provide any SSNs or other identifiable information. The verification is only to ensure all the provided details match the SSA records but does not in any way authenticate the identity of the SSN holder or prove that the holders are who they claim to be.

Permitted entities must obtain and maintain the customer (SSN holder) consent either with an electronic signature or a wet signature to use the eCBSV service. Details about the requirements related to written consent can be found in the official eCBSV User Agreement. Under the eCBSV process, the permitted entity does not need submit the number holder’s consent forms to SSA. SSA requires each permitted entity to retain a valid consent for each SSN verification request submitted for 5 years. The agency permits the permitted entity to retain the consent in an electronic format.

Secure & Trusted Data access

In technical terms, the Permitted Entity should integrate with SSA’s entity services using Identity federation. SSA uses OpenID Connect and OAuth 2.0 specifications for authentication and authorization to protect the eCBSV Verification API access. To access eCBSV securely, permitted entities must have the technological capabilities to:

  • Support all the required OpenID Connect/OAuth 2.0 configurations
  • Expose JWKS endpoints for exposing signing keys
  • Expose OAuth Dynamic Client Registration endpoints
  • Provide advanced token signing algorithms
  • Provide signing & encryption key rotations and revocations
  • Assign and manage all end-user permissions, which are provided as attributes in the OpenID connect assertion.

In short, the Verification API access is based on the OAuth Open Standards approach and some advanced OAuth specifications. Cloudentity supports and is also certified in all of the advanced OAuth, OIDC, and Financial Grade API specifications as defined by the OpenID Foundation (OIDF).

Cloudentity as eCBSV adoption enabler

Cloudentity provides the capabilities required by Permitted entities to meet the eCBSV technical specification requirements and securely authorize the verification API request on behalf of users by Permitted entities. Entities wanting to use eCBSV are required to comply with the above specifications before attempting to complete the eCBSV online registration.

Let’s take a look at all the actors and systems involved to integrate with the eCBSV service and how Cloudentity abstracts away some of the complexities from the Permitted Entity core services.

eCBSV oidc workflows

There are 3 main personas involved in the eCBSV journey

  • End user/customer(SSN Holder)

    Cloudentity facilitates Permitted Entities to store user consent to use eCBSV services for audit trails and other events and provides APIs to ensure the user consent is in place before triggering a verification service API call on behalf of the SSN holder.

  • Permitted entity authorized users

    Permitted entity authorized users are the users that request SSN holder SSN verification. These users request verification on behalf of other SSN holders provided the SSN holders have given consent to Permitted Entity to perform SSN verification.

  • Permitted entity admins

    Permitted entity admins are a subset of authorized users within the Permitted entity ecosystem that have access to the eCBSV customer connection portal. SSA requires the permitted entity to provide Identity federation to allow such users from the permitted entity to access the eCBSV portal. Cloudentity provides all the identity federation for SSA on behalf of the permitted entity and also provides fine grained authorization control using policies on what kind of users are authorized to access the eCBSV portal.

Identity provider Integration

Cloudentity integrates with any of your existing identity providers seamlessly to perform user authentication. For eCBSV integration usecases, it would be any of the above user personas that may require user authentication. If you don’t have an existing system or you want to move to much lighter and faster identity provider, Cloudentity provides the identity pool functionality to host all the users with varying level of segmentation and custom attributes that will fit most of the requirements at high scale.

eCBSV permitted entity user identity provider

In a nutshell, the Cloudentity platform facilitates and accelerates the eCBSV service adoption, integration, and consumption journey for all the personas and systems involved. Cloudentity systems also provide additional authorization capabilities to ensure your systems are secure and compliant with all the requirements and also support any future evolution of evolving Open Standard specifications in the OIDF space.

With Cloudentity, your organization:

  • Can integrate with eCBSV interfaces faster
  • Can be out of the box compliant with eCBSV integration requirements
  • Gets consent management APIs out of the box to store user consent
  • Gets an OIDC certified and advanced OAuth server built for cloud scale
  • Can offload the identity federation requirements completely
  • Can offload the key management and other complex OIDC requirements
  • Can lower the overall eCBSV integration implementation & maintenance cost

Securely Integrate with eCBSV using Cloudentity

eCBSV Integration profile compliance can be enabled in the Cloudentity platform by choosing a compliant workspace and then configuring it to meet all eCBSV requirements and achieve compliance.

eCBSV workspace

Once the workspace (that includes an OAuth Authorization server instance) is created within Cloudentity, you get a workspace that satisfies all the items listed by eCBSV. Let’s dive deeper into some of the technical specifications required by eCBSV from the provider.

All the endpoints exposed by Cloudentity utilize TLS 1.2+ version. Within Cloudentity vanity domains can be configured to use the Permitted entity domains. In such a setup the permitted entity domain should have EV SSL certificates as recommended by eCBSV

Cloudentity publishes all the supported endpoints and other elements as specified in OIDC specification and as required by eCBSV in the OIDC well_known discovery endpoint which includes:

  • Token endpoint
  • UserInfo endpoint
  • Registration endpoint
  • Grant types supported - authorization_code for DCR clients
  • Token endpoint authentication method supported - client_secret_post
  • userinfo_signing_alg_values_supported - RS256
  • claim_types_supported

Detailed workflow that utilizes the OAuth/OIDC specifications as required by eCBSV and how Cloudentity offloads specific requirements within the ecosystem to address those requirements are shown below:


eCBSV OAuth/OIDC Compliance with Cloudentity

Let’s dive into the important configuration and specific OIDC/OAuth requirements required by eCBSV. As you can see below, Cloudentity goes above and beyond to meet the all requirements for these specifications. Cloudentity is an OIDC certified advanced FAPI-grade authorization server with configuration flexibility up to date with most of the advanced OAuth specifications.

  • OIDC Claims and scopes

    Cloudentity can be configured to release all the scopes and claims expected by eCBSV. Expected scopes are openid, email, and roles. The role’s scope claim should contain the ssa-ecbsv-account-representative value. Cloudentity allows flexible ways to add new scopes and can also allow dynamic configurable mapping for values

  • Signing algorithm

    Cloudentity supports both ECDSA and RSA type signing algorithms (ECSDA by default). You can change the signing algorithm from ECSDA to RSA within the Cloudentity workspace OAuth server settings

  • Registration of entity within SSA

    Cloudentity has highly configurable Dynamic client registration(DCR) flows and easily meets the flows required by eCBSV. Cloudentity hosts a dynamic client registration endpoint as per OpenID Connect Dynamic Client Registration specifications and also supports authorization policies and initial access token configurations to restrict dynamic client registration requests to only SSA’s services.

    Cloudentity also offers a DCR governance policy that can be authored to restrict dynamic client registration calls to only be permitted from SSA source IP addresses in the CIDR block: as recommended by SSA.


    Cloudentity also supports all the REQUIRED values and following additional values as specified in the requirements - client_secret & client_secret_expires_at

    Another critical requirement for SSA that Cloudentity supports out of the box is to expire the client_secret to force re-authentication. If a client_secret is compromised, using Cloudentity admin UI/API the Oauth client secrets can be forcefully rotated.

  • End User Auth code flow initiated at SSA

    Cloudentity presents the user with an idp selection page, or just one identity provider that directly logs in case there is only one identity source and returns an authorization code. SSA auth backend retrieves the OAuth authorization code returned to customer UI by Cloudentity and makes an OAuth token request to fetch an access token and ID token from Cloudentity.

  • Machine to Machine flow initiated at SSA

    Cloudentity can generate signed JWT that contains information using regular client authentication methods and the signed JWT can be used as the client assertion by Permitted entity while communicating with the eCBSV service. The permitted entity must first call Cloudentity to fetch the signed JWT issued as an access token, extract the token, and pass the token value as client assertion to the eCBSV service via JWT Bearer grant flow to obtain SSA access token. SSA eCBSV service validates the client assertion signature in the JWT Bearer grant flow using Cloudentity’s JWKS URI; thereby eliminating the requirement for Permitted entity to maintain and host a key pair and JWKS endpoint for signature verification.

  • JSON Web Key Set (JWKS) Endpoint

    Cloudentity hosts a JSON Web Key Set (JWKS) endpoint that conforms to the specification and supports following requirements for eCBSV.

    • Key Algorithm

      Cloudentity has support for the KEYS that are required by the eCBSV specification, the RSASSA-PKCS1-v1_5 scheme and also specifies the use and alg attributes for the published keys as per requirements.

    • ID token signing

      Cloudentity uses the associated private key to sign any JSON Web Tokens (JWTs) (such as the ID token or user’s claims) when communicating with SSA. SSA utilizes the public keys to verify the signature of the JWT. Cloudentity maintains the private keys used for signing and keeps them not exposed to any other systems.


    • Key rotation

      Cloudentity supports the key rotation specification. As per SSA, the keys MUST EXPIRE after a maximum of 367 days and MUST be ROTATED accordingly. It is recommended that both the expiring and new keys are available during rotation to avoid interruption of the service. In Cloudentity, forced rotation is available for the existing keys and the last two keys are retained to avoid interruption of services. There is also a feature available to schedule rotation to avoid any manual work to rotate keys.

    • Compromised keys

      One of the critical requirements is in the case that a private key is compromised, the provider should take some actions and Cloudentity provides these also out of the box.

      • Delist the compromised key at the JWKS endpoint.
      • Generate a new public-private key pair and list the new public key at the JWKS endpoint.
  • Authorization Endpoint

    Cloudentity supports all the OAuth authorization requests mandatory values, as well as the following ADDITIONAL values, state, nonce, and login_hint. Cloudentity has rich extensions around login_hint support and can even redirect to any of the IDPs based on the IDP discovery extensions.

  • Token endpoint

    Cloudentity exposes a token endpoint as per specification and can be configured at the workspace level to configure the allowed authentication mechanisms required for SSA. SSA RP issues the authenticate token requests using the client_secret_post method and is natively supported.

  • UserInfo endpoint

    Cloudentity also hosts a UserInfo endpoint that uses JSON format and signs all UserInfo response objects. The content-type header for the HTTP response is application/jwt and the signed response content is configurable and, by default, includes iss (issuer) and aud (audience) claims as required by the specification.

As you can see, the above Cloudentity feature rich solution meets all the complex eCBSV requirements with ease. Leave the heavy lifting of keeping up to latest OAuth and emerging Open Standards to us and you can accelerate to build the business value of your solution.

eCBSV Integration guides

Feels like diving deep into all the OAuth/OIDC and other requirements for the eCBSV integrations? We have detailed guides to help you navigate the eCBSV adoption journey with ease.

Jump start the eCBSV adoption journey

Pick your style - SaaS vs non SaaS

Cloudentity has a SaaS region dedicated for US. If you want to host the solution yourself, we offer the same binary and tools that we use to run our SaaS infrastructure to your DevOps team. Your team can run our high scale solution on the infrastructure of your choice. Read about all the offered deployment models here

Consumer Data Right API Gateways

Register for free to get access to a Cloudentity tenant and experience the ease of eCBSV adoption journey with us!

Lets work together to reduce Synthetic identity fraud and build safe and secure systems that safeguard user privacy and consent.

Updated: Jan 20, 2023