Fix #1174 Add OIDC, Encryption documentation for NextStep

wultra · Dec 9, 2024 · 5125f8a · 5125f8a
1 parent 5fb04f1
commit 5125f8a
Showing 1 changed file with 71 additions and 49 deletions.
diff --git a/docs/Next-Step-Server.md b/docs/Next-Step-Server.md
@@ -1,58 +1,65 @@
 # NextStep Server
 
-Next Step Server resolves the Next Step of the authentication process, handled authentication using credentials and OTP authorization codes, and manages user identities.
+Next Step Server resolves the Next Step of the authentication process, handled authentication using credentials and OTP
+authorization codes, and manages user identities.
 
-You can obtain the war file which can be deployed to a Java EE container in [releases](https://github.com/wultra/powerauth-webflow/releases).
+You can obtain the war file which can be deployed to a Java EE container
+in [releases](https://github.com/wultra/powerauth-webflow/releases).
 
-The configuration of Next Step Server is described in [Next Step Configuration](./Web-Flow-Configuration.md#next-step-server).
+The configuration of Next Step Server is described
+in [Next Step Configuration](./Web-Flow-Configuration.md#next-step-server).
 
-Next step definitions need to be configured before deploying Next Step Server, see chapter [Configuring Next Step](Configuring-Next-Step.md).
+Next step definitions need to be configured before deploying Next Step Server, see
+chapter [Configuring Next Step](Configuring-Next-Step.md).
 
 ## Next Step Server functionality
 
 Next Step Server implements following functionality:
+
 - management of next steps during authentication process
-  - step definitions are loaded from database when Next Step Server starts
-  - making decision about the next step of an operation given loaded step definitions, operation name, operation type, operation status and step authentication result
+    - step definitions are loaded from database when Next Step Server starts
+    - making decision about the next step of an operation given loaded step definitions, operation name, operation type,
+      operation status and step authentication result
 - management of authentication methods
-  - create an authentication method
-  - listing available authentication methods both general and user-specific
-  - enabling/disabling authentication methods per user including their configuration (configuration is required for the [Mobile Token](./Mobile-Token-Configuration.md))
-  - get a list of authentication methods currently enabled for the user  
-  - delete an authentication method
+    - create an authentication method
+    - listing available authentication methods both general and user-specific
+    - enabling/disabling authentication methods per user including their configuration (configuration is required for
+      the [Mobile Token](./Mobile-Token-Configuration.md))
+    - get a list of authentication methods currently enabled for the user
+    - delete an authentication method
 - management of operations
-  - create a new operation
-  - update an operation based on the next step decision
-  - retrieve operation detail
-  - list pending operations for user
-  - retrieve operation configuration for an operation or all defined operations
-  - update operation form data
-  - update user and organization for an operation
-  - update application context for an operation
-  - set chosen authentication method
-  - update mobile token status for an operation
-  - retrieve mobile token configuration
-  - get and update detailed authentication method and operation configuration
-  - authentication method downgrade for the next step
-  - enable PowerAuth token for the next step   
-  - integration with PowerAuth operations   
-  - store result of an AFS action
+    - create a new operation
+    - update an operation based on the next step decision
+    - retrieve operation detail
+    - list pending operations for user
+    - retrieve operation configuration for an operation or all defined operations
+    - update operation form data
+    - update user and organization for an operation
+    - update application context for an operation
+    - set chosen authentication method
+    - update mobile token status for an operation
+    - retrieve mobile token configuration
+    - get and update detailed authentication method and operation configuration
+    - authentication method downgrade for the next step
+    - enable PowerAuth token for the next step
+    - integration with PowerAuth operations
+    - store result of an AFS action
 - management of organizations
-  - create an organization
-  - list organizations
-  - retrieve organization detail
-  - delete an organization
+    - create an organization
+    - list organizations
+    - retrieve organization detail
+    - delete an organization
 - management of user identity
-  - user identity CRUD operations
-  - user contact CRUD operations
-  - user alias CRUD operations
-  - assignment of user roles
-  - blocking and unblocking of user identity
-  - obtaining user credential list
-  - obtaining user authentication history
-  - update status of multiple user identities
-  - lookup of user identities
-- management of Next Step applications  
+    - user identity CRUD operations
+    - user contact CRUD operations
+    - user alias CRUD operations
+    - assignment of user roles
+    - blocking and unblocking of user identity
+    - obtaining user credential list
+    - obtaining user authentication history
+    - update status of multiple user identities
+    - lookup of user identities
+- management of Next Step applications
 - management of credential policies
 - management of OTP policies
 - management of credential definitions
@@ -67,17 +74,32 @@ Next Step Server implements following functionality:
 
 REST services are available for all Next Step functionality listed above.
 
-The Next Step Server functionality is described in details in [Next Step Server REST API Reference](./Next-Step-Server-REST-API-Reference.md).
-
+The Next Step Server functionality is described in details
+in [Next Step Server REST API Reference](./Next-Step-Server-REST-API-Reference.md).
 
 ## OpenID Connect (OIDC)
 
 You may configure OpenID Connect (OIDC) authentication.
 
-| Property                                                | Default value | Description                                                                           |
-|---------------------------------------------------------|---------------|---------------------------------------------------------------------------------------|
-| `powerauth.nextstep.security.auth.type`                 |               | `OIDC` for OpenID Connect. If OIDC enabled, the properties bellow must be configured. |
-| `spring.security.oauth2.resource-server.jwt.issuer-uri` |               | URL of the provider, e.g. `https://sts.windows.net/example/`                          |
-| `spring.security.oauth2.resource-server.jwt.audiences`  |               | A comma-separated list of allowed `aud` JWT claim values to be validated.             |
+| Environment Variable                     | Default value | Description                                                                           |
+|------------------------------------------|---------------|---------------------------------------------------------------------------------------|
+| `NEXTSTEP_AUTH_TYPE`                     | NONE          | `OIDC` for OpenID Connect. If OIDC enabled, the properties bellow must be configured. |
+| `NEXTSTEP_SECURITY_AUTH_OIDC_ISSUER_URI` |               | URL of the provider, e.g. `https://sts.windows.net/example/`                          |
+| `NEXTSTEP_SECURITY_AUTH_OIDC_AUDIENCES`  |               | A comma-separated list of allowed `aud` JWT claim values to be validated.             |
+
+See
+the [Spring Security documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html#oauth2-client-log-users-in)
+and [OpenID Connect UserInfo endpoint](https://connect2id.com/products/server/docs/api/userinfo) for details. 
+
+## Enabling Record Encryption
+In order to enable the additional database record encryption, you need to set the following environment variable to the application:
+
+`NEXTSTEP_MASTER_DB_ENCRYPTION_KEY=[16 random bytes Base64 encoded, for example 'MTIzNDU2Nzg5MDEyMzQ1Ng==']`
+
+In case you lose the original master DB encryption key, there is no way to recover original data and your users will need to re-activate their mobile applications.
+
+The value of the key must be 16 random bytes, Base64 encoded.
 
-See the [Spring Security documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html#oauth2-client-log-users-in) and [OpenID Connect UserInfo endpoint](https://connect2id.com/products/server/docs/api/userinfo) for details. 
+## Enabling E2E encryption
+In order to enable end-to-end encryption of credentials, you need to set the following environment variable to the application: 
+`NEXTSTEP_E2E_ENCRYPTION_KEY=[32 random bytes Base64 encoded, for example 'SkJNSkp5eTZMRHk5N0RDSGRacEhhZlp0NnpValdOVksK']`