A ForgeRock protected, sample, todo web-app written with the React view library with a supporting (protected) API resource server. A live version can be found here: https://fr-react-todos.crbrl.io.

IMPORTANT: This is not a demonstration of React itself or instructional for how to build a React app. This is intended to demonstrate the implementation of the ForgeRock JavaScript SDK within a React app. There are many aspects to routing, state management, tooling and other aspects to building a React app that are outside of the scope of this project. For information about creating a React app, visit React's official documentation.

1. An instance of ForgeRock's Access Manager (AM), either within a ForgeRock's Identity Cloud tenant, your own private installation or locally installed on your computer
2. Node >= 14.2.0 (recommended: install via official package installer)
3. Knowledge of using the Terminal/Command Line
4. Ability to generate security certs (recommended: mkcert (installation instructions here)
5. This project "cloned" to your computer

Once you have the 5 requirements above met, we can build the project.

This project requires HTTPS (secure protocol) which means security (SSL/TLS) certificates are necessary. For local development, it's common to generate your own self-signed certificates. You're free to use any method to do this, but if you need assistance in generating your own certs, the following can be helpful:

• Using this utility (mkcert) can help simplify the process of creating trusted certs

• After following mkcert's installation guide and simple example of creating certs, you should have two files: example.com+5.pem & example.com+5-key.pem

  (Ensure these two files are at the root of this project; you can name them whatever you want since you configure them in your .env file)

WARNING: Self-signed certificates or certificates not from an industry-recognized, certificate authority (CA) should never be used in production.

1. Allowed origins: https://react.example.com:8443
2. Allowed methods: GET POST
3. Allowed headers: Content-Type X-Requested-With Accept-API-Version Authorization

1. Create a public (SPA) OAuth client for the web app: no secret, scopes of openid profile email, implicit consent enabled, and no "token authentication endpoint method".
2. Create a confidential (Node.js) OAuth client for the API server: with a secret, default scope of am-introspect-all-tokens, and client_secret_basic as the "token authentication endpoint method".

1. Login
2. Register

Note: The sample app currently supports the following callbacks only:

• NameCallback
• PasswordCallback
• ChoiceCallback
• ValidatedCreateUsernameCallback
• ValidatedCreatePasswordCallback
• StringAttributeInputCallback
• BooleanAttributeInputCallback
• KbaCreateCallback
• TermsAndConditionsCallback

Change the name of .env.example to .env and replace the bracketed values (e.g. <<<helper-text>>>) with your values.

Example with annotations

AM_URL=https://example-am-instance.forgerock.com/am (include the /am)
APP_URL=https://react.example.com:8443 (your SPA's URL)
API_URL=https://api.example.com:9443 (your resource API server's URL)
DEBUGGER_OFF=false
DEVELOPMENT=true
JOURNEY_LOGIN=Login (name of journey/tree for Login)
JOURNEY_REGISTER=Registration (name of journey/tree for Register)
SEC_KEY_FILE=./key.pem
SEC_CERT_FILE=./cert.pem
REALM_PATH=alpha
REST_OAUTH_CLIENT=sample-app-server (name of private OAuth 2.0 client/application)
REST_OAUTH_SECRET=secret (the secret for the private OAuth 2.0 client/application)
WEB_OAUTH_CLIENT=example-react-app (the name of the public OAuth 2.0 client/application)

# Install the project dependencies
$ npm install

# Build the client project
$ npm run build

Now you'll need to update your hosts (/etc/hosts if on a Mac) to allow for domain aliases:

$ sudo vim /etc/hosts

# hosts file aliases
127.0.0.1 react.example.com api.example.com

Now, run the below commands to start the processes needed for building the application and running the servers for both client and API server:

# In one terminal window, run the following watch command
# This "watches" the client source files for changes and rebuilds when needed
$ npm run watch

# In another terminal window, run the dev servers for both client and server
$ npm run servers

Now, you should be able to visit https://react.example.com:8443, which is your web app or client (the Relying Party in OAuth terms). This client will make requests to your AM instance, (the Authorization Server in OAuth terms), which will be running on whatever domain you set, and https://api.example.com:9443 as the REST API for your todos (the Resource Server). Enjoy!

This project has a debugging statements that can be activated which causes the app to pause execution at each SDK integration point. It will have a comment above the debugger statement explaining the purpose of the integration.

If you'd like to use this feature as a learning tool, open the live app and then open the developer tools of your browser. Rerun the app with the developer tools open, and it will automatically pause at these points of integration.

For local development, if you want to turn these debuggers off, you can set the environment variable of DEBUGGER_OFF to true.

To modify the client portion of this project, you'll need to be familiar with the following React patterns:

1. Functional components and composition
2. Hooks (including custom hooks)
3. Context API
4. React Router

You'll also want a basic understanding of Webpack and the following:

1. Babel transformation for React
2. Plugins for Sass-to-CSS processing

We heavily leveraged Twitter Bootstrap and it's utility classes, but you will see classes with the prefix cstm_. These are custom classes, hence the cstm shorthand, and they are explicitly used to denote an additional style application on top of Bootstrap's styling.

To modify the API server, you'll need a basic understanding of Node as well as the following things:

1. Express
2. PouchDB
3. Superagent

The ForgeRock Javascript SDK is developed with TypeScript, so type definitions are available. This sample application does not utilize TypeScript, but if you'd like to see a version of this written in TypeScript, let us know.