diff --git a/docs/Home.md b/docs/Home.md index f4f509035..c16d9bebc 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -6,6 +6,7 @@ PowerAuth Enrollment Server is an easy to deploy backend service used for bootst - [Deploying Enrollment Server](./Deploying-Enrollment-Server.md) - [Deploying Enrollment Server on JBoss/Wildfly](./Deploying-Wildfly.md) +- [Migration Instructions](./Migration-Instructions.md) - [Configuration Properties](./Configuration-Properties.md) - [Documentation for Onboarding Server](./onboarding/Home.md) diff --git a/docs/Migration-Instructions.md b/docs/Migration-Instructions.md new file mode 100644 index 000000000..2950d2c3e --- /dev/null +++ b/docs/Migration-Instructions.md @@ -0,0 +1,5 @@ +# Migration Instructions + +This page contains PowerAuth Enrollment Server migration instructions. + +- [PowerAuth Enrollment Server 1.4.0](./PowerAuth-Enrollment-Server-1.4.0.md) diff --git a/docs/Operation-Extensions.md b/docs/Operation-Extensions.md index 43357d521..73bc71f37 100644 --- a/docs/Operation-Extensions.md +++ b/docs/Operation-Extensions.md @@ -2,11 +2,79 @@ Enrollment server may expose mobile token API `api/auth/token/app`, if `enrollment-server.mtoken.enabled` set to `true`. -## Operation Templates +## Operation Templates UI Extension Behavior of the mobile application may be affected via UI JSON at operation template. +Here is an example of complete UI extension. +It will be explained in detail below. -### Post Approval Screen +```json +{ + "flipButtons": true, + "blockApprovalOnCall": false, + "preApprovalScreen": { + "type": "WARNING", + "heading": "Watch out!", + "message": "You may become a victim of an attack.", + "items": [ + "You activate a new app and allow access to your accounts", + "Make sure the activation takes place on your device", + "If you have been prompted for this operation in connection with a payment, decline it" + ], + "approvalType": "SLIDER" + }, + "postApprovalScreen": { + "type": "MERCHANT_REDIRECT", + "heading": "Thank you for your order", + "message": "You will be redirected to the merchant application.", + "payload": { + "redirectText": "Go to the application", + "redirectUrl": "https://www.example.com", + "countdown": 5 + } + } +} +``` + +### Risk Flags + +If you define any UI extension, the operation risk flags are overridden. + +| Attribute | Required | Default | Risk Flag | Description | +|-----------------------|----------|---------|-----------|-------------------------------------------------------------------------------------------| +| `flipButtons` | `false` | `false` | `X` | Flip the approve and reject buttons on the approval screen. | +| `blockApprovalOnCall` | `false` | `false` | `C` | Block approving the operation in case there is an ongoing call. | +| `preApprovalScreen` | `false` | | `F` | Optional information about screen that should be displayed before the operation approval. | + +### Pre-approval Screen + +Optional information about screen that should be displayed before the operation approval. + +```json +{ + "preApprovalScreen": { + "type": "WARNING", + "heading": "Beware of Cyber-Attacks!", + "message": "This operation is often abused by fraudsters.", + "items": [ + "You are activation a new mobile app and provide access to your account.", + "Make sure the activation is happening on the device you own.", + "If you were asked for this operation over phone, reject it." + ], + "approvalType": "SLIDER" + } +} +``` + +| Attribute | Required | Default | Description | +|----------------------------------|----------|---------|----------------------------------------------------------------------------------------------------| +| `preApprovalScreen.type` | `true` | - | Type of the screen. Use `WARNING` for warning screen, and `INFO` for a general information screen. | +| `preApprovalScreen.heading` | `true` | - | Heading of the screen. | +| `preApprovalScreen.message` | `true` | - | Message displayed to the user, placed under the screen heading. | +| `preApprovalScreen.items` | `false` | `null` | Bullet point items displayed by the message. | +| `preApprovalScreen.approvalType` | `true` | - | Type of the approval screen component. Currently, only a `SLIDER` option is available. | + +### Post-approval Screen You may define a screen visible after approval of the operation. There are three types available: `REVIEW`, `MERCHANT_REDIRECT`, and `GENERIC`. @@ -14,7 +82,7 @@ It is possible to substitute template variables based on operation parameters, e #### Review -Payload of the review post approval screen shows the operation attributes. +Payload of the review post-approval screen shows the operation attributes. Mind that the payload attributes must be specified again at `es_operation_template.ui`. It usually could be only subset of `es_operation_template.attributes`. @@ -41,7 +109,7 @@ It usually could be only subset of `es_operation_template.attributes`. #### Merchant Redirect -Payload of the merchant redirect post approval screen contains three attributes. +Payload of the merchant redirect post-approval screen contains three attributes. - `redirectUrl` - URL to redirect, might be a website or application - `redirectText` - Label of the redirect URL @@ -64,7 +132,7 @@ Payload of the merchant redirect post approval screen contains three attributes. #### Generic -Payload of the generic post approval screen may contain any object. +Payload of the generic post-approval screen may contain any object. ```json { diff --git a/docs/PowerAuth-Enrollment-Server-1.4.0.md b/docs/PowerAuth-Enrollment-Server-1.4.0.md new file mode 100644 index 000000000..7ea34879a --- /dev/null +++ b/docs/PowerAuth-Enrollment-Server-1.4.0.md @@ -0,0 +1,213 @@ +# Migration from 1.3.x to 1.4.x + +This guide contains instructions for migration from PowerAuth Enrollment Server version `1.3.x` to version `1.4.0`. + +Since version 1.4.0, there are two war files available. + +- `enrollment-server.war` - Original Enrollment server functionality. +- `enrollment-server-onboarding.war` - Onboarding functionality using government-identification and user verifications. + +## Onboarding Server + +The Onboarding Server has been introduced as a separate war module, see [Documentation for Onboarding Server](./onboarding/Home.md) +and [Onboarding Server Database Structure](./onboarding/Database-Structure.md) +This module is optional. + +### Onboarding Server Configuration + +If you want to integrate Onboarding Server, add this dependency to your Enrollment Server. + +```xml + + com.wultra.security + enrollment-server-onboarding-common + ${project.version} + +``` + +And configuration of the common beans, for example. + +```java +@Configuration +@EnableJpaRepositories(basePackages = { + "com.wultra.app.enrollmentserver.database", // not to override component scan for enrollment-server + "com.wultra.app.onboardingserver.common.database" // dependencies from enrollment-server-onboarding common +}) +@EntityScan(basePackages = { + "com.wultra.app.enrollmentserver.database.entity", // not to override component scan for enrollment-server + "com.wultra.app.onboardingserver.common.database.entity" // dependencies from enrollment-server-onboarding common +}) +public class OnboardingComponentsConfiguration { + + /** + * Register onboarding service bean. + * + * @param onboardingProcessRepository onboarding process repository + * @param auditService Audit service. + * @return onboarding service bean + */ + @Bean + public OnboardingService onboardingService(final OnboardingProcessRepository onboardingProcessRepository, final AuditService auditService) { + return new CommonOnboardingService(onboardingProcessRepository, auditService); + } + + /** + * Register otp service bean. + * + * @param onboardingOtpRepository onboarding otp repository + * @param onboardingProcessRepository onboarding process repository + * @param identityVerificationRepository Identity verification repository. + * @param onboardingConfig onboarding config + * @param auditService Audit service. + * @return otp service bean + */ + @Bean + public OtpService otpService( + final OnboardingOtpRepository onboardingOtpRepository, + final OnboardingProcessRepository onboardingProcessRepository, + final IdentityVerificationRepository identityVerificationRepository, + final CommonOnboardingConfig onboardingConfig, + final OnboardingProcessLimitService processLimitService, + final IdentityVerificationLimitService identityVerificationLimitService, + final AuditService auditService) { + + return new CommonOtpService(onboardingOtpRepository, onboardingProcessRepository, identityVerificationRepository, onboardingConfig, processLimitService, identityVerificationLimitService, auditService); + } + + /** + * Register onboarding config bean. + * + * @return onboarding config bean + */ + @Bean + public CommonOnboardingConfig onboardingConfig() { + return new CommonOnboardingConfig(); + } + + /** + * Register process limit service. + * @param config Common onboarding process configuration. + * @param onboardingProcessRepository Onboarding process repository. + * @param auditService Audit service. + * @return Onboarding process limit service. + */ + @Bean + public OnboardingProcessLimitService processLimitService( + final CommonOnboardingConfig config, + final OnboardingProcessRepository onboardingProcessRepository, + final AuditService auditService) { + + return new OnboardingProcessLimitService(config, onboardingProcessRepository, auditService); + } + + /** + * Register identity verification limit service. + * @param identityVerificationRepository Identity verification repository. + * @param documentVerificationRepository Document verification repository. + * @param config Onboarding configuration. + * @param onboardingProcessRepository Onboarding process repository. + * @param activationFlagService Activation flag service. + * @param onboardingProcessLimitService Onboarding process limit service. + * @param auditService Audit service. + * @return Identity verification limit service. + */ + @Bean + public IdentityVerificationLimitService identityVerificationLimitService( + final IdentityVerificationRepository identityVerificationRepository, + final DocumentVerificationRepository documentVerificationRepository, + final CommonOnboardingConfig config, + final OnboardingProcessRepository onboardingProcessRepository, + final ActivationFlagService activationFlagService, + final OnboardingProcessLimitService onboardingProcessLimitService, + final AuditService auditService) { + + return new IdentityVerificationLimitService(identityVerificationRepository, documentVerificationRepository, config, onboardingProcessRepository, activationFlagService, onboardingProcessLimitService, auditService); + } + + /** + * Register activation flag service. + * @param powerAuthClient PowerAuth client. + * @param httpCustomizationService HTTP customization service. + * @return Activation flag service. + */ + @Bean + public ActivationFlagService activationFlagService(PowerAuthClient powerAuthClient, HttpCustomizationService httpCustomizationService) { + return new ActivationFlagService(powerAuthClient, httpCustomizationService); + } + + /** + * Register activation otp service bean. + * + * @param otpService otp service + * @return activation otp service bean + */ + @Bean + public ActivationOtpService activationOtpService(final OtpService otpService) { + return new ActivationOtpService(otpService); + } + + /** + * Register activation process service bean. + * + * @param onboardingService onboading service + * @return activation process service bean + */ + @Bean + public ActivationProcessService activationProcessService(final OnboardingService onboardingService) { + return new ActivationProcessService(onboardingService); + } + + /** + * Register activation exception handler for onboarding. + * @return Activation exception handler. + */ + @Bean + @Order(Ordered.HIGHEST_PRECEDENCE) + public ActivationExceptionHandler activationExceptionHandler(){ + return new ActivationExceptionHandler(); + } + + /** + * Register audit service. + * + * @param audit Audit. + * @return Audit service. + */ + @Bean + public AuditService auditService(final Audit audit) { + return new AuditService(audit); + } +} +``` + +## Database Changes + +### Operation Template + +A new column `ui` has been added to the table `es_operation_template`. + +#### PostgreSQL + +```sql +ALTER TABLE es_operation_template + ADD COLUMN ui TEXT; +``` + +#### Oracle + +```sql +ALTER TABLE es_operation_template + ADD ui CLOB; +``` + +#### MySQL + +```sql +ALTER TABLE es_operation_template + ADD COLUMN ui TEXT; +``` + +## Inbox + +Inbox functionality is turned on by default if PowerAuth Push Server is running. +It could be turned off by setting property `enrollment-server.inbox.enabled` to `false`. diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index 7f0927cd0..fac9c4293 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -2,6 +2,7 @@ - [Deploying Enrollment Server](./Deploying-Enrollment-Server.md) - [Deploying Enrollment Server on JBoss/Wildfly](./Deploying-Wildfly.md) +- [Migration Instructions](./Migration-Instructions.md) - [Configuration Properties](./Configuration-Properties.md) - [Documentation for Onboarding Server](./onboarding/Home.md)