Authentication

Authentication is the act of verifying, via a username or email address, and password, that a user is who he or she claims to be. NYC.ID implements authentication using Security Assertion Markup Language 2.0 (SAML 2.0).

 

Implementing Authentication

To implement authentication, your application must:

Metadata Exchange

The metadata exchange forms a trust relationship between your application and the NYC.ID IdP. There are two steps:

  • Installation of Service Provider (SP) metadata on the IdP
  • Installation of Identity Provider (IdP) metadata on the SP
metadata exchange

Installation of Service Provider (SP) Metadata on the IdP

Installation of the SP metadata on the NYC.ID IdP involves:

  1. generating the Service Provider (SP) metadata
  2. configuring the NYC.ID Console
Generating Service Provider Metadata

You can generate the Service Provider (SP) metadata for your application using a framework associated with your programming language. Two common frameworks are Spring Security and ComponentSpace. Learn how to generate SP metadata using either of those frameworks via these links:

Configuring the NYC.ID Console

After your request to access the NYC.ID Console is complete:

  1. Login to the NYC.ID Console
  2. Create a new service account
  3. Create a new SAML SP
Installation of Identity Provider (IdP) Metadata on the SP

You'll need to install the IdP metadata, and certificate, if needed, onto the SP. You can download the IdP metadata and, if needed, the certificate for your various environments from the following URLs:

IdP Metadata URLs

NON-PRD https://fidm.us1.gigya.com/saml/v2.0/3_DkZigi2v_eW7z-cZt8PAw-cYWQYg2d8VqABUFRZUhhzxNAdwR5brLl_h8Hqbo7Bm/idp/metadata

PRD https://fidm.us1.gigya.com/saml/v2.0/3_vmpCA4aKvG0SQpyaS2U-BberGxNM7YYtfGc3B0-w2jkr4rmJoIMys6JhpRnP7_LH/idp/metadata

To install the IdP metadata and, if needed, the certificate, in your Service Provider, consult your application framework (e.g., Spring Security, ComponentSpace, etc.).

 

Login

A user should log in to your application by clicking a link or button, which directs the user to a secure page within it. Your application should detect that the user is not logged in and redirect the user to the Login page. A user can then login with:

  • his or her NYC.ID account or,
  • if configured, a social identity provider, or,
  • his or her New York City employee credentials

When logging in with his or her NYC.ID account, after five consecutive failed login attempts, a user is shown a CAPTCHA. After eight consecutive failed login attempts, the user's account is permanently locked, until the user resets his or her password. Learn more about Forgot Password.

SAML Assertion

After a user logs into your application, it receives a SAML Assertion with information about that user. Your application controls user access based on attributes provided in the SAML Assertion. The attributes are defined here:

Attribute Name Description
GUID The unique identifier of the user for the "userType". (8 or 32 characters and case sensitive)
mail The user's email address or username, if the user doesn't have an email address. If the domain part of the email address equals "noemail.nyc.gov", the local part of the email address is the user's username.
! IMPORTANT: When logging in with Facebook, a user may choose to exclude his or her email address and therefore, it will not be provided in the SAML Assertion.
givenName The first name of the user. (Maximum of 32 characters; valid Unicode alphabet, 0 through 9, hyphen, apostrophe, forward slash, or space)
middleName The middle initial of the user. (Maximum of one character; valid Unicode alphabet, 0 through 9, hyphen, apostrophe, forward slash, or space)
sn The surname of the user. (Maximum of 64 characters; valid Unicode alphabet, 0 through 9, hyphen, apostrophe, forward slash, or space)
nycExtEmailValidationFlag If "nycExtEmailValidationFlag" equals True, then "mail" is validated. If False, then "mail" is not validated. This value cannot be null.
nycExtTOUVersion (deprecated) Either 0.0 or 1.0
userType (deprecated) Always EDIRSSO

 

Logout

A user can log out of your application in four ways. Your application should be configured as follows:

  • When a user clicks a Logout button, your application should perform a SAML Single Logout or IdP Logout; this explicit logout should destroy the user's active session within your application and the IdP.
  • When a user takes no action on a session timeout warning dialog (see below), your application should perform a SAML Single Logout or IdP Logout; this implicit logout should destroy the user's active session within your application and the IdP.
  • When a user closes his or her Web browser without logging out, your application should take no action (i.e., do not perform a SAML Single Logout).
  • When a user clicks a Logout button in any other NYC.ID-integrated application, your application, if configured to support SAML Single Logout, should respond to the IdP's SAML Single Logout request and destroy the user's active session within your application.

