OpenID Connect

NYC.ID supports OpenID Connect. OpenID Connect is a protocol for authenticating users, built on top of the OAuth 2.0 authorization framework. Create (RP) relying party, that requests user authorization from an OpenID Connect Provider (OP)

To integrate NYC.ID with your app, follow these steps

  1. Have a NYCID console access and create/configure new RP
    1. Add a meaniningful description
    2. Redirect URI must be first registered and added to the list of valid domains. Only HTTPS are allowed.
    3. Access Token Lifetime and Identity Token Lifetime is mandatory and need to be set from 60 to 604800 seconds (7 days)
    4. Select Subject Identifier Type as Public if you wish to have GUID in the sub field of the JWT. Otherwise unique value will be created for you.
  2. Configure RP application
    1. Invoke gigya authorize endpoint with the following parameters:

      GET https://fidm.us1.gigya.com/oidc/op/v1.0/[apikey]/authorize

      Parameter Name Parameter Description
      client_id Defined in NYCID console.
      response_type RP wishes to receive from NYCID (OP provider). Must be valid as defined in NYCID console. Any combination of code id_token token
      redirect_uri The URI must be regisered and configured in the NYCID console.The URI that the user is sent to after completing the authorization process. The "redirect_uri" must be registered and 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.
      scope Available standard OpenID Connect scopes openid email profile address phone ui separate with spaces %20. Plus a Custom Scope (for non-prod) gov.nyc.accounts-nonprd and gov.nyc (for prod). Including tfa,nycExtEmailValidationFlag,GUID,nycExtTOUVersion,middleName claims. Additional claims can be requested. Please contact nycidintegration@doitt.nyc.gov
      nonce A unique string that associates the current Client session with an ID Token. can be current date var newNonce=Date.now();.
      state RECOMMENDED. Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.
      ui_locales OPTIONAL. This parameter can be passed to the login page, which then can be retrieved by the implementation. A space-separated list of RFC5646 language tag values. Example (fr-CA fr en)
    2. Read the code and exchange it for access_token. Invoke gigya token endpoint

      POST https://fidm.us1.gigya.com/oidc/op/v1.0/[apikey]/token

    3. token endpoint returns an access_token
      ! IMPORTANT: The client ID must be included in the query string of all calls made to the OP Authorize and Token endpoints.
      ! IMPORTANT: The client secret is required when using server-to-server calls to the Token endpoint when the RP is using Authorization Code flow.
      ! IMPORTANT: For public clients, it is recommended to use PKCE along with the authorization code grant to mitigate code interception attacks.
    4. Securely store the access_token. Expiration of the access_token is configurable in the NYCID console. Access Token Lifetime and Identity Token Lifetime
    5. Check current status of received access_token. Use introspect endpoint

      GET https://fidm.us1.gigya.com/oidc/op/v1.0/[apikey]/introspect

      ! IMPORTANT: You construct the request to the introspect endpoint just like you do for the token endpoint, using a Basic Auth token. If invalid, json response {"active": false} is returned.
    6. access_token is destroyed when user logs out.
      ! IMPORTANT: You must destroy the user's IdP session after revoking the user's access token. Learn how to perform an IdP Logout.

 

NYC.ID User Authentication using OIDC Code Flow Diagram

This sequence diagram describes how your app can integrate with the NYC.ID Openid Connect Provider

Code Flow Sequence Diagram: NYC.ID User Authentication

OIDC Sequence Diagram: NYC.ID User Authentication

Available Endpoints (OP Metadata)

To review the OP's endpoints.

  • apikey non-prod:3_DkZigi2v_eW7z-cZt8PAw-cYWQYg2d8VqABUFRZUhhzxNAdwR5brLl_h8Hqbo7Bm

  • apikey prod:3_vmpCA4aKvG0SQpyaS2U-BberGxNM7YYtfGc3B0-w2jkr4rmJoIMys6JhpRnP7_LH

GET https://fidm.us1.gigya.com/oidc/op/v1.0/[apikey]/.well-known/openid-configuration

! IMPORTANT: If the OP is using a CName or custom API domain prefix, the endpoints can also use your CName. See bellow.

  • Endpoint URL non-prod:https://nonprd-login.nyc.gov

  • Endpoint URL prod:https://prd-login.nyc.gov

Endpoint Endpoint URL
authorize [Endpoint URL]/oidc/op/v1.0/[apikey]/authorize
introspect [Endpoint URL]/oidc/op/v1.0/[apikey]/introspect
device_authorization [Endpoint URL]/oidc/op/v1.0/[apikey]/device_authorization
register [Endpoint URL]/oidc/op/v1.0/[apikey]/register
revoke [Endpoint URL]/oidc/op/v1.0/[apikey]/revoke
token [Endpoint URL]/oidc/op/v1.0/[apikey]/token
userinfo [Endpoint URL]/oidc/op/v1.0/[apikey]/userinfo

 

Authorization Code flow and PKCE for public clients

Implement login with OpenID Connect in your application by using the authorization code flow and PKCE. This method is most suitable for public clients, which are applications that cannot keep the client credentials securely.

! IMPORTANT: In NYC.ID Console under RP settings make sure Public Client is selected.
  1. Invoke gigya authorize endpoint with the following parameters:

    GET https://fidm.us1.gigya.com/oidc/op/v1.0/[apikey]/authorize

    Parameter Name Parameter Description
    client_id Defined in NYCID console.
    response_type RP wishes to receive from NYCID (OP provider). Must be valid as defined in NYCID console. code
    redirect_uri The URI must be regisered and configured in the NYCID console.The URI that the user is sent to after completing the authorization process. The "redirect_uri" must be registered and 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.
    scope (see NYCID console) separate with spaces %20.
    nonce A unique string that associates the current Client session with an ID Token. can be current date var newNonce=Date.now();.
    code_challenge The client creates and records a secret cryptographical random string code_verifier, which is then encoded using URL-safe base64 encoding to transform it into the code_challenge. The code_challenge is required for the authorization code flow with PKCE. You can use some tools to generate the code_challenge and code_verifier.The code challenge is the base64 URL encoded value of the SHA256 hashed code_verifier.
    code_challenge_method This is the method used for transforming the code_verifier into the code_challenge.The code challenge method S256. This is required for the authorization code flow with PKCE.
  2. Read the code and exchange it for access_token. Invoke gigya token endpoint

    POST https://fidm.us1.gigya.com/oidc/op/v1.0/[apikey]/token

    Parameter Name Parameter Description
    client_id Defined in NYCID console.
    code The authorization code received from the authorization request.
    redirect_uri The URI must be regisered and configured in the NYCID console.The URI that the user is sent to after completing the authorization process. The "redirect_uri" must be registered and 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.
    grant_type The grant type. Here, we are using the authorization_code grant.
    code_verifier The plain text cryptographical random string used to generate the code_challenge. This is required for the authorization code flow with PKCE.
    code_challenge_method This is the method used for transforming the code_verifier into the code_challenge.The code challenge method S256. This is required for the authorization code flow with PKCE.