What this blog covers: You can get underway with a live example. This article for getting a sample app up and running with PingOne for Customers will show you the quick and easy steps you could be doing to add customer identity and access management (CIAM) features to your app. You’ll see how to:
Create an application in the PingOne for customers console
Set up a user
Download the sample app
Connect and customize the sample app
You can skip to the part that’s relevant to your situation (just click the links above) or run through the whole process.
Background So you’re assigned to work on a great new application, feature or product on a fast timeline with little wiggle room. The business logic functions are up to spec and you’ve found an incredibly efficient way to handle the big problem that had everyone stumped at first. There’s just one piece remaining: the ability for end users to authenticate, log in, specify personal settings and details, and customize the app.
Understandably, you left this part for last because dealing with identity and access management is not what excites you the most about your project. And while you absolutely have the skills to create a user table in a database, to encrypt passwords, to save and retrieve key/value pairs of for passwords and other information, to research and implement the best security practices, etc., is this really where your time and attention is best spent?
There’s an easier way. PingOne for Customers offers everything a developer like you needs, complete with a robust selection of APIs and all of the features you require to finish your project with login, registration and other identity services. By dropping in a turnkey, feature-rich identity management solution brought to you by leaders in the identity space, you help ensure your project is complete and the best it can be in less time.
Application Instance Setup In order to use PingOne for Customers in your app, you will need to create an Application in your PingOne for Customers environment. You can use the API to make the appropriate calls or use the admin console for a visual interface. We’ll show the latter in this guide.
The PingOne for Customers application you create will be what your app will communicate with for its identity services. In other words, when someone tries to perform a task like logging in or registering for an account from your app, your app will make some API calls to the application set up in PingOne for Customers.
For this guide, let’s assume you have a Single Page Application. The directions are similar for other types of applications but might require a few different steps along the way. Follow these steps to create an application instance:
Go to your PingOne for Customers admin console. If you didn’t save the link, you can find it in the email we sent after you signed up for the trial.
Click on the “Connections” link in the top navigation menu.
Click on the “+ Application” button in the upper right corner.
Select a type of Application. In this example, select “Single Page App.”
Give your application a name, such as “Test App.”
Set the redirect URI. In this example, set it to http://localhost.
The OAuth 2.0 protocol requires the redirect URI to be specified beforehand so the client knows where they’re supposed to end up (and to be suspicious if they don’t). For now, we’ll send users back to your local environment.
Add scopes to your application. In this example, the four default OIDC scopes (email, profile, phone, address) were added to allow the user to view and manage their own identity data. The OIDC and the broader OAuth scopes are defined (and included in requests) to determine and limit what users can access.
Save the Application.
Enable your new Application by flipping the switch to the right of the application title.
User Account Setup Let’s also create an example user so we can test out our app. The process is quick and painless using the admin console. Follow the steps below to create a test user.
Click on the “Users” link in the top navigation menu.
Click on the “+ Add User” button in the upper right corner.
Enter some details about the person, such as their Username (required), Given Name and Family Name.
Edit the user account by expanding the user details and clicking on the Edit icon next to the user’s account entry.
Give the user a first-time, temporary password by clicking the “Reset Password” button and entering the password.
That’s it! Now we have a test user that we can start playing around with, experiencing what it would be like for an end user interacting with your app.
Download and View Code Samples Our team is constantly pushing out more sample apps, in more languages, to allow you to do more with PingOne for Customers. These apps are examples to help you get a feel for how things work with PingOne for Customers, and can even be used as the foundation or starting point for your application.
Either download the ZIP file and expand its contents to your local computer’s drive, or clone the repository using Git: git clone firstname.lastname@example.org:pingidentity/pingone-customers-sample-oidc.git
Open the index.html file in the code editor of your choice and scroll to the bottom, where you’ll find the entries for client_id, environment_id and the redirect URIs.
These are the values you will set to match those in the configuration of the Application you created in Section 1 above.
(Remember to expand the view on the right in the “Connections” tab for each app and click on the various application tabs to see more details. The environment id can be found in the “Settings” tab of the specific environment, as shown in the next section’s steps 1 and 2.)
Customizing Code Samples to Connect to Your Application Instance You might want to have your branding on your app and things linked to your app, so we’ve provided a way to do that. Even with our simple sample app, which uses the pre-built UI, we can add some features to keep things consistent throughout your user’s app experience.
Find your PingOne for Customers account’s Environment ID in the Settings section. It’ll show the environment id for the currently selected environment (environment selection can be done in the drop-down menu on the right side of the title bar).
Find your Application’s Client ID in the Application’s details.
Enter those in index.html and save.
Now you can put your folder on a web server, local or remote. Or, if you’re familiar with NPM, you could run the following to start up a node server running your machine:
npm install && npm start
Once you have a server running with your files, you can access index.html from a web browser, where you should see the sample app home screen:
Test the login process with the test user created earlier in this guide. You will be asked to select a new password upon first login.
You should see the details of your logged-in user in the web browser as well as in Session Storage in the browser’s Web Inspector.
Use the contents of index.html as a starting point to build your own application!
Reviewing the Process Great work! Let’s review what this guide covered.
The first section was about getting an application set up in the PingOne for Customers admin console. This application is your entry point into getting all of the IAM features that PingOne for Customers has to offer.
Next, we wanted to get a new user entered into our environment that we could test with. This involved a few simple steps using the admin console.
After that, we took a look at where to find the sample app and different ways to get it. We also looked at the file containing the variables that we’ll need to adjust to connect it with your PingOne for Customer application.
Lastly, we found the information we needed to adjust the variables in the sample app, located in a single file, so it can communicate with our PingOne for Customer application. After we get the files on a server, we could use NPM but aren’t limited to it; we can access the sign-on page and try logging in!
We chose to run through this guide using the admin console, but it could’ve all been done through simple API calls instead. You can safely scale the customer identity features of your app with your user base by automating the process.
For more details on PingOne for Customer’s APIs, and for a video version of this tutorial, please visit our Developer Community and our documentation.