A SAML Single Logout simultaneously logs a user out of your application and all other NYC.ID-integrated applications that he or she is logged into.

! IMPORTANT: During SAML Single Logout, the user will not be logged out of any federated identity providers.

IdP Logout

If your application doesn't support SAML Single Logout, or your application needs to log the user out of the NYC Employees IdP, you must include the following code within your Web application. When this iframe is invoked by a Web browser, it will log the user out of the NYC.ID IdP, the NYC Employees IdP, and Account Profile.

<iframe src="https://${environment}/account/idpLogout.htm?x-frames-allow-from={urlWithValidDomain}" style="display: none;"></iframe>
NOTE: If your application does not support iframes, your application may perform a redirect to the iframe "src" URL.

Session Timeout Warning Dialog

Your application should automatically log the user out after a period of inactivity to prevent exposing user data. If the user is inactive in your application for more than five minutes, your application should prompt the user to logout or stay logged in.

  • If the user clicks the Logout button on the dialog box, your application should perform a SAML Single Logout.
  • If the user clicks the Stay Logged In button on the dialog box, your application should extend the user's session. This is usually done using AJAX
  • If the user takes no action for two additional minutes after the dialog box appears, your application should invoke a SAML Single Logout.
NOTE: The session timeout of the IdP is four hours.
! IMPORTANT: We recommend that your application's session timeout be 30 minutes or less.

 

Generating SP Metadata – Spring Security

You can generate SP metadata using the Spring Security Framework for Java Web applications. 

! IMPORTANT: All URLs are case-sensitive. It is recommended that lowercase be used for all values.

Follow these steps to generate SP metadata using Spring Security:

  1. Install and deploy the Spring SAML 2.0 Sample application to the environment that has your application's SSL certificate. Download the application from Spring.
    NOTE: You application can be configured to generate its SP metadata. Learn more about this capability within the Spring Security SAML Extension documentation.
  2. Click on Metadata Administration
  3. Click on Generate new service provider metadata
  4. Enter the following values into the form:
    1. Store for the current session: No
    2. Entity ID: The fully-qualified URL of your application (e.g., https://domainName/contextPath). It must match the alias used in the ExtendedMetadata Spring bean (e.g., https://nyc-dev-web.csc.nycnet/xxx).
    3. Entity base URL: The fully-qualified URL of your application
    4. Entity alias: The same value as Entity ID
    5. Signing key: Pre-populated with the certificate alias. If the value is blank, it means the certificate alias in the Spring SAML 2.0 Sample application is incorrect. If you are using the Spring SAML2 Sample application from TeamCity, the certificate alias can be found in operations.properties.
    6. Encryption key: Pre-populated with the certificate alias. If the value is blank, it means the certificate alias in the Spring SAML 2.0 Sample application is incorrect. If you are using the Spring SAML2 Sample application from TeamCity, the certificate alias can be found in operations.properties.
    7. Signature security profile: MetalOP
    8. SSL/TLS security profile: PKIX
    9. SSL/TLS hostname verification: Standard hostname verifier
    10. SSL/TLS client authentication: None
    11. Sign metadata: Yes
    12. Signing algorithm: (Leave blank)
    13. Sign sent AuthNRequests: Yes
    14. Required signed authentication Assertion: Yes
    15. Require signed LogoutRequest: Yes
    16. Required signed LogoutResponse: No
    17. Required signed ArtifactResolve: No
    18. Single sign-on bindings:
      1. SSO HTTP-POST: Default and Included 
      2. SSO Artifact: Included
      3. All other Names should be unchecked!
    19. Supported NameIDs: (Check all)
    20. Enable IDP discovery profile: No
    21. Custom URL for IDP discovery: (Leave blank)
    22. Include IDP discovery extension in metadata: No
  5. Click on Generate metadata
  6. Copy the content within the Metadata text field
  7. Paste this content into a new file called serviceProvider-metadata.xml. We recommend that you don't package this file in your application's Web Archive (WAR). For the NYC.gov environment, our convention is to place it within this classpath location: /opt/app_config/java_app/xxx/. This makes it easy to regenerate the SP metadata without having to re-package your application.

 

Generating SP Metadata – ComponentSpace 2.6.0.2

You can generate SP metadata using the ComponentSpace library for ASP.NET Web applications, however it is not required.

! IMPORTANT: DoITT owns an enterprise license for ComponentSpace SAML for ASP.NET and ASP.NET Core, which can be used across all .NET applications that are developed by the City of New York. The components necessary for integration can be downloaded from the NYC.ID Console.
! IMPORTANT: This documentation is based on ComponentSpace version 2.6.0.2. Consult the ComponentSpace documentation for the version you are using, including the saml.config xml schema definition.

Configuring ComponentSpace saml.config File

To ensure that authentication and logout work properly, you must use the following attribute names and values in the ServiceProvider and PartnerIdentityProvider elements in your application's saml.config file. Download a sample saml.config

! IMPORTANT: All attribute values are case-sensitive.
ServiceProvider Attribute Name Attribute Value
Name The entityID of your SP
! IMPORTANT: This is the Issuer of the SAML Service Provider configured in the NYC.ID Console.
AssertionConsumerServiceUrl The URL of the SP's Assertion Consumer Service
LocalCertificateFile The private key file for the server which is hosting your application. Learn how to export a private key
! IMPORTANT: The certificate must valid and should not be self-signed. If your application is deployed on CityNet, the certificate should be signed by the CITYNET CA.
! IMPORTANT: This is the same certificate that is used to create a SAML Service Provider in the NYC.ID Console.
LocalCertificatePassword The password of the private key
PartnerIdentityProvider Attribute Name Attribute Value
Name The entityID inside the IdP Metadata URL
SignAuthnRequest true
SignLogoutRequest true
SignLogoutResponse true
WantSAMLResponseSigned false
WantAssertionSigned true
WantAssertionEncrypted false (or true, if Encrypted Assertion is checked and the X.509 Encryption Certificate is specified in the NYC.ID Console)
SingleLogoutServiceBinding urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
SingleSignOnServiceBinding urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
SingleSignOnServiceUrl The Location attribute value of the SingleSignOnService found in the IdP Metadata
SingleLogoutServiceUrl The Location attribute value of the SingleLogoutService found in the IdP Metadata
NameIDFormat urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
PartnerCertificateFile The Gigya IdP certificate. Learn how to download the IdP Certificate
! IMPORTANT: The UseEmbeddedCertificate attribute is intended for debugging purposes only. In production, you must specify the PartnerCertificateFile attribute with the IdP certificate (i.e., .cer).

Exporting a Certificate and/or Private Key

To export a certificate and private key from Microsoft IIS 7.x Manager, follow these steps:

  1. Open Microsoft Internet Information Services (IIS) 7.x Manager
  2. In the connections window, select a server
  3. Double click on Server Certificates
  4. Right click on the certificate to export and click View...
  5. In the Certificate window, click the Details tab
  6. Click the Copy to File... button
  7. In the Certificate Export Window, click the Next > button
  8. Choose one of the following
    1. To export the certificate:
      1. Select No, do not export the private key radio button
      2. Click the Next > button
      3. Select the DER encoded binary X.509 (.CER) radio button
      4. Click the Next > button
      5. Enter a file name for the certificate
      6. Click the Next > button
      7. Click the Finish button
    2. To export the private key:
      1. Select Yes, export the private key radio button
      2. Click the Next > button
      3. This option will be pre-selected: Personal Information Exchange – PKCS #12 (.PFX)
      4. Select the Include all certificates in the certification path if possible and Export all extended properties checkboxes
      5. Enter a password to protect the private key
      6. Click the Next > button
      7. Enter a file name for the private key
      8. Click the Next > button
      9. Click the Finish button

       

Downloading the IdP Certificate

To download the IdP certificate, follow these steps:

  1. Within IdP Metadata URL, copy the X509Certificate element to a text editor (e.g., Notepad).
  2. On the first line, add -----BEGIN CERTIFICATE-----.
  3. On the last line, add -----END CERTIFICATE-----.
  4. Save the certificate (e.g., fidm.us1.gigya.com.cer).