...
As an Administrator I should be able to create/update/reset password/deactivate customer login user and associate it to client id so that customer can login to the system and view/transact on their own accounts
As an Administrator I should be able to assign access permissions to the customer login user so that I can control what actions customer login user can perform on the system
As a customer I should be able to validate my username/password credentials with the system so that I can continue invoking APIs to view/transact on my accounts
As a customer I should be able to retrieve my personal details so that I can validate my personal data with the organization
As a customer I should be able to change my password credential so that I can keep my login access secureAs a customer I should be able to retrieve list of my savings accounts details so that I can be aware of my holdings
As a customer I should be able to retrieve transactions related to one of my savings accounts so that I am aware of details of my holdings
As a customer I should be able to retrieve charges related to one of my savings accounts so that I am aware of charges incurred on my transactions
As a customer I should be able to retrieve list of my loan account details so that I can be aware of my commitments/liabilities
As a customer I should be able to retrieve repayment schedule of one of my loan accounts so that I am aware of my commitments/liabilities
As a customer I should be able to retrieve transactions related to one of my loan accounts so that I am aware of details of my holdings
As a customer I should be able to retrieve charges related to one of my loan accounts so that I am aware of charges incurred on my transactions
...
Keeping ease of maintenance in mind, it is decided that this feature addition should reuse the existing services as much as possible. This will also help in extending new functionalities as well. This can be done in two ways: A) use Spring's RestTemplate and act like a client, or B) inject needed resources in the code. Option B is chosen to help reuse user activity logging and tracking.
Separate endpoint APIs
As suggested by Markus, setting up a separate resource endpoints is the right thing to do for at least one reason. If a MFI wants to ever make a public available web client that allows a customer to deal with his account(s) it is insecure to expose the whole back-office API to the world. With a dedicated API only this endpoint needs to be exposed and it would not be possible to trial the whole system and hack it.
...
We should build a service that can validate the API requests against the valid data scope assigned to self service user. A self service login user, should be able to view/transact only their loans and savings accounts. Also it should prevent the user from reading certain confidential information like notes and internal approval cycle.
Design
New Screens
Scope of this feature is to provide only platform capability and doesn't include any UI.
Separate
...
URL endpoints for customer self service
New root resource url /mifosng-selfservice would be defined where all the self service APIs would be exposed.The resources exposed as part of this root would be similar to /mifosng-provider root. For eg, API to get list of loans in self-service would be /mifosng-selfserviceAll the APIs resources for customer self service would start with /mifosng-provider/api/v1/loansself.This would be achieved similar to the suggestion provided here http://stackoverflow.com/questions/10231854/multiple-jersey-applications-with-same-path-for-root-resource
Having separate root context for this API comes with lot of complications. It would require changes at tomcat deployment level.
Identifying self service user
...
m_appusers table would be modified to add a column 'is_self_service_user to identify a self service API user.
...
This API would be available only /mifosng-provider root, indicating this is in control of back for back office/administrative user.
All the data scoping for self service user would be based on this client mapping.
In future, additional use cases like agent, staff with limited scope can be created with multiple client mapping in this table and they would get access to view/transact on only such clients.
...
A self service user should be able to use only self service APIs and back officer should not have access to self service APIs and vice versa.
Any APIs API with root /mifosng-provider should be accessible only for m_appusers whose is_self_service_user attribute is false and Any APIs with root /mifosng-selfservice URL containing /self/ should be accessible only for m_appusers whose is_self_service_user attribute is true.
Two new AuthenticationProvider classes would be created extending existing default spring DaoAuthenticationProvider one each for /mifosng-provider and /mifosng-selfservice rootsURLs with /self/ and one for existing APIs. These extensions would additionally check the is_self_service_user attribute and enforce proper authorisation.
Self Service User Role permissions
Existing Role permission APIs would be used. Due to differentiation of self service and back office user authorisation as explained above, a self service user will not have access to any APIs other than those exposed for self service channel.
New APIs for self service users
To start with, all the APIs exposed would support only GET methods. And data scope would be limited to clients association mapping to the user.
| Usecase | API | Notes | |
|---|---|---|---|
| Authentication Basic HTTP | /mifosng-selfserviceprovider/api/v1/self/authentication?username={username}&password={password} | ||
| Authentication Oauth2 | /mifosng-selfserviceprovider/api/self/oauth/token?username={username}&password={password}&client_id={clientId}&grant_type={grant_type}&client_secret={client_secret} | ||
| /mifosng-selfserviceprovider/api/self/oauth/token?refresh_token={refresh_token}&client_id={clientId}&grant_type={grant_type}&client_secret={client_secret} | |||
| /mifosng-selfserviceprovider/api/v1/self/userdetails?access_token={access_token} | |||
| List Clients | /mifosng-selfserviceprovider/api/v1/self/clients | Return list of clients mapped to given self service app user | |
| Retrieve a Client | /mifosng-selfserviceprovider/api/v1/self/clients/{clientId}Only approved and active clients | ||
| Retrieve client accounts overview | /mifosng-selfserviceprovider/api/v1/self/clients/{clientId}/accounts | Only approved and active accounts | |
| Get client image | /mifosng-selfserviceprovider/api/v1/self/clients/{clientId}/images | ||
| List client charges | /mifosng-selfserviceprovider/api/v1/self/clients/{clientId}/charges | ||
| Retrieve a client charge | /mifosng-selfserviceprovider/api/v1/self/clients/{clientId}/charges/{clientChargeId} | ||
| List client transactions | /mifosng-selfserviceprovider/api/v1/self/clients/{clientId}/transactions | ||
| Retrieve a client transaction | /mifosng-selfserviceprovider/api/v1/self/clients/{clientId}/transaction/{transactionId} | ||
| Retrieve a Savings Account | /mifosng-selfserviceprovider/api/v1/self/savingsaccounts/{accountId} | Only approved and active account | |
| List Savings account transactions | /mifosng-selfserviceprovider/api/v1/self/savingsaccounts/{accountId}/transactions | ||
| Retrieve a savings account transaction | /mifosng-selfserviceprovider/api/v1/self/savingsaccounts/{accountId}/transactions/{transactionId} | ||
| List Savings account charges | /mifosng-selfserviceprovider/api/v1/self/savingsaccounts/{accountId}/charges | ||
| Retrieve a savings account charge | /mifosng-selfserviceprovider/api/v1/self/savingsaccounts/{accountId}/charges/{savingsAccountChargeId} | ||
| Retrieve a Loan | /mifosng-selfserviceprovider/api/v1/self/loans/{loanId} | Only approved and active account | |
| List loan account transactions | /mifosng-selfserviceprovider/api/v1/self/loans/{loanId}/transactions | ||
| Retrieve loan account transaction | /mifosng-selfserviceprovider/api/v1/self/loans/{loanId}/transactions/{transactionId} | ||
| List loan account charges | /mifosng-selfserviceprovider/api/v1/self/loans/{loanId}/charges | ||
| Retrieve a loan account charge | /mifosng-selfservice/api/v1/loans/{loanId}/charges/{chargeId} |
User interaction and design
Exception Handling
Reporting
APIs
...
Data scoping self service API
A new service would be written to validate the request parameters against the Data scope for the given user. Parameters for each API would be validated for client id, loan id, account id, additional parameter requests etc. On invalid requests appropriate AuthenticationException would be thrown.
Role permissions verification would be taken care by the existing service implementations.
Notes
On this feature deployment, all the existing users will be marked as non-self service user.
Questions
Below is a list of questions to be addressed as a result of this requirements document:
| Question | Outcome |
|---|---|
Out of Scope
- Transfers within/outside client accounts are not considered yet.