Skip to content
This repository has been archived by the owner on Jul 22, 2024. It is now read-only.

Store and access sensitive and confidential documents in a secure way

License

Notifications You must be signed in to change notification settings

IBM/store-and-access-documents-securely

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

35 Commits
 
 
 
 
 
 
 
 

Repository files navigation

Securely store and share documents

Data provides a critical foundation for every operation of your organization. Organizations collect a lot of data, including documents, from its customers. It is very important for organizations to have a robust security mechanism to secure sensitive customer documents. In addition to securing these documents using authentication and authorization of application, data should be encrypted and stored in a secure storage.

In the financial services domain, businesses collect, generate and store documents. Customer on-boarding, Loan origination or Know your customer are some common scenarios.

This code pattern focusses on the two specific processes in a banking scenario:

  • Opening of a savings bank account.
  • Loan origination.

The customer submits documents for identification proof and address proof during the opening of a Savings account at a bank. These documents are stored in a shared storage. These documents are verified and approved for the opening of the Savings account. Next, the customer applies for a loan with loan department of the bank. The loan department needs the identification proof and address proof as part of the loan approval process. The customer does not need to re-submit these documents as it has been already submitted during the savings account opening. These documents are accessed from the shared storage by the Loan deparment official for processing the loan application.

This code pattern will demonstrate the following:

  • Deploying a simple account opening banking application on OpenShift.
  • How to integrate Security Verify with the banking application to provide authentication and authorization for users.
  • How to securely store customer provided documents to IBM Cloud Object Storage.
  • Data Encryption using IBM Key Protect for IBM Cloud.
  • Securely access the stored customer documents for a loan approval process.

architecture

Flow

  1. User(end user/bank official) access the application.
  2. User registration/login to the application.
  3. Front end application accesses.
  • The savings account service to get savings account details.
  • The loan account service to apply/get loan account details.
  • The approval service (bank official) to approve/reject savings account and loan account requests.
  1. The services (savings account, loan account and approval) use data access service and document access service to store/retrieve account details and documents to database and IBM Cloud Object Storage.
  2. Database to store account details.
  3. IBM Cloud Object Storage to store user documents.
  4. Documents are encrypted in IBM Cloud Object Storage.

Prerequisites

Steps

  1. Clone the repository
  2. Create IBM Cloud Services instances
  3. Configuration of services
  4. Deploy Microservices
  5. Access the Application

1. Clone the repository

From a command terminal, run the below command to clone the repo:

git clone https://github.com/IBM/store-and-access-documents-securely

2. Create IBM Cloud Services instances

2.1 Sign up for IBM Security Verify

