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:

trust the NYC.ID Identity Provider (IdP) (called a metadata exchange)
process the user's info in the SAML Assertion, and
invoke SAML 2.0 Single Logout or IdP Logout.

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

Installation of Service Provider (SP) Metadata on the IdP

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

generating the Service Provider (SP) metadata
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:

Generating SP Metadata – Spring Security
Generating SP Metadata – ComponentSpace 2.6.0.2

Configuring the NYC.ID Console

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

Login to the NYC.ID Console
Create a new service account
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

PRD

! IMPORTANT: Console generated certificate other than SHA1 requires integration team to make manual update to your SP. Email us nycidintegration@doitt.nyc.gov

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
tfa	A value of true indicates the user has two factor authentication enabled

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:

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.
Click on Metadata Administration
Click on Generate new service provider metadata
Enter the following values into the form:

Store for the current session: No
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).
Entity base URL: The fully-qualified URL of your application
Entity alias: The same value as Entity ID
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.
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.
Signature security profile: MetalOP
SSL/TLS security profile: PKIX
SSL/TLS hostname verification: Standard hostname verifier
SSL/TLS client authentication: None
Sign metadata: Yes
Signing algorithm: (Leave blank)
Sign sent AuthNRequests: Yes
Required signed authentication Assertion: Yes
Require signed LogoutRequest: Yes
Required signed LogoutResponse: No
Required signed ArtifactResolve: No
Single sign-on bindings:

SSO HTTP-POST: Default and Included
SSO Artifact: Included
All other Names should be unchecked!

Supported NameIDs: (Check all)
Enable IDP discovery profile: No
Custom URL for IDP discovery: (Leave blank)
Include IDP discovery extension in metadata: No

Click on Generate metadata
Copy the content within the Metadata text field
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:

Open Microsoft Internet Information Services (IIS) 7.x Manager
In the connections window, select a server
Double click on Server Certificates
Right click on the certificate to export and click View...
In the Certificate window, click the Details tab
Click the Copy to File... button
In the Certificate Export Window, click the Next > button
Choose one of the following

To export the certificate:

Select No, do not export the private key radio button
Click the Next > button
Select the DER encoded binary X.509 (.CER) radio button
Click the Next > button
Enter a file name for the certificate
Click the Next > button
Click the Finish button

To export the private key:

Select Yes, export the private key radio button
Click the Next > button
This option will be pre-selected: Personal Information Exchange – PKCS #12 (.PFX)
Select the Include all certificates in the certification path if possible and Export all extended properties checkboxes
Enter a password to protect the private key
Click the Next > button
Enter a file name for the private key
Click the Next > button
Click the Finish button

Downloading the IdP Certificate

To download the IdP certificate, follow these steps:

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