Step Up Updates (#123)

* Additions for step up

Author: jrmccannon

src/guide/admin-console/applications.md

@@ -50,3 +50,9 @@ You should now be able to call `https://v4.passwordless.dev/signin/generate-toke
 Magic Links provides you with the ability to email your users a link that will redirect them to your application without having to configure your own email provider. This feature can be enabled by going to the **Settings** page, scrolling to the **Magic Links** section, checking the box, and clicking Save.
 
 You should now be able to call `https://v4.passwordless.dev/magic-links/send` to send Magic Link emails to your users. For more information, please refer to the [documentation](../api.md#magic-links-send).
+
+### Authentication Configurations
+
+Authentication Configurations allow you to fine tune the tokens being used through the `signin` or `stepup` client methods. The two default purposes are `sign-in` and `step-up`. You can configure the TTL on each of them and change the User Verification requirement. However, they cannot be deleted.
+
+You can create additional configurations to suit your needs and pass through the purposes through the `stepup()` client method.

src/guide/api.md

@@ -402,6 +402,135 @@ If successful, the `/magic-links/send` endpoint will return an HTTP 204 (No Cont
 
 If Magic Links has not been enabled, the `/magic-links/send` endpoint will return an HTTP 403 (Unauthorized) [status code](#status-codes) along with a message about enabling the Magic Links feature.
 
+## `/auth-configs/list`
+
+### Request
+
+`GET` requests made to the `/auth-configs/list` endpoint will return a `.json` object containing a list of authentication configurations that can be used by the application. It can be filtered to one specific configuration by passing the purpose name as a query parameter.
+
+```http request
+GET https://v4.passwwordless.dev/auth-configs/list HTTP/1.1
+ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
+```
+
+```http request
+GET https://v4.passwwordless.dev/auth-configs/list?purpose=step-up HTTP/1.1
+ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
+```
+
+For more information about Authentication Configurations, please see the [concepts page](concepts.md#authentication-configurations).
+
+### Response
+
+If successful, the `/auth-configs/list` endpoint will return a `.json` object containing a list of authentication configurations:
+
+```json
+{
+  "configurations": [
+    {
+      "purpose": "sign-in",
+      "timeToLive": 120,
+      "userVerificationRequirement": "preferred",
+      "createdBy": "System",
+      "createdOn": null,
+      "editedBy": null,
+      "editedOn": null,
+      "lastUsedOn": null
+    },
+    {
+      "purpose": "step-up",
+      "timeToLive": 180,
+      "userVerificationRequirement": "required",
+      "createdBy": "System",
+      "createdOn": null,
+      "editedBy": null,
+      "editedOn": null,
+      "lastUsedOn": null
+    }
+  ]
+}
+```
+
+## `/auth-configs/add`
+
+### Request
+
+`POST` requests to `/auth-configs/add` will create an authentication configuration for the authentication process. There are some restrictions on the request object.
+
+- `purpose`: A-z, 0-9, -, and \_ are the allowed characters. Max length of purpose is 255 characters.
+- `timeToLive`: Positive time span value (hh:mm:ss)
+- `userVerificationRequirement`: `preferred`, `required`, `discouraged`
+- `performedBy`: user identifier to track changes to the configuration
+
+```http request
+GET https://v4.passwwordless.dev/auth-configs/add HTTP/1.1
+ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
+Content-Type: application/json
+
+{
+  "purpose": "access-secrets-purpose", // identifying string give context to the specific authentication
+  "timeToLive": "00:03:00", // timespan the token is valid for
+  "userVerificationRequirement": "preferred" // requirement for if the user has to verify they're allowed to use an authenticator
+  "performedBy": "user_123" // user identifier to track changes to the configuration
+}
+```
+
+### Response
+
+If successful, the `/auth-configs/add` endpoint will return an HTTP 201 (Created) [status code](#status-codes).
+If unsuccessful, the `/auth-configs/add` endpoint will return an HTTP 400 (Bad Request) [status code](#status-codes) with a [problem details](errors/#problem-details) body.
+
+## `/auth-configs/`
+
+### Request
+
+`POST` requests to `/auth-configs` will edit an authentication configuration for the authentication process. There are some restrictions on the request object.
+
+- `purpose`: Must be an existing purpose (If a new purpose is passed here, a 404 will be returned)
+- `timeToLive`: Positive time span value (hh:mm:ss)
+- `userVerificationRequirement`: `preferred`, `required`, `discouraged`
+- `performedBy`: user identifier to track changes to the configuration
+
+```http request
+GET https://v4.passwwordless.dev/auth-configs HTTP/1.1
+ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
+Content-Type: application/json
+
+{
+  "purpose": "access-secrets-purpose", // existing purpose
+  "timeToLive": "00:03:00", // timespan the token is valid for
+  "userVerificationRequirement": "preferred" // requirement for if the user has to verify they're allowed to use an authenticator
+  "performedBy": "user_123" // user identifier to track changes to the configuration
+}
+```
+
+### Response
+
+If successful, the `/auth-configs` endpoint will return an HTTP 204 (No Content) [status code](#status-codes).
+If an unknown purpose is passed through, the `/auth-configs` endpoint will return an HTTP 404 (Not Found) [status code](#status-codes).
+
+## `/auth-configs/delete`
+
+### Request
+
+`POST` requests made to the `/auth-configs/delete` endpoint delete a specific authentication configuration, as specified by a `purpose`.
+
+```http request
+GET https://v4.passwwordless.dev/auth-configs/add HTTP/1.1
+ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
+Content-Type: application/json
+
+{
+  "purpose": "access-secrets-purpose", // existing purpose
+  "performedBy": "user_123" // user identifier to track changes to the configuration
+}
+```
+
+### Response
+
+If successful, the `/auth-configs/delete` endpoint will return an HTTP 204 (No Content) [status code](#status-codes).
+If an unknown purpose is passed through, the `/auth-configs/delete` endpoint will return an HTTP 404 (Not Found) [status code](#status-codes).
+
 ### Status codes
 
 The API returns HTTP Status codes for each request.

src/guide/concepts.md

@@ -113,6 +113,12 @@ While WebAuthn is very secure, attestation enhances the security of the WebAuthn
 
 The relying party can use the attestation information to make informed decisions about whether to trust the authenticator and to assess the level of security provided by the user's device. It's important to note that while attestation enhances security, it is not mandatory for the basic operation of WebAuthn. WebAuthn can still work without attestation, but its use is recommended for stronger security practices.
 
+### Authentication Configurations
+
+Authentication configurations allow you to configure your authentication token used in the `signin()` and `stepup()` client methods. Each method passes parameters into the authenticator accessed by the browser. Authentication Configurations allow for the Time to Live of the authentication token and the User Verification Requirement setting to be set for the given authentication workflow.
+
+There are two default Authentication Configurations for each application, `step-up` and `sign-in`. They are used in their respective client methods as the `purpose` of the authentication. They can be edited, and if deleted, they will revert back to their default settings. Authentication Configurations can be accessed via the [API](./api.md#auth-configs) or [Admin Console](./admin-console/applications.md#authentication-configurations).
+
 ## More terms
 
 ### Relying party

src/guide/frontend/javascript.md

@@ -162,7 +162,7 @@ const { token, error } = await p.siginWithId(123);
 // plain object
 const signinResponse = await p.signinWithId(123);
 console.log(signinResponse.token); // "verify_xxyyzz"
-console.log(signinResponse.error); // undefined or a problem details object
+console.error(response.error); // undefined or a problem details object
 ```
 
 If the signin was successful, the `token` has a string value `"verify_xxyyzz"`. If the sign-in failed, the `error` property contains the [problem details](../errors.md#problem-details).
@@ -193,3 +193,26 @@ Call the static async `.isAutofillSupported()` method to check if the end-user's
 if (await Passwordless.isAutofillSupported()) {
 }
 ```
+
+## .stepup()
+
+`.stepup()` works similar to the `.signin()` method except it allows for a specific purpose to be passed through. These purposes are set via the API ([API](../api.md#authentication)/OpenAPI) or through the application's authentication configuration setting in the [Admin Console](../admin-console/applications.md#authentication-configurations).
+
+If the authentication was successful, the `token` has a string value `"verify_xxyyzz"`. This token will have a `Purpose` property of `step-up` by default, whatever was passed in through the `StepUpRequest`. If the authentication failed, the `error` property contains the [problem details](../errors.md#problem-details).
+
+```js
+const stepUpRequest = {
+  signinMethod: {
+    userId: 123 // you could also use alias as the signinMethod as well.
+  },
+  purpose: 'step-up'
+};
+
+// destructured
+const { token, error } = await p.stepup(stepUpRequest);
+
+// plain object
+const response = await p.stepup(stepUpRequest);
+console.log(response.token); // verify_xxyyzz
+console.error(response.error); // undefined or a problem details object
+```