Transcription
Electronic Consent BasedSSN Verification (eCBSV)ServiceTechnical Information GuideVersion 3.0Date: July 15, 2021
1 TABLE OF CONTENTS2INTRODUCTION . 4Overview and Background . 4Recommended Technical Expertise . 53REGISTRATION – TECHINCAL SPECIFICATIONS . 6Process Overview . 6Registration Flow . 7End-User Authorization Code Flow . 8Machine-to-Machine Flow. 9Full Systems Flow Diagram . 10Open ID Connect Provider . 11eCBSV OpenID Connect Requirements Summary . 12OIDC Discovery . 13Dynamic Client Registration Endpoint . 14JSON Web Key Set (JWKS) Endpoint . 15Authorization Endpoint . 16Token Endpoint. 17UserInfo Endpoint . 174REGISTRATION – TEST SERVICE . 18Entity OIDC URL Validation Tool . 18OIDC Validation Tool Screen Shots . 18OIDC Issuer URL Web Page Error Codes and Exception Handling . 21Successful Test and Next Steps . 235ENROLLMENT – CUSTOMER CONNECTION . 24Enrollment: Customer Connection Overview. 24Customer Connection: End-User Authorization Code Integration . 24Accessing the Customer Connection . 246VERIFICATION SERVICE – Authorization and Encryption . 25Machine-to-Machine Integration . 25Production Endpoint . 25Obtaining Access Token (M2M Flow) - Production. 25Sample Requests to Production Endpoint . 27Encryption Requirements - Production . 297VERIFICATION SERVICE – Requests and Responses . 322
Data Content for Request . 32Data Content for Response. 35eCBSV Error Codes and Exception Handling . 36Sample Requests and Reponses . 388VERIFICATION SERVICE – External Testing Environment . 42Overview . 42Register for ETE . 42Accessing eCBSV Service – External Testing Environment (ETE). 43ETE Test Data and Response Codes . 43Obtaining Access Token (M2M Flow) - ETE . 43Sample Request to ETE Endpoint . 44Encryption Requirements - ETE . 469HEALTH PING . 49Operation . 49Parameters . 49Responses . 5010CONTACT US . 52When to contact eCBSV Technical Support . 52eCBSV Technical Support Contact Information . 52What is needed when contacting eCBSV Technical Support . 5211CHANGE HISTORY . 53APPENDIX . 54Appendix A: Financial Institution Registration . 54Appendix B: Supported Certificate Authorities . 55Appendix C: eCBSV Screen Package . 57Appendix D: Acronyms . 58Appendix E: eCBSV ETE Test Data and Scenarios . 593
2 INTRODUCTIONOverview and BackgroundThe Social Security Administration’s (SSA) Electronic Consent Based SSN Verification (eCBSV) serviceprovides Permitted Entities with the capability to perform real-time Social Security Number (SSN)verifications. The eCBSV service is a Representational State Transfer (REST) service to verify whetherthe name, date of birth, and SSN obtained from a consenting Numberholder matches the data as itappears in SSA’s records. Additionally, if SSA’s records show that an individual is deceased, a deathindicator will be provided to the customer as part of the verification.In the Expanded Rollout, SSA will send email invitations to directly enroll in eCBSV to companieswho applied during the initial application period in July 2019. In the future, SSA may announceopen direct enrollment periods on its eCBSV website. The diagram displayed below provides a highlevel view of the steps required to use the eCBSV service:Figure - 2.1 Overview of required step to use eCBSVMore information about eCBSV program and business process may be found at the following link:https://www.ssa.gov/dataexchange/eCBSV/NOTE: Financial Institutions have the option to indirectly participate in theeCBSV program through a Service Provider. Please see Appendix A for moreinformation about the Indirect Registration for Financial Institutions.4
Recommended Technical ExpertiseSocial Security recommends that each entity wishing to directly enroll in the eCBSV programhave familiarity with the following concepts: Extended Validation SSL certificatesOpenID Connect specification (OIDC), including Discovery, Dynamic Client Registration, andAuthorization Code FlowJSON Web Tokens (JWTs)OAuth 2, including JWT client assertionUnderstanding of REST API requests and responses (JSON) and headersJSON Web Encryption (JWE)5
3 REGISTRATION – TECHINCAL SPECIFICATIONSProcess OverviewThe diagram displayed below provides the high-level steps required by an Entity to register to usethe eCBSV service:Figure 3.1 - Process Overview for Entity Registration6
Registration Flow(Refer to Figure 1 below)During registration of an Entity, the SSA system will: Verify that Extended Validation (EV) SSL certificates are in place at relevant domainsCreate an SSA client in the Entity's OIDC Identity Provider (IdP) through dynamic clientregistrationCreate a mapping from the Entity's email domain to the Entity's OIDC IdP login page tofacilitate the end-user authentication code flowCreate the Entity's OAuth Client ID in the SSA authentication layer and email it to the EntityFigure 1.2 - Registration Flow7
End-User Authorization Code Flow(Refer to Figure 2 below)In the end-user authorization code flow, displayed on the next page, the user is prompted to entera corporate email address at SSA's user interface. The user is redirected to the Entity's OIDC IdP,where they can present their credentials to obtain an authorization code. SSA's authentication layercan use the authorization code to obtain a token from the Entity's OIDC IdP to verify and allowaccess to the eCBSV Customer Connection portal.Figure 3.3 - Authentication Code Flow8
Machine-to-Machine Flow(Refer to Figure 3 below)In machine-to-machine flows, the Entity's client application creates a client assertion JSON WebToken (JWT) using a designated issuer URL and signing key (that the OIDC IdP serves at its JWKsendpoint). That JWT is presented to SSA's authentication layer to obtain an access token, which canthen be used in REST calls to eCBSV services along with the Exchange ID received after completingenrollment.Figure 3. 4 - Machine to Machine Flow9
Full Systems Flow Diagram(Refer to Figure 4 below)Figure 3.5 - Full System Flow10
Open ID Connect ProviderIn order to login with a corporate identity to access SSA's business services, entities are requiredto host an OpenID Connect Provider (OP) that supports the following capabilities: Dynamic Client Registration Authentication using the Authorization Code FlowREQUIRED: refer to the OIDC Technical Specifications in the table, eCBSV OpenIDConnect Requirements Summary, to ensure the requisite criteria are met toregister with eCBSV. In some cases, the OIDC Connect Configuration specificationsfor eCBSV differ from OIDC/JWT specifications.In order to support these features, the entity MUST host and implement the following endpoints: Well known OpenID Configuration Endpoint Dynamic Client Registration Endpoint JWKS Endpoint Authorization Endpoint Token Endpoint UserInfo EndpointThe entity MUST use Extended Validation (EV) SSL certificates for endpoint authentication andutilize TLS 1.21 for any communication with these endpoints. The Extended Validation (EV)certificate MUST conform to the specification defined in Entity Extended Validation CertificateRequirements and be issued from a supported certificate authority defined in Appendix B of thisdocument.NOTE: To successfully register, the entity’s company name and thecompany name on the EV certification MUST be an exact match.It is strongly recommended that entities use one of the many OpenID ConnectProvider products, SaaS Providers, or open source projects available that ALREADYmeet the requirements defined here, rather than attempting to develop their ownsolution.1TLS 1.3 will be required by January 1, 2024 as per NIST SP 800-52 Rev. 2 here. SSA may offer TLS 1.3 as an optionprior to that date.11
eCBSV OpenID Connect Requirements SummaryOIDC/JWT Specification ItemOIDC/JWT quirementNot required (TODO Reference)EV SSL CertificatesTLS is required. Version is notdictated.TLS 1.2(This is a NIST Requirement)ENDPOINTSEV SSL CertificatesTLSOIDC CONFIGtoken endpointREQUIRED unless only theImplicit Flow is usedREQUIRED becauseAuthorization Code Flow isuseduserinfo endpointRECOMMENDEDREQUIREDregistration endpointRECOMMENDEDREQUIREDNeeded to create Auth CodeSSA client at Entity IdPgrant types supportedtoken endpoint auth methods supportedDynamic OpenID Providers MUSTsupport the authorization codeREQUIREDOPTIONALREQUIREDMust containclient secret postscopes supportedRECOMMENDEDREQUIREDMust containopenid, email, rolesDYNAMIC CLIENT REGISTRATIONclient secretclient secret expires atOPTIONALREQUIRED for Auth Code FlowREQUIRED if client secret isissuedMUST be 012
JWKS ENDPOINTR256 sig keysNo specificationKeys must expire after 367days and rotateAUTHORIZATION REDCLIENT ASSERTION JWTKid (key)iss (issuer)Essentially optional. The kid mustbe available but not necessarilyvia JWKS endpoint or the JWKSendpoint as an IdP.REQUIREDSigned by a kid (key) availableat the JWKS EndpointREQUIRED, though notnecessarily an IdP Issuer URLiss (issuer) must match theOIDC IdP Issuer URLOIDC DiscoveryThe well-known OpenID Configuration endpoint MUST conform to Section 4.1 of the OpenIDConnect Discovery specification.The endpoint MUST respond to GET requests at the path /.well-known/openid-configurationand MUST serve a valid OpenID Configuration document as described in Section 4.2.The entity MUST support all the REQUIRED values described in Section 3 as well as the followingADDITIONAL values: token endpointThis value MUST be the URL of the Token endpoint (required to support the authorizationcode flow). userinfo endpointThis value MUST be the URL of the UserInfo endpoint. registration endpointThis value MUST be the URL of the Dynamics Client Registration endpoint. grant types supportedAt a minimum, the entity MUST support the authorization code grant type.13
scopes supportedAt a minimum, the entity MUST support the openid, email, and roles scopes. The role’s scopeshould contain the value ssa-ecbsv-account-representative.oEntities MUST ensure controls are in place to properly set attributes that allowAuthorized Users access to the eCBSV service. See the user agreement for moreinformation. userinfo signing alg values supportedAt a minimum, the entity MUST support the RS256 signing algorithm. token endpoint auth methods supportedAt a minimum, the entity MUST support the client secret post method. claim types supportedThe entity MUST support normal claims. If omitted, SSA assumes only normal claims. The SSARP will ignore distributed claims.Dynamic Client Registration EndpointThe entity MUST host a dynamic client registration endpoint in accordance with Section 3 of theOpenID Connect Dynamic Client Registration. The endpoint MUST use TLS 1.2 2 and MUST besecured using an EV SSL certificate. The URL for this endpoint MUST match the value of theregistration endpoint in the OpenID Connect configuration document.The entity may OPTIONALLY provide an Initial Access Token or other Authorization header duringentity registration which restricts dynamic client registration requests to only SSA’s services. Theentity may also restrict dynamic client registration calls to only be permitted from SSA source IPaddresses in the CIDR block: 137.200.0.0/16.The entity MUST support all the REQUIRED values described in Section 3.2 as well as the followingADDITIONAL values: client secretThis value along with the client id, MUST be unique for the SSA RP. Furthermore, this valueMUST be confidential and issued in accordance with Section 5.1.4.2.2 of RFC 6819.2TLS 1.3 will be required by January 1, 2024 as per NIST SP 800-52 Rev. 2 here. SSA may offer TLS 1.3 as an optionprior to that date.14
client secret expires atThis value is required to be 0, indicating that the client secret does not expire.If a client secret is compromised, the entity SHALL immediately take the following action: Notify SSA of the compromised client secret value.Expire the client secret to force re-authentication.JSON Web Key Set (JWKS) EndpointThe entity MUST host a JSON Web Key Set (JWKS) endpoint that conforms to the specificationdefined in Section 5 of RFC 7517. The endpoint MUST use TLS 1.2 and MUST be secured using anEV SSL certificate. The URL for this endpoint MUST match the value of jwks uri in the OpenIDConnect configuration document.The array of KEYS retrieved from the endpoint MUST contain at least ONE JSON Web Key (JWK)value that utilizes the RSASSA-PKCS1-v1 5 scheme as defined in Section 3.3 of RFC 7518.The entity MUST specify the following attribute values for the key(s): useThis value MUST be sig for the key.algThis value MUST be RS256 for the key.The entity OP must use the associated private key to sign any JSON Web Tokens (JWTs) (such as theid token or user's claims) when communicating with SSA. SSA will utilize the public keys to verifythe signature of the JWT. The entity must not disclose the private keys used for signing to any thirdparties.Finally, 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 be available during rotation to avoidinterruption of service.In the case that a private key is compromised, the entity SHALL immediately take the followingaction: Notify SSA immediately of the public key that corresponds to the compromised private key.Delist the compromised key at the JWKS endpoint.Generate a new public-private key pair (in accordance with the specifications describedabove) and list the new public key at the JWKS endpoint.15
Authorization EndpointThe entity MUST host an Authorization endpoint that conforms to the specification defined inSection 3.1.2 of OpenID Connect Core. The endpoint MUST use TLS 1.23 and MUST be secured usingan EV certificate. The URL for this endpoint MUST match the value of authorization endpoint in theOpenID Connect configuration document. The endpoint MUST support authentication usingAuthorization Code Flow as defined in Section 3.1.1 of OpenID Connect Core.The entity MUST support Authentication requests with all the REQUIRED values describedin Section 3.1.2.1 of OpenID Connect Core as well as the following ADDITIONAL values: stateThis value is used to mitigate Cross-Site Request Forgery (CSRF) attacks and MUST be passedas-is when the entity OP invokes the callback specified in the redirect uri Authenticationrequest parameter. nonceThe value is passed through unmodified from the Authentication request to the ID Token.The following value is RECOMMENDED in order to improve user experience: login hintThis is a hint about the login identifier that the end-user might use to log in (typically acorporate email address).If the end-user is authenticated successfully, the entity OP MUST respond to an Authenticationrequest with a valid success response in accordance with Section 3.1.2.5 of OpenID Connect Core.If the Authentication request object coming from the SSA Relying Party (RP) is invalid or there is anerror during authentication, the entity OP MUST respond with a valid error response as definedin Section 3.1.2.6 of OpenID Connect Core.3TLS 1.3 will be required by January 1, 2024 as per NIST SP 800-52 Rev. 2 here. SSA may offer TLS 1.3 as an optionprior to that date.16
Token EndpointThe entity MUST host a Token endpoint that conforms to the specification defined in Section 3.1.3of OpenID Connect Core. The endpoint MUST use TLS 1.2 and MUST be secured using an EVcertificate. The URL for this endpoint MUST match the value of token endpoint in the OpenIDConnect configuration document. The entity OP MUST validate all Token requests from the SSA RPin accordance with Section 3.1.3.2 of OpenID Connect Core. Furthermore, the endpoint MUSTauthenticate Token requests from the SSA RP using the client secret post method defined inSection 9 of OpenID Connect Core.If the Token request was successfully validated, the entity OP MUST respond with a valid successresponse in accordance with Section 3.1.3.3 of OpenID Connect Core.If the Token request object coming from the SSA RP is invalid or there is an error during validation,the entity OP MUST respond with a valid error response as defined in Section 3.1.3.4 of OpenIDConnect Core.UserInfo EndpointThe entity MUST host a UserInfo endpoint that conforms to the specification defined in Section 5.3of OpenID Connect Core. The endpoint MUST use TLS 1.2 4 and MUST be secured using an EVcertificate. The URL for this endpoint MUST match the value of userinfo endpoint in the OpenIDConnect configuration document. The entity OP MUST authorize all UserInfo requests from the SSARP via an OAuth 2.0 Bearer Token as specified in RFC 6750.If the UserInfo request was successfully authorized the entity OP MUST respond with a validUserInfo response in accordance with Section 5.3.2 of OpenID Connect Core. At a minimum, theentity OP MUST use JSON format and sign all UserInfo response objects. As such, the content-typeheader for the HTTP response MUST be application/jwt. As defined in the specification the signedresponse MUST include iss (issuer) and aud (audience) claims.If the UserInfo request object coming from the SSA RP is invalid or there is an error duringauthorization, the entity OP MUST respond with a valid error response as defined in Section 5.3.3of OpenID Connect Core.NOTE: Entities CANNOT move forward until technical development fromthis section has been completed4TLS 1.3 will be required by January 1, 2024 as per NIST SP 800-52 Rev. 2. SSA may offer TLS 1.3 as anoption prior to that date.17
4 REGISTRATION – TEST SERVICEEntity OIDC URL Validation ToolOnce an entity has met all prerequisites and completed their development as specified in Section3 of this document, the entity is highly encouraged to test prior to attempting to register inProduction. The entity’s OIDC URL and Dynamic Client Registration Authorization HeaderCredential should be tested to ensure there are no issues prior to attempting registration inproduction in order to prevent business downtime.A link to the OIDC URL Validation Tool is found here.OIDC Validation Tool Screen Shots1. Enter OIDC Provider Issuer URL18
2.Validation Successful3.Invalid Issuer URL Validation – Failure Message19
4.Enter Dynamic Client Registration Authorization Header Credentials (Optional)5.Validation Successful20
6.Validation FailureOIDC Issuer URL Web Page Error Codes and Exception HandlingThe test validation process will provide an Error Code with a corresponding http code indicatingthat there is a problem with the OIDC Issuer URL, the EV SSL certificate, and/or the DynamicClient Registration Authorization Header Credential.Error CodeError Code Descriptionhttp Code400.1.0The issuer URL must be a valid URL400400.1.1Failed GET request for the OIDC configuration400400.1.2The OIDC configuration is missing the following claim [field]400400.1.3The OIDC configuration claim [a field] must contain a value400400.1.4The JWKS at [URL] cannot be retrieved400400.1.5The JWKS must contain at least one key400400.1.6The JWKS should have a key with alg:RS256 and use:sig400400.1.7The following URL failed the SSL Validation Service [URL]400400.1.10Failed POST request for the Dynamic Client Registration Endpoint40021
400.1.11The Dynamic client registration response does not meet outrequirements. [A field] is null400400.1.12The Dynamic client registration response does not meet outrequirements.400400.1.14The issuer URL must be provided400400.1.15The domain name must be provided400400.2.0URL must not be empty400400.2.1URL must be a valid HTTPS URL400400.2.2A connection could not be established to the given URL400400.2.4The certificate at the given URL could not be parsed400400.2.5The certificates for the given URL could not be retrieved400400.2.6The certificate at the given URL is not an Extended ValidationCertificate from an SSA trusted Certificate Authority400400.2.7The certificate at the given URL is untrusted400400.2.8A connection could not be made to a valid hostname using theprovided URL400401Authentication Failure. Occurs when no valid bearer token is providedwith the request401403Authorization Failure. Occurs when a valid bearer token is providedwith the request, but the token does not have the role required toaccess the resource403404Not Found404500Internal Server Error50022
Successful Test and Next StepsWhen a successful validation message is displayed at the bottom of the screen the entity MUSTcomplete the following steps to continue with the registration process:1. Entity MUST delete the OAuth Client ID generated during validation testing2. Access the eCBSV Entity Registration webpage to register in production. The link to the eCBSV Entity Registration webpage can be found in the Expanded RollOut invitation email provided by the eCBSV mailbox. Screen shots of the Entity Registration webpage can be found in the eCBSV ScreenPackage (Appendix C)NOTE: To successfully register in Production, the entity’s company nameand the company name on the EV certification MUST be an exact match.23
5 ENROLLMENT – CUSTOMER CONNECTIONEnrollment: Customer Connection OverviewOnce successfully registered in production, the entity is ready to complete the eCBSV EnrollmentProcess in the eCBSV Customer Connection.The eCBSV Customer Connection is an automated workflow tool that will guide the entity through theenrollment process. During the enrollment process, the entity is required to provide their PermittedEntity Certification, sign the User Agreement, and purchase the Tier Subscription.The eCBSV Customer Connection screens can be viewed in the eCBSV Screen Package (Appendix C).More information about the eCBSV Enrollment process can be found on SSA’s eCBSV tomer Connection: End-User Authorization Code IntegrationIn the end-user authorization code flow, as displayed on the system diagram in Section 3.3, Figure1-2, the user is prompted to enter a corporate email address at SSA's eCBSV Registration. Whenattempting to access the eCBSV Customer Connect portal (URL provided in the next section), theuser is redirected to the Entity's OIDC IdP where they can present their corporate credentials to login. As part of the normal OIDC authorization code flow, and hidden to the user, a successful loginat their IdP allows the web browser to obtain an authorization code. Upon automatic browserredirection back to Customer Connect portal, SSA's authentication layer uses the authorization codeto obtain a token from the Entity's OIDC IdP to verify the user’s identity and to allow access to theeCBSV Customer Connection portal.Accessing the Customer ConnectionThe link to the eCBSV Customer Connection is as follows:eCBSV Customer 24
6 VERIFICATION SERVICE – AUTHORIZATION ANDENCRYPTIONMachine-to-Machine IntegrationI
a corporate email address at SSA's user interface. The user is redirected to the Entity's OIDC IdP, where they can present their credentials to obtain an authorization code. SSA's authentication layer can use the authorization code to obtain a token from the Entity's OIDC IdP to verify and allow access to the eCBSV Customer Connection portal.