Click Security Verify to sign up for Security Verify. After you sign up for an account, the account URL (https://[tenant name].verify.ibm.com/ui/admin) and password is sent in an email.

2.2 Create IBM DB2 Service instance

In IBM Cloud Catalog search of DB2. Click on the Db2 tile. .

Select an appropriate plan. Read and accept the license agreement. You may leave the other options to their default values. Click on Create button. It will take a minute or so to provision an instance.

Make a note of service credentials

  • Click the newly created db2 entry in IBM Cloud Resource list
  • Click Service credentials on the left hand side navigation menu. If there are no credentials, then click on New credential button and create new credentials.

  • Copy the credentials and paste the contents in the file <cloned repo parent folder>/sources/data-access-service/src/main/resources/credentials-db2.json.
  • Make a note of username value. This value will be used to create database tables.
  • Save the file.

2.3 Create Cloud Object Storage instance

Use the following commands to create the service instance:

  ibmcloud login ## Login using CLI if not done already
  ibmcloud target -r <region_name> -g <resource_group_name> -o <org_name> -s <space_name>
  ibmcloud resource service-instance-create <instance-name> cloud-object-storage lite global ## Make a note of the GUID in the output
  ibmcloud resource service-key-create skey --instance-id <GUID of Object Storage instance noted above>  ## it will create a service id, make a note of that

Make a note of service credentials, it will be required later.

2.4 Create Key Protect Service instance

Create a Key protect service instance using the following commands:

ibmcloud resource service-instance <instance-name> ## make a note of the GUID in the output
##install key protect plugin
ibmcloud plugin install key-protect -r "IBM Cloud"
ibmcloud kp region-set <region>  ##for example us-south
ibmcloud kp key create <name-of-the-key> -i <GUID of Key Protect instance noted above>

Make a note of service credentials to use in further steps.

3. Configure services

3.1 Configure Key Protect

Grant access of the Key Protect to the Object Storage

Run the following command to create authorization policy:

ibmcloud iam authorization-policy-create cloud-object-storage kms Reader --source-service-instance-id [GUID of Cloud Object Storage Instance]  --target-service-instance-id [GUID of Key-Protect instance]

Get the root key CRN value using IBM Cloud Dashboard. You can refer to step 5 here for more details.

3.2 Configure Security Verify

Add a custom application

  • Login to Security Verify. Use the URL for your admin account that was sent to you in the confirmation email: https://[tenant name].verify.ibm.com/ui/admin.
  • Select Applications from the menu on the left.
  • To add an application, click Add application.
  • Select Custom Application as the application type, then click Add application.
  • Specify a name for the application. Then, on the General tab, specify a company name.
  • Click the Sign-on tab. Configure SSO using the OpenID Connect based authentication with Authorization code scheme. Specify these values:
    • For the Sign-on method, select Open ID Connect 1.0.
    • For the Application URL, enter the URL you noted for the front end UI application
    • For the Grant types, check Authorization code.
    • Uncheck Require proof key for code exchange (PKCE) verification.
    • For Redirect URIs, enter the re-direct URL on the front end application.
    • Click Save to save this SSO configuration. Configure SSO
  • Click the Entitlements tab. For the Access Type, select Automatic access for all users and groups. Click Save to save the custom application.
  • Click the Sign-on tab. Note down the client ID and the client secret. This is needed for configuring the front-end gateway service.

Note Security Verify endpoints In the far right information pane, note down the IBM Security Verify endpoint.

Note endpoint.

Then, note down the following endpoints: authorization_endpoint, token_endpoint and introspection_endpoint. These will be needed to configure our application microservices to integrate with Security Verify.

Note profile id Note the profile id.It is needed in configuring the front-end gateway service.

profile-id.

Add an API Client

  • Click on the API Access tab on application settings
  • Click on Add API Client button
  • Enter a name and click on Save
  • Again click Save on the parent settings page. The credentials will now be generated.

Save API Client

  • Select the added API Client. On the right pane, the generated credentials can be copied. Make a note of the credentials. They will be needed for the Approval service configuration. Also note that this is different from the client-id and client-secret we noted when you created the SSO configuration.

Note API Client credentials

Add users in Security Verify

Let us add two users savings_official and loan_official. These user names will be used by the bank employees in this code pattern.

Click on Add user .

Click Add User

Enter the user details as shown for user savings_official. Enter a valid e-mail. The password will be emailed to the specified address. Click Save.

Enter user details

Repeat the above steps to create a user for loan_official.

Note: The same e-mail id can be used for both the users.

3.3 Configure DB2 database

Create database tables

  • Click the newly created db2 entry in IBM Cloud Resource list

  • Click on Go to UI

  • Click the SQL (Run SQL when you expand the menu) tile

  • Click on From file and select <cloned repo parent folder>/sources/data-access-service/dbscripts.sql. Click Open.

  • The scripts to create tables are copied to SQL editor.

  • Update all the occurances of <schema_name> with the schema name that was noted above.

  • Click Run all option.

  • The results of running these queries are shown on the right hand side of the SQL editor. Verify that all the tables, as mentioned in script, are created.

4. Deploy Microservices

Login to your OpenShift cluster from command line

Login to your OpenShift cluster. Access the IBM Cloud Dashboard > Clusters (under Resource Summary) > click on your OpenShift Cluster > OpenShift web Console. Click the dropdown next to your username at the top of the OpenShift web console and select Copy Login Command. Select Display Token and copy the oc login command from the web console and paste it into the terminal on your workstation. Run the command to login to the cluster using oc command line.

4.1 Deploy Data Access Service

On the terminal window, change directory to <cloned repo parent folder>/sources/data-access-service.

Run the following commands to deploy data access service.

oc new-project ssd-das
mvn clean install
oc new-app . --name=data-access-service --strategy=docker
oc start-build data-access-service --from-dir=.
oc logs -f bc/data-access-service
oc expose svc/data-access-service

Ensure that the application is started successfully using the command oc get pods. Also make a note of the route using the command oc get routes. The route will be provided in the configuration of other microservices requiring integration with data access service.

4.2 Deploy Document Access Service

On the terminal, run the following commands.

cd <cloned repo parent folder>/sources/document-access-service
cp .env.sample .env

Update the object storage service and key protect service credentials in .env and save it.

Run the following commands to deploy document-access-service.

  oc new-project document-access
  oc new-app . --name=document-access-service --strategy=docker
  oc start-build document-access-service --from-dir=.

  oc logs -f bc/doc-access-service ## it takes time and wait till it gets completed
  oc get pods 

  oc expose svc/doc-access-service
  oc get routes 

Ensure that the application is started successfully using the command oc get pods. Also make a note of the route using the command oc get routes. The route will be provided in the configuration of other microservices requiring integration with document access service.

Create bucket

Run the API http://<your_service_route>/create-bucket-kp on your browser to create bucket in your cloud object storage instance. It will create the bucket with the name provided in .env.

4.3 Deploy Approval Service

Approval Service accesses Data Access Service. So, you need to update the file <cloned repo parent folder>/sources/approval-service/src/main/resources/config/config.properties. Update the entry DAS_BASE_URL to http://<data-access-service-route>/DAS/ as noted in section 4.1.

Enter the introspection_endpoint url noted in the Note Security Verify endpoints section above. Enter the client_id and client_secret noted in the Add an API Client section above.

TOKEN_URL=https://{{tenant_id}}.verify.ibm.com/v1.0/endpoint/default/introspect
CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_ID=xxxxxxxxxx
USER_URL=https://{tenant_url}/v2.0/Users

Save the file.

Change directory to <cloned repo parent folder>/sources/approval-service and run the following commands to deploy approval service.

oc new-project ssd-approval
mvn clean install
oc new-app . --name=approval-service --strategy=docker
oc start-build approval-service --from-dir=.
oc logs -f bc/approval-service
oc expose svc/approval-service

Ensure that the application is started successfully using the command oc get pods. Also make a note of the route using the command oc get routes. The route will be provided in the configuration of other microservices requiring integration with approval service.

4.4 Deploy Loan Accounts Service

On a terminal window, change directory to <cloned repo parent folder>/sources/loan-service. Ensure you are logged in to the cluster from command line.

Add security verify configuration for token instrospection

Open the file verify.config file under src/main/resources folder. Enter the introspection_endpoint url noted in the Note Security Verify endpoints section above. Enter the client_id and client_secret noted in the Add a custom application section above.

introspectionUrl=https://{{tenant_id}}.verify.ibm.com/v1.0/endpoint/default/introspect
clientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
clientSecret=xxxxxxxxxx

Save the file.

Open the file config.properties file under src/main/resources folder. Update the Data Access Service url and Document Access Service url in the file as shown below:

documentSvcUrl={{Document Access Service URL}}/upload-file
dataAccessSvcUrl={{Data Access Service URL}}/DAS/loan-account

Now, go back to the directory <cloned repo parent folder>/sources/savings-service.

Run the following commands to deploy Loan account service.

oc new-project loan-project
mvn clean install
oc new-app . --name=loan-service --strategy=docker
oc start-build loan-service --from-dir=.
oc logs -f bc/loan-service
oc expose service/loan-service

Ensure that the application is started successfully using the command oc get pods.

Make a note of the route to the loan-service using the command oc get routes. The route will be provided in the configuration of other microservices requiring integration with loan-service.

4.5 Deploy Savings account service

On a terminal window, change directory to <cloned repo parent folder>/sources/savings-service. Ensure you are logged in to the cluster from command line.

Add security verify configuration for token instrospection

Open the file verify.config file under src/main/resources folder. Enter the introspection_endpoint url noted in the Note Security Verify endpoints section above. Enter the client_id and client_secret noted in the Add a custom application section above.

introspectionUrl=https://{{tenant_id}}.verify.ibm.com/v1.0/endpoint/default/introspect
clientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
clientSecret=xxxxxxxxxx

Save the file.

Open the file config.properties file under src/main/resources folder. Update the Data Access Service url and Document Access Service url in the file as shown below:

documentSvcUrl={{Document Access Service URL}}/upload-file
dataAccessSvcUserUrl={{Data Access Service URL}}/DAS/user
dataAccessSvcSavingUrl={{Data Access Service URL}}/DAS/savings-account

Now, go back to the directory <cloned repo parent folder>/sources/savings-service.

Run the following commands to deploy Savings account service.

oc new-project savings-project
mvn clean install
oc new-app . --name=savings-service --strategy=docker
oc start-build savings-service --from-dir=.
oc logs -f bc/savings-service
oc expose service/savings-service

Ensure that the application is started successfully using the command oc get pods. Make a note of the route to the saving-service using the command oc get routes. The route will be provided in the configuration of other microservices requiring integration with savings-service.

4.6 Deploy Frontend Service

On the terminal, access the code of frontend-service using the following commands.

cd <cloned repo parent folder>/sources/frontend-service
cp .env.sample .env

Update the security verify credentials and other deployed microservices URL in .env. The client-id and client-secret should be the one noted in the Add a custom application section. The profile-id noted earlier must be entered against the REGISTRATION_PROFILE_ID.

TENANT_URL=https://[tenant-id].verify.ibm.com
CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_SECRET=xxxxxxxxxx
REDIRECT_URI=http://[your deployed application route]/redirect
RESPONSE_TYPE=code
FLOW_TYPE=authorization
SCOPE=openid
REGISTRATION_PROFILE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
~                                                            

Note: REDIRECT_URI should be <your deployed application route>/redirect. The base URL of the deployedfront-end service must be replaced for the REDIRECT_URI. The REDIRECT_URI must match the configuration on Security Verify that you specified in Add a custom application section.

Update the URLs of the deployed services in .env.

APPROVAL_SERVICE_URL=
LOAN_ACCOUNT_SERVICE_URL=
SAVINGS_ACCOUNT_SERVICE_URL=

After making all the required changes in .env, you are good to deploy frontnd service. Login to the OpenShift cluster from the command line and then run the following commands to deploy frontend-service.

  oc new-project frontend-svc
  oc new-app . --name=frontend-service --strategy=docker
  oc start-build frontend-service --from-dir=.

  oc logs -f bc/frontend-service ## it takes time and wait till it gets completed
  oc get pods ##pod should be in running state else wait for sometime

  oc expose svc/frontend-service
  oc get routes 

Ensure that the application is started successfully using the command oc get pods. Also make a note of the route using the command oc get routes. The route will be used to access the application.

5. Access the Application

Access the application using the route of frontend service deployed in step 4.6. As a first step, you need to submit request for savings account creation as shown below.

Once the request of savings account is submitted, it goes for approval to Savings branch official. In this code pattern, we have already created credentials of savings branch official in step 3.2. Savings branch Official logs-in using appropriate credentials and gets a list of savings account requests submitted newly. The official person verifies the data and document provided by the user and then accordingly approve or reject the request as shown below.

Upon savings account approval, user's credentials gets created and emailed to user. Using those credentails, user can log-in to check his savings account details. So far, only savings account of that user exists. If the user wants to apply for loan, he can do as shown below. For loan, he needs to provide all the required details and documents similar to savings account.

Loan request goes to loan branch official. The official verifies all the required details and document and accordingly approve or reject the request.

If the loan request is approved, it will be visible on user dashboard. User can login again and check as shown below.

Summary

In this code pattern, you saw how a secure storage solution can be implemented on IBM Cloud. In this application, only the authenticated and authorized user can access the application using IBM Security Verify. In addition, all the microservices were protected using token introspection with Security Verify. The documents were encrypted using IBM Key Protect and stored securely on IBM Cloud Object Storage.

This solution is applicable to all business processes where documents need to be stored and accessed securely.

License

This code pattern is licensed under the Apache License, Version 2. Separate third-party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 and the Apache License, Version 2.

Apache License FAQ

About

Store and access sensitive and confidential documents in a secure way

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published