Merge pull request #6283 from okta/tbs-okta-889035-spa-authjs-react-update

AuthJS SDK: Sign in to SPA - update React examples

Author: brentschaus-okta

packages/@okta/vuepress-site/docs/guides/sign-in-to-spa-authjs/main/react/basic-sign-in.md

@@ -1,73 +1,198 @@
-Review the simple password-only sign-in use case from the sample app. This use case is outlined in the following sequence diagram with your single-page app (SPA) as the client:
+Review the simple password-only sign-in use case from the sample app.
 
+<!-- The sequence diagram below is out of date. It shows the old Step Mode
+flow: a single idx.authenticate(username, password) call. The current flow
+instead primes and submits each remediation step in turn with proceed({
+step }). This comment hides the diagram until the design team updates it.
+See OKTA-1220704 for the tracking ticket.
 <div class="full">
 
 ![Sequence diagram that displays the interactions between the resource owner, SDK, authorization server, and resource server for a basic SPA password sign-in flow.](/img/oie-embedded-sdk/password-only-spa-authjs-flow.svg)
 
 </div>
+-->
 
 ### Set up the Okta configuration settings
 
-Review the `src/config.js` file that references the required [app integration settings](#app-integration-settings) to initialize your Okta Auth JS instance. The `config.js` file references the values that you add to the `testenv` file.
+Review the `src/config.js` file that references the required [app integration settings](#app-integration-settings) to initialize your Okta Auth JS instance. The `config.js` file references the values that you add to the `.env` file.
 
 ```JavaScript
-const CLIENT_ID = process.env.SPA_CLIENT_ID || process.env.CLIENT_ID || '{clientId}';
-const ISSUER = process.env.ISSUER || 'https://{yourOktaDomain}/oauth2/default';
-const REDIRECT_URI = `{window.location.origin}/login/callback`;
+const CLIENT_ID = import.meta.env.VITE_CLIENT_ID || '{clientId}';
+const ISSUER = import.meta.env.VITE_ISSUER || 'https://{yourOktaDomain}/oauth2/default';
+const REDIRECT_URI = `${window.location.origin}/login/callback`;
 
-// eslint-disable-next-line import/no-anonymous-default-export
 export default {
   clientId: CLIENT_ID,
   issuer: ISSUER,
   redirectUri: REDIRECT_URI,
   scopes: ['openid', 'offline_access', 'profile', 'email'],
+  pkce: true
 };
 ```
 
+> **Note:** Okta Auth JS 8.x requires every `idx.proceed()` call to name the remediation step it's submitting. This guide uses that Step Mode pattern throughout. See [Step Mode vs Legacy Mode](https://github.com/okta/okta-auth-js/blob/master/docs/idx.md#step-mode-vs-legacy-mode) in the Auth JS SDK docs if you're migrating an older app that relies on the deprecated, generic remediation-driven pattern.
+
 ### Instantiate the Okta Auth JS client
 
-Review the React `app.js` file that imports the required libraries and instantiates the Okta Auth JS client with values from the `config.js`.
+Review the React `app.js` file that imports the required libraries and instantiates the Okta Auth JS client with values from the `config.js`. Wrap your app in the `Security` component from the Okta React SDK so it can manage the Auth JS instance for you.
 
 ```JavaScript
 import { useEffect, useState } from 'react';
 import { useHistory } from 'react-router-dom';
-import { OktaAuth, IdxStatus, urlParamsToObject, hasErrorInUrl } from '@okta/okta-auth-js';
+import { OktaAuth, IdxStatus, toRelativeUrl } from '@okta/okta-auth-js';
+import { Security } from '@okta/okta-react';
 import { formTransformer } from './formTransformer';
 import oidcConfig from './config';
 import './App.css';
 
-function createOktaAuthInstance() {
-  const { state } = urlParamsToObject(window.location.search);
-  return new OktaAuth(Object.assign({}, oidcConfig, {
-    state
-  }));
+const oktaAuth = new OktaAuth(oidcConfig);
+
+...
+
+function App() {
+  const history = useHistory();
+  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
+    history.replace(toRelativeUrl(originalUri || '/', window.location.origin));
+  };
+
+  return (
+    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
+      ...
+    </Security>
+  );
 }
+```
 
-const oktaAuth = createOktaAuthInstance();
+> **Note:** This guide's simplified example doesn't cover redirect callbacks (for example, social IdP sign-in or email magic links). If your app needs them, see [Redirect callbacks](https://github.com/okta/okta-auth-js/blob/master/docs/idx.md#redirect-callbacks) in the Auth JS SDK docs and the `LoginCallback` component in [Okta's reference sample app](https://github.com/okta/okta-auth-js/tree/master/samples/generated/react-embedded-auth-with-sdk).
 
-...
+### Start the sign-in transaction
+
+Before you can render a sign-in form, you need an in-progress IDX transaction to drive it. Start one when your component mounts by calling `idx.start()`. `idx.start()` begins the transaction. It doesn't resolve a step's field data until you name that step. Call `idx.proceed()` with only a `step` name and no other values. The SDK then returns that step's `inputs` for rendering. For this password-only use case, the sign-in flow always begins with the `identify` step, which asks for `username`:
+
+```JavaScript
+const [transaction, setTransaction] = useState(null);
+
+useEffect(() => {
+  const startTransaction = async () => {
+    await oktaAuth.idx.start();
+    const newTransaction = await oktaAuth.idx.proceed({ step: 'identify' });
+    setTransaction(newTransaction);
+  };
+  startTransaction();
+}, []);
 ```
 
+Pass `transaction.nextStep` into `formTransformer` to render the form fields for the current step. See [Basic sign-in flow](#basic-sign-in-flow) for the full form code. Okta's Identity Engine collects the username first. It then challenges for the password on a separate step. This password-only flow therefore renders two forms in sequence, not one combined form.
+
 ### Handle the password authentication
 
-Review the `apps.js` file for details on handling a successful password authentication by receiving the `SUCCESS` status and storing the returned tokens:
+Name the step you're submitting on every `idx.proceed()` call. `transaction.nextStep.name` holds that name. It matches the step the form already rendered. Submitting a step's values reveals the name of the next step. It does not reveal that step's renderable field data. Call `idx.proceed()` again with just the step name to prime the next form before you render it. Review the `app.js` file for details on handling a successful password authentication. It receives the `SUCCESS` status and stores the returned tokens:
 
 ```JavaScript
-....
-
 const handleSubmit = async e => {
-    e.preventDefault();
+  e.preventDefault();
 
-    const newTransaction = await oktaAuth.idx.proceed(inputValues); // inputValues = username, password
-    console.log('Transaction:', newTransaction);
+  const submittedTransaction = await oktaAuth.idx.proceed({ step: transaction.nextStep.name, ...inputValues });
+  console.log('Transaction:', submittedTransaction);
+  setInputValues({});
 
-    setInputValues({});
-    if (newTransaction.status === IdxStatus.SUCCESS) {
-      oktaAuth.tokenManager.setTokens(newTransaction.tokens);
-    } else {
+  if (submittedTransaction.status === IdxStatus.SUCCESS) {
+    oktaAuth.tokenManager.setTokens(submittedTransaction.tokens);
+    return;
+  }
+
+  const newTransaction = await oktaAuth.idx.proceed({ step: submittedTransaction.nextStep.name });
+  setTransaction(newTransaction);
+};
+```
+
+For this password-only use case, `handleSubmit` runs twice. The first run submits `username` from the `identify` step and primes the `challenge-authenticator` step. The second run submits `password` from that step and reaches `IdxStatus.SUCCESS`.
+
+### The full sign-in component code
+
+With the pieces above in place, here's the complete `App.jsx` for the password-only sign-in flow, with everything shown together:
+
+```JavaScript
+import { useEffect, useState } from 'react';
+import { useHistory } from 'react-router-dom';
+import { OktaAuth, IdxStatus, toRelativeUrl } from '@okta/okta-auth-js';
+import { Security } from '@okta/okta-react';
+import { formTransformer } from './formTransformer';
+import oidcConfig from './config';
+import './App.css';
+
+const oktaAuth = new OktaAuth(oidcConfig);
+
+function SignInForm() {
+  const [transaction, setTransaction] = useState(null);
+  const [inputValues, setInputValues] = useState({});
+
+  useEffect(() => {
+    const startTransaction = async () => {
+      await oktaAuth.idx.start();
+      const newTransaction = await oktaAuth.idx.proceed({ step: 'identify' });
       setTransaction(newTransaction);
+    };
+    startTransaction();
+  }, []);
+
+  const handleChange = ({ target: { name, value } }) => {
+    setInputValues({ ...inputValues, [name]: value });
+  };
+
+  const handleSubmit = async e => {
+    e.preventDefault();
+
+    const submittedTransaction = await oktaAuth.idx.proceed({ step: transaction.nextStep.name, ...inputValues });
+    console.log('Transaction:', submittedTransaction);
+    setInputValues({});
+
+    if (submittedTransaction.status === IdxStatus.SUCCESS) {
+      oktaAuth.tokenManager.setTokens(submittedTransaction.tokens);
+      return;
     }
+
+    const newTransaction = await oktaAuth.idx.proceed({ step: submittedTransaction.nextStep.name });
+    setTransaction(newTransaction);
+  };
+
+  if (!transaction?.nextStep) {
+    return null;
+  }
+
+  const { inputs } = formTransformer(transaction.nextStep)({});
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {inputs.map(({ label, name, type, required }) => (
+        <label key={name}>
+          {label}
+          <input
+            name={name}
+            type={type}
+            required={required}
+            value={inputValues[name] || ''}
+            onChange={handleChange}
+          />
+        </label>
+      ))}
+      <button type="submit">Sign in</button>
+    </form>
+  );
+}
+
+function App() {
+  const history = useHistory();
+  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
+    history.replace(toRelativeUrl(originalUri || '/', window.location.origin));
   };
 
-  ...
-  ```
+  return (
+    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
+      <SignInForm />
+    </Security>
+  );
+}
+
+export default App;
+```

packages/@okta/vuepress-site/docs/guides/sign-in-to-spa-authjs/main/react/download-sample.md

@@ -1,6 +1,8 @@
 ### Download the sample React application
 
-To view a simple example of a React app, clone the Auth JS repository and follow the setup procedure:
+Clone the Auth JS repository and follow the setup procedure below to confirm your org and environment work end-to-end.
+
+> **Note:** The generated sample still uses Auth JS's Legacy Mode internally, so its `App.jsx` and `GeneralForm.jsx` source don't match the Step Mode code shown later in this guide. Use the sample only to verify your app integration settings and environment; use this guide's own code snippets as the reference for how to build the sign-in logic.
 
 #### Clone the Auth JS repository
 
@@ -26,7 +28,6 @@ Create and add a configuration file (`testenv`) to the `okta-auth-js` root folde
 ```txt
 ISSUER=https://{yourOktaDomain}/oauth2/default
 CLIENT_ID={clientId}
-USE_INTERACTION_CODE=true
 ```
 
 #### Run the sample application
@@ -40,16 +41,17 @@ Navigate to the project folder and run the sample app. Click **Login** and sign
 
 ### Create a React app (optional)
 
-If you don't have an existing React app, you can quickly create an app by using [Create React App](https://create-react-app.dev/):
+If you don't have an existing React app, you can quickly create one using [Vite](https://vite.dev/):
 
 ```bash
-  npx create-react-app okta-app
+npm create vite@latest okta-app -- --template react
 ```
 
-Go into your root app directory to view the created files:
+Go into your app directory and install the base dependencies:
 
 ```bash
-  cd okta-app
+cd okta-app
+npm install
 ```
 
 ### Install dependencies
@@ -70,4 +72,15 @@ npm install @okta/okta-react@latest
 npm install react-router-dom@5
 ```
 
-> **Note:** The sample code in this use case requires `react-router-dom` version 5.x. Certain objects used in the sample code don't exist in `reactor-router-dom` version 6.x.
+> **Note:** The sample code in this use case requires `react-router-dom` version 5.x. Certain objects used in the sample code don't exist in `react-router-dom` version 6.x or later. Okta's own reference sample app is also still on `react-router-dom` version 5.x, so there's no version 6+ equivalent to switch to yet.
+
+### Add environment variables
+
+Vite only exposes environment variables to your app code when they're prefixed with `VITE_` and read through `import.meta.env`, unlike some other React tooling. Create a `.env` file in your app's root folder with your [app integration settings](#app-integration-settings):
+
+```txt
+VITE_ISSUER=https://{yourOktaDomain}/oauth2/default
+VITE_CLIENT_ID={clientId}
+```
+
+> **Note:** Add `.env` to your `.gitignore` file so you don't commit it to source control.

packages/@okta/vuepress-site/docs/guides/sign-in-to-spa-authjs/main/react/sign-in-form.md

@@ -1,22 +1,22 @@
-Build a sign-in page that captures both the username and password. As an example, from the test application, see the `index.js` file, which renders the simple sign-in for from the `formtransformer.js` file:
+Build a sign-in page that renders whichever fields the current step needs. This password-only flow asks for `username` first and `password` second. See the test application's `main.jsx` file, which renders the sign-in form using `formTransformer.js`:
 
 ```JavaScript
 import React from 'react';
-import ReactDOM from 'react-dom';
+import { createRoot } from 'react-dom/client';
 import { BrowserRouter as Router } from 'react-router-dom';
 import App from './App';
 
-ReactDOM.render(
+const root = createRoot(document.getElementById('root'));
+root.render(
   <React.StrictMode>
     <Router>
       <App />
     </Router>
-  </React.StrictMode>,
-  document.getElementById('root')
+  </React.StrictMode>
 );
 ```
 
-From the `formtransformer.js` file:
+From the `formTransformer.js` file:
 
 ```JavaScript
 const inputTransformer = nextStep => form => {