Email Validation

Email validation is the process of confirming that a user owns the email address he or she registered with NYC.ID. When a user registers with NYC.ID, his or her email address is un-validated. NYC.ID sends the user an email, which contains a validation link. Once the user clicks the validation link, his or her email address becomes validated. If a user registers with NYC.ID using a username, the user will not receive a validation email. A username is always un-validated.

NOTE: The validation link expires in two weeks.
! Important: A user may authenticate with a validated or an un-validated email address. This supports authentication with usernames.

 

Integrating Email Validation

Your application should consider the following scenarios when configuring user access:

  1. If your application does not require a validated user email address, then your application can skip the validation process. Two examples include:
    1. your application accepts usernames
    2. your application operates in a kiosk without Internet access
  2. If the user has an un-validated email address (i.e., "nycExtEmailValidationFlag" = FALSE), and your application requires a validated user email address, your application should:
    1. invoke the Email Validation Web Service1 to determine the current email address validation status, and
    2. if the value returned equals false, your application should send the user to this relative URL to request another validation email:

      GET /account/validateEmail.htm

      Parameter Name Parameter Description Optional/ Required
      emailAddress The email address of the user (include @noemail.nyc.gov for usernames) Required
      target

      The URI (encoded in Base64) that the user is sent to after completing the email validation process.

      The "target" query string parameter must have a domain name of doitt.nycnet, nyc.gov, nycid.nycnet, csc.nycnet, cloudapp.net, hpd.nycnet, nycgovparks.org, finance.nycnet, hpdnyc.org, cs.nycnet, gcomsoft.com, records.nycnet, dcas.nycnet, dhs.nycnet, redcapcloud.com, cityofnewyork.us, dynamics.com, dynamics365portals.us, getinfo.nyc, fdnycloud.org, microsoftonline.com, mkscloud.com, samaritan.com, ivalua.us, sbs.nycnet, communityneeds.nyc, ukrosoft.com.ua, appgeo.com, azurewebsites.net, or gigya.com. Please contact nycidintegration@doitt.nyc.gov to add your domain name to the list of valid domains.      		 Optional
      lang A language code. Learn about Internationalization and Localization for a list of supported language codes. Defaults to en. Optional
      spName Your application's SAML Service Provider (SP) Metadata name, found in the NYC.ID Console. This value is used to override the Application Brand Banner computed from the "target" parameter. Learn more about Application Brand Banner Logic Optional
! IMPORTANT: If the "target" parameter isn't specified or is invalid, NYC.ID will send the user to NYC.gov. 
When a user visits the Email Confirmation Required page:
  1. If the "emailAddress" parameter is an email address, NYC.ID will display the user's email address and the user would click the Send Email button to request another validation email.
    1. After the user clicks the link in the validation email, NYC.ID will change the user's email address to the validated state.
    2. The user can click the Continue button to return to your application via the URL specified in the "target" parameter. When the user returns to your application, the SAML Assertion remains unchanged, with the user's email address "appearing" un-validated. Your application should invoke the Email Validation Web Service again to determine the current email address validation status.
  2. If the "emailAddress" parameter is a username, NYC.ID will prompt the user to change his or her username to an email address within the Account Profile page.
  3. If the user is logged in and the user has a validated email address, NYC.ID will direct the user to his or her Account Profile.
1 After the user validates his or her email address, the SAML Assertion will remain unchanged with the user's email address "appearing" un-validated. Therefore, your application must use the web service to accurately determine the user's current email validation status.

 

Email Validation Web Service

Your application must use this web service to determine a user's current email address validation status. Learn about Web Services.

GET /account/api/isEmailValidated.htm

Input

Parameter Name Parameter Description Optional/ Required
guid The user's "guid" from the SAML Assertion Required
dateTime The current date and time formatted as a Java SimpleDateFormat pattern (MM/dd/yyyy HH:mm or M/d/yy HH:mm). Optional, unless your application's NYC.ID Service Account is configured to prevent replay attacks
userName Your application's NYC.ID Service Account username Required
signature The signature generated for this request. Refer to calculating the authentication signature Required

Output

Http Status (Code) Response Description
OK (200) {"validated":true} Indicates the user has a validated email address
OK (200) {"validated":false} Indicates the user has an un-validated email address
BAD REQUEST (400) Refer to Bad Request Status table below Indicates there was an error in the http request
UNAUTHORIZED (401) Refer to Unauthorized Status table below Indicates there was an error in the http request related to authentication
INTERNAL SERVER ERROR (500) Refer to Internal Server Error Status table below Indicates there was an error while processing the http request
SERVICE UNAVAILABLE (503) Not Applicable Indicates the server is undergoing maintenance and is temporarily unavailable

Bad Request Status

A bad request status indicates there was a problem with the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.

Here are a couple of sample errors: 

{"ERRORS":{"guid":"invalid","userName":"required","signature":"invalid"}}
{"ERRORS":{"cpui.unknownGuid":"Unknown GUID: test1234"}}
Code Message Description
guid invalid "guid" was not provided or was not in the required format.
userName invalid "userName" was not provided or was invalid.
signature invalid "signature" was not provided or was not in the required format.
cpui.unknownGuid Unknown GUID: <guid> "guid" was not found within NYC.ID.

Unauthorized Status

An unauthorized status indicates there was a problem with the http request related to authentication. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.

Here is a sample error:

{"ERRORS":{"cpui.failedToAuthenticate":"The combination of userName and signature is incorrect."}}
Code Message Description
cpui.invalidDomainName Invalid Domain Name: <domainName>. Valid Domains: [doitt.nycnet, nyc.gov, nycid.nycnet, csc.nycnet, cloudapp.net, hpd.nycnet, nycgovparks.org, finance.nycnet, hpdnyc.org, cs.nycnet, gcomsoft.com, records.nycnet, dcas.nycnet, dhs.nycnet, redcapcloud.com, cityofnewyork.us, dynamics.com, dynamics365portals.us, getinfo.nyc, fdnycloud.org, microsoftonline.com, mkscloud.com, samaritan.com, ivalua.us, sbs.nycnet, communityneeds.nyc, ukrosoft.com.ua, appgeo.com, azurewebsites.net, or gigya.com] The referrer domain name was invalid.
cpui.failedToAuthenticate The combination of userName and signature is incorrect. Authentication failed. Either "userName" or "signature" was incorrect or "dateTime", if provided, differs by more than 15 minutes from the current date and time.

Internal Server Error Status

An internal server error status indicates there was a problem while processing the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.

Code Message Description
cpui.exception This value is dynamically computed based on the cause of the error. For those that are curious, it's the output of the getMessage() method of the java.lang.Exception class. Indicates an unknown error occurred while processing the request