--- title: Integrate PingOne with a Node.js Express app description: In this tutorial, you configure a Node.js application running Express to connect to your PingOne instance using OpenID Connect (OIDC). component: pingone page_id: pingone:pingone_tutorials:p1_tutorial_integrate_nodejs_express_app canonical_url: https://docs.pingidentity.com/pingone/pingone_tutorials/p1_tutorial_integrate_nodejs_express_app.html revdate: Nov 5, 2024 section_ids: before-you-begin: Before you begin step-1-download-and-initialize-the-sample-app: Step 1. Download and initialize the sample app download-the-sample-app: Download the sample app initialize-the-sample-app: Initialize the sample app example: Example: step-2-configure-the-sample-app: Step 2. Configure the sample app example-2: Example: step-3-test-the-sample-app: Step 3. Test the sample app example-3: Example: result: Result: result-2: Result: result-3: Result: result-4: Result next-steps: Next steps troubleshooting-redirect-uri-mismatch-errors: Troubleshooting redirect URI mismatch errors how-to-fix-redirect-uri-mismatch-errors: "How to fix \"Redirect URI mismatch\" errors" --- # Integrate PingOne with a Node.js Express app In this tutorial, you configure a Node.js application running Express to connect to your PingOne instance using OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)*. You can then authenticate as a user and obtain both an access and ID token. *Time to success*: 10 minutes ## Before you begin To complete this tutorial you must have: * An OIDC Web application in PingOne configured with the following settings: * **Response Type**: Code * **Grant Type**: Authorization Code * **Redirect URIs**: http\://localhost:3000/callback * **Token Endpoint Authentication Method**: Client Secret Basic | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | As a starting point, use the **Getting Started Application** built into all customer solution environments when you select the **Include a solution designer to easily design and test experiences** checkbox. Learn more in [Building solutions](../getting_started_with_pingone/p1_building_solutions.html). | Learn more in [Adding an application](../applications/p1_applications_add_applications.html) and [Editing an application - OIDC](../applications/p1_edit_application_oidc.html). * [Node.js v18.7.1](https://nodejs.org/en/download/package-manager) or later. * A user created in your environment. Learn more in [Adding a user](../directory/p1_adduser.html). ## Step 1. Download and initialize the sample app We provide a sample app project that you can download and configure to connect to PingOne quickly and easily. The project uses `npm` to manage the packages it requires, such as Express and Dotenv. ### Download the sample app Clone the Git repository or download a `.zip` archive to obtain the sample app source code: * Clone with Git * Download a `.zip` archive 1. From the command line, clone the sample repo using Git: ``` git clone https://github.com/pingidentity/generic-sample-apps.git ``` 2. Navigate to the root of the sample using the following command: ``` cd express-authorization-code % npm start ``` 3. Run the following command to download and install the required packages and modules: ``` npm install ``` 1) In a browser, go to . 2) Select **Code**, and then click **Download ZIP**. 3) Extract the contents of the `.zip` archive to a folder on your computer. For example `{generic-sample-apps}`. ### Initialize the sample app The sample app requires a number of packages, which you can install by using npm: 1. Navigate to the express authorization code folder in the root directory using the following command: ``` cd express-authorization-code ``` 2. Run the following command to download and install the required packages and modules: ``` npm install ``` ### Example: The result resembles the following: ``` `~/PingOneNodeExpressSample $ npm install added 134 packages, and audited 135 packages in 3s 19 packages are looking for funding run `npm fund for details found 0 vulnerabilities` ``` ## Step 2. Configure the sample app Add the code and configuration the app needs to connect to PingOne: 1. In the PingOne admin console, go to **Applications > Applications**, and select the application to use for this tutorial. 2. On the **Integrate tab**, select the following: * In **Authorization Flows**, ensure that **Authorization Code** is selected. * In **Language Framework**, select **Express**. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This tutorial is for Express only. Selecting **Ping SDK for JavaScript** creates a different snippet. Go to [JavaScript Tutorials](https://docs.pingidentity.com/sdks/latest/sdks/tutorials/javascript/pingone/index.html) for detailed instructions and links to the sample app. | * If you've enabled custom domains, in the **Domain Path** list, select one of the following: * **Base**: Select to use the default \*.pingone.com domain. * **Custom**: Select to use the custom domain configured for the environment. 3. Click the **Copy to clipboard** icon to copy the code snippet. The code is preconfigured with the environment settings the app requires for a connection, excluding the client secret. ### Example: ``` `PingOne Express Authorization Code Flow PINGONE_AUTH_ENDPOINT="https://auth.pingone.com/####-####-####-####-######/as/authorize" PINGONE_TOKEN_ENDPOINT="https://auth.pingone.com/######-####-####-####-#########/as/token" PINGONE_SIGNOFF_ENDPOINT="https://auth.pingone.com/#######-####-####-####-############/as/signoff" PINGONE_CLIENT_ID="########-####-####-####-##########" PINGONE_CLIENT_SECRET="{{PINGONE_CLIENT_SECRET}}" REDIRECT_URI="http://localhost:3000/callback" PINGONE_SCOPES="openid"` ``` 4. Open the application and folder in the IDE. 5. Paste the code from the PingOne console into the `.env` file, replacing the `# Replace with Snippet` string. 6. Save the `.env` file. ## Step 3. Test the sample app You can now run the sample app, which starts a server at http\://localhost:3000 by default. 1. Navigate to the express authorization code folder in the root directory using the following command: ``` cd express-authorization-code ``` 2. Run the following command to build the project and start the local server: ``` npm start ``` ### Example: The result resembles the following: ``` express-authorization-code % npm start > node-ex-website@1.0.0 start > node server.js Server listening on port 3000` ``` 3. In a browser, go to . ### Result: A wireframe for the application opens: ![wireframe for an application](_images/wireframe.png) 4. Click **Sign On**. ### Result: The PingOne sign-on page opens. 5. Enter a known user's credentials and click **Sign On**. ### Result: PingOne verifies the credentials and redirects the browser to the sample app, which opens a wireframe profile page that includes the access and ID tokens: ![access and id token](_images/idtoken.png) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | Copy a token value and inspect its contents using the [Ping Identity JWT Decoder](https://developer.pingidentity.com/en/tools/jwt-decoder.html). | 6. To revoke the tokens and sign the user off of PingOne, click **Sign Off**. ## Result You have successfully added PingOne-backed sign on and sign off to a Node.js app running Express. ## Next steps * You can easily change the sign-on experience by changing the authentication policy the application uses without rebuilding the sample app. * Learn more in [Authentication policies for applications](../applications/p1_auth_policies_for_applications.html). * Learn more about what you can do with the tokens you obtained during the OIDC in [The Essential OAuth Primer](https://hub.pingidentity.com/white-papers/3119-essential-oauth-primer). To see how PingFederate uses OAuth 2.0 and OIDC, download the [OAuth Playground](https://www.pingidentity.com/bin/ping/signedDownloadLink?c=eydmaWxlS2V5JzonZ2F0ZWQvU29mdHdhcmUvUGluZ0ZlZGVyYXRlL2RldmVsb3Blci10b29scy9PQXV0aFBsYXlncm91bmQtNC40LnppcCcsJ2V1bGFQYXRoJzonJ30=) (requires sign on). ## Troubleshooting redirect URI mismatch errors Try the tips and workarounds in the following section if you encounter a redirect URI mismatch error. ### How to fix "Redirect URI mismatch" errors The sample application sends a `redirect_uri` parameter when contacting the PingOne instance. If the value doesn't match a value configured in the web app in PingOne, you receive the following error: ``` The request could not be completed. One or more validation errors were in the request. ``` ![error message](_images/errormessage.png) To resolve the issue: 1. In the PingOne admin console, go to **Applications > Applications** and select the application the sample is using. 2. On the **Configuration** tab, ensure that the **Redirect URIs** property contains http\://localhost:3000/callback. 3. In an IDE or text editor, open the `.env` file in the root folder of the sample app. 4. Ensure the `REDIRECT_URI` property exactly matches the value in PingOne and is surrounded with double quotes: `"http://localhost:3000/callback"`.