This documentation is for WSO2 Open Banking version 1.4.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

WSO2 Open Banking for Australia currently supports only evaluation purposes. This is available only as a WUM update and is effective from December 02, 2019 (12-02-2019). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

WSO2 Open Banking now supports the Consumer Data Standard (CDS). This document guides you through the configurations and troubleshooting that you need to set up the solution in your local environment. 

The scripts for the below local setup in the Quick Start Guide are configured for a Linux and MySQL/MSSQL environment. Notice that WSO2 Open Banking solution is applicable to Windows/Linux and MySQL/MSSQL and Oracle environments.

Prerequisites

  1. Download Oracle JDK 1.8 in all the nodes of the setup.
    • In the environment variables, update the JAVA_HOME and PATH variables. For instance, you can do this on a Mac/Linux server by adding the following to the ~/.bashrc file:

      export JAVA_HOME="<JDK_LOCATION>"
      
      export PATH=$PATH:$JAVA_HOME/bin
  2. Download and unzip the following files:

    • wso2-obam-1.4.0.zip (WSO2 Open Banking API Manager) 

    • wso2-obkm-1.4.0.zip (WSO2 Open Banking Key Manager)

     Click here to see how to download the packs from WUM

    Set up the WSO2 Update Manager (WUM). 

    • WUM is a simple command-line tool that connects to the WSO2 update service, determines which updates are new and relevant, and downloads them. You can get the latest version of the WSO2 Open Banking product packs through WUM.

    License

    WSO2 Open Banking is not distributed under the Apache Community License and is only available under the WSO2 Software License. You need a WSO2 subscription to install and update the WSO2 Open Banking solution via WUM. Contact us to find out how you can access a free evaluation copy...

    • Follow the guidelines provided in the Download WUM page to download, and install WUM in your environment. For more information on how to use WUM, see the WUM documentation.

        1. Add the necessary product packs using the commands given below:

          wum add wso2-obam-1.4.0              		 	                	     
          wum add wso2-obkm-1.4.0 
        2. Update the product packs using the commands given below:

          wum update wso2-obam-1.4.0	                	     
          wum update wso2-obkm-1.4.0               	     
        3. Additionally, download and update the other instances of WSO2 Open Banking product.

          wum add wso2ei-6.4.0
          wum update wso2ei-6.4.0
          
          wum add wso2am-analytics-2.6.0    
          wum update wso2am-analytics-2.6.0 
             
          wum add wso2-obbi-1.4.0
          wum update wso2-obbi-1.4.0

          WSO2 OB APIM Analytics(wso2am-analytics-2.6.0) provides the API analytics feature.

          WSO2 OB BI(wso2-obbi-1.4.0) provides the following features:

          • API Analytics

          • Transaction Risk Analysis

          • Fraud Detection

          • Data Reporting

    • The product packs reside in the <WUM_HOME>/products/<Product_Name>/<version>/full directory as <Product_name-<version>+<timestamp>.full.zip. Copy the product packs to a preferred location in each node, and extract them.

      This document refers to the file paths of the product packs for the Key Manager, API Manager, API Manager Analytics, and Enterprise Integrator as <WSO2_OB_KM_HOME>, <WSO2_OB_APIM_HOME>, <WSO2_AM_ANALYTICS_HOME>,<WSO2_OB_BI_HOME> and <WSO2_EI_HOME> respectively.



  3. Setup a database server using MySQL 5.7+, Microsoft SQL Server 2016+ or, Oracle 12c.

Setting up the databases

To start the servers, configure the databases in both the API Manager (WSO2 OB APIM) and the Key Manager (WSO2 OB KM) according to the open banking specification, as follows:

  1. Open the <WSO2_OB_KM_HOME>/repository/resources/finance/scripts/startup.properties file and configure the following:

    • Specify the hostnames for the APIM and KM servers.

      # Specify the hostname you want to configure
      APIM_HOSTNAME=localhost
      IAM_HOSTNAME=localhost
    • Configure the databases related properties.

      Database PropertyDescription
      DB_TYPE

      Type of the database you installed

      DB_TYPE=mysql
      DB_USER Database user
      DB_PASS Password set for the database connection
      DB_HOST Name of the database server
      DB_DRIVER

      Configure DB_DRIVER according to the database installed:

      • Mysql JDBC Driver : com.mysql.jdbc.Driver 
      • MSSQL JDBC Driver : com.microsoft.sqlserver.jdbc.SQLServerDriver
      • Oracle JDBC Driver : oracle.jdbc.driver.OracleDriver

      If you are using MSSQL or Oracle, create the following databases before executing the configure-km.sh file.

      • openbank_am_configdb   

      • openbank_apimgt_statsdb

      • openbank_apimgtdb

      • openbank_openbankingdb

      • openbank_govdb

      • openbank_iskm_configdb       

      • openbank_mbstoredb

      • openbank_userdb

  2. Go to the <WSO2_OB_KM_HOME>/repository/resources/finance/scripts directory and execute the following command:

    ./configure-km.sh
  3. Go to the <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts directory and configure the database properties in the startup.properties file, similar to Step 1.

  4. Go to the <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts directory and execute the following command:

    ./configure-am.sh

    You have configured the databases in step 1. By running the configure.sh files, you set the database credentials with reference to the configuration files.

Setting up the servers

  1. Configure the open-banking specification to deploy the solution according to the AU specification. 

    The <DeployedSpecification> configuration is used to define the deployed specification at runtime. In the following files, update the <DeployedSpecification> value as AU.

    • <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml 

    • <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml
  2. Configure the authentication web app.

    1. Update the <WSO2_OB_KM_HOME>/repository/conf/identity/application-authentication.xml file with the following configurations:

      <AuthenticationEndpointURL>https://localhost:9446/authenticationendpoint/login.do</AuthenticationEndpointURL>
      <AuthenticationEndpointRetryURL>https://localhost:9446/authenticationendpoint/retry.do</AuthenticationEndpointRetryURL>
      <AuthenticationEndpointMissingClaimsURL>/authenticationendpoint/claims.do</AuthenticationEndpointMissingClaimsURL>
      <AuthenticatorConfig  name="FIDOAuthenticator" enabled="true">
      	<Parameter name="FidoAuth">/authenticationendpoint/fido-auth.jsp</Parameter>
      	<!--Please uncomment the following property and define AppID if you are using proxy configurations-->
      	<!--<Parameter name="AppID">https://localhost</Parameter>-->
      </AuthenticatorConfig>
    2. Update the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file with the following configurations:

      <OpenID>
      	<OpenIDLoginUrl>${carbon.protocol}://${carbon.host}:${carbon.management.port}/authenticationendpoint/openid_login.do
      	</OpenIDLoginUrl>
      </OpenID>
      <OAuth>
      	<OAuth2ConsentPage>${carbon.protocol}://localhost:${carbon.management.port}/ob/authenticationendpoint/oauth2_authz.do</OAuth2ConsentPage>
      	<OAuth2ErrorPage>${carbon.protocol}://localhost:${carbon.management.port}/authenticationendpoint/oauth2_error.do</OAuth2ErrorPage>
      	<OIDCConsentPage>${carbon.protocol}://localhost:${carbon.management.port}/ob/authenticationendpoint/oauth2_consent.do</OIDCConsentPage>
      	<OIDCLogoutConsentPage>${carbon.protocol}://localhost:${carbon.management.port}/authenticationendpoint/oauth2_logout_consent.do</OIDCLogoutConsentPage>
      	<OIDCLogoutPage>${carbon.protocol}://localhost:${carbon.management.port}/authenticationendpoint/oauth2_logout.do</OIDCLogoutPage>
      </OAuth>
      <SSOService>
      	<DefaultLogoutEndpoint>${carbon.protocol}://${carbon.host}:${carbon.management.port}/authenticationendpoint/samlsso_logout.do</DefaultLogoutEndpoint>
      	<NotificationEndpoint>${carbon.protocol}://${carbon.host}:${carbon.management.port}/authenticationendpoint/samlsso_notification.do</NotificationEndpoint>
      </SSOService>
      <PassiveSTS>
      	<RetryURL>${carbon.protocol}://${carbon.host}:${carbon.management.port}/authenticationendpoint/retry.do</RetryURL>
      </PassiveSTS>
  3. Configure the IDTokenBuilder in the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file as follows:

    <OpenIDConnect>
    	<IDTokenBuilder>com.wso2.finance.open.banking.idtoken.builder.AUIDTokeBuilder</IDTokenBuilder>
    </OpenIDConnect>
  4. According to CDS, an Access Token must expire between 2 minutes to 10 minutes after the Data Holder issues it. To configure the validity period of the Access Token in seconds, update the following configurations in the <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file.

    <OAuth>
    	<UserAccessTokenDefaultValidityPeriod>120</UserAccessTokenDefaultValidityPeriod>
    </OAuth>
  5. To enable Request-URI validation, open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file and add the following configurations under the <UK> tag:

    <!-- Validate AccountID with consented accountID in account retrieval -->
    <ValidateAccountIdOnRetrieval>true</ValidateAccountIdOnRetrieval>
  6. By default, Enforcement caching is enabled in the solution. To customize them, open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml file and add the following under the <Server> tag:

    <AU>
    	<Enforcement>
    		<Cache>
    			<CacheEnabled>true</CacheEnabled>
    			<ModifiedExpiryMinutes>15</ModifiedExpiryMinutes>
    			<AccessedExpiryMinutes>15</AccessedExpiryMinutes>
    		</Cache>
    	</Enforcement>
    </AU>
  7. Add the following Consent Enforcement handler configurations to the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file, below the

    #if($handler.className == "org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler") line.
    ##
    ## Start of AU Specification Handlers
    ##
    
    #if($apiObj.additionalProperties.get("ob-spec") == "au")
    <handler class="com.wso2.finance.open.banking.gateway.api.schema.validation.RequestSchemaValidationHandler"/>
    <handler class="com.wso2.finance.open.banking.au.consent.enforcement.AUConsentEnforcementHandler">
        <property name="validationBaseUrl" value="https://localhost:9446/consent/au100"/>
    </handler>
    #end
    
    ##
    ## End of AU Specific Handlers
    ##
    
  8. You are now ready to start the Key Manager and API Manager servers. To start the WSO2 OB KM server, go to the <WSO2_OB_KM_HOME>/bin directory and execute the following command:

    ./wso2server.sh -Dsetup
  9. Run the following command from the <WSO2_OB_APIM_HOME>/bin directory to start the WSO2 OB APIM server:

    ./wso2server.sh -Dsetup

    Execute the following command against the openbank_openbankingdb database:

    ALTER TABLE OB_CONSENT_METADATA DROP FOREIGN KEY FK_CONSENT_ID_UK_INITIATION;

Configuring consumer authentication

By default, WSO2 Open Banking comes with basic authentication configured. For CX guideline aligned experience, you can configure Identifier-first authentication paired with a secondary identity provider. In this section, we configure SMS OTP as the secondary identity provider.

Configuring Identifier-first authentication

The Identifier-first login enables identifying the individuals prior to authenticating them. It retrieves the identity of the user without using authentication information and uses that identity to control the authentication flow. For more information, see Identifier-first Flow Handler.

The Identifier-first is a handler that can be configured at any step in the authentication flow. However, it is not an authenticator by itself and needs to be configured along with another authenticator in order for the authentication process to be successful.

  1. To enable the Identifier-first authenticator in WSO2 OB KM, add the following configurations to the <WSO2_OB_KM>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> tag.

    <AuthenticatorConfig name="IdentifierExecutor" enabled="true">
    	<Parameter name="ValidateUsername">false</Parameter>
    </AuthenticatorConfig>
  2. Configure the Key Manager Extension to use Identifier-first as the primary authenticator.
    Open the <WSO2_OB_APIM>/repository/conf/finance/open-banking.xml file and add the following under the <SCA> configurations.

    <SCA>
    	<!--Configure the primary authenticator / 1st step authenticator-->
    	<PrimaryAuthenticator>
    		<Name>IdentifierExecutor</Name>
    		<DisplayName>identifier-first</DisplayName>
    	</PrimaryAuthenticator>
    </SCA>

Configuring SMS OTP as an identity provider for Identifier-first

To use SMS OTP with Identifier-first authentication, configure <WSO2_OB_KM>/repository/conf/identity/application-authentication.xml as follows:

<AuthenticatorConfig name="SMSOTP" enabled="true">
	<Parameter name="usecase">subjectUri</Parameter>
	<Parameter name="secondaryUserstore">primary</Parameter>
</AuthenticatorConfig>
 Click here to see how to configure SMS OTP Authenticator

Configuring SMS OTP Authenticator

Follow the steps below to configure SMS OTP Authenticator.

  1. Start the WSO2 Open Banking Key Manager (WSO2 OB KM) server. Sign in to the Management Console as an administrator.
  2. Navigate to the Main menu to access the Identity menu. Click Add under Identity Providers.
  3. Fill the Basic Information section and name this identity provider SMSAuthentication .
  4. Expand the Federated Authenticators > SMS OTP Configuration section.

  5. Select both the Enable and Default checkboxes. This is to enable and make the SMSAuthentication authenticator the default one.

    Based on your SMS provider, fill out the SMS OTP configurations.

    If Twilio is used as the SMS provider,
    • Go to https://www.twilio.com/try-twilio and create an account.

    • While registering the account, verify your mobile number and click on console home https://www.twilio.com/console to get free credits (Account SID and Auth Token).

    • Twilio uses a POST method with headers and the text message and phone number are sent as the payload. So the fields would be as follows.

      SMS URLhttps://api.twilio.com/2010-04-01/Accounts/{AccountSID}/SMS/Messages.json
      HTTP MethodPOST
      HTTP HeadersAuthorization: Basic base64{AccountSID:AuthToken}
      HTTP PayloadBody=$ctx.msg&To=$ctx.num&From=urlencode{TrialNumber}

      If you pass the text message and the phone number in any field, you have to replace them with $ctx.num and $ctx.msg respectively.
      E.g., Body=$ctx.msg&To=$ctx.num&From=+12345678

    Currently, the WSO2 OB KM supports only the following SMS providers.

  6. Click Register to add the Identity Provider. 
  7. Open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file.  Update the value of the <IdpName> parameter under the <SCA> element with the identity provider name.

    <SCA>
    	<IdpName>SMSAuthentication</IdpName>
    </SCA>

To verify the SMSAuthentication authenticator:

Follow the steps below to verify whether the SMSAuthentication authenticator is properly configured.

  1. Create an application in WSO2 OB APIM.

  2. Generate Access Tokens and Security Keys.

  3. Log in to the Management Console as the super admin.

  4. In the Main menu under the Identity section, click List under Service Providers. The list of service providers created appears.

  5. Select the service provider with the application name you created in step A. The service provider name is in the following format:

    <WSO2_OB_APIM_ USERNAME>_<APPLICATION_NAME>_<ENVIRONMENT>

  6. Click on the corresponding Edit link.

  7. Expand Local & Outbound Authentication Configuration. Select Advanced Configuration. You can configure additional authentication steps and additional authentication options.

  8. If you have successfully configured the above, you will see how the identifier-first and SMSAuthentication are configured under Authentication Step Configuration > Step 1 and Step 2.

Configuring users

  1. Sign in to the Identity and Access Management console (https://localhost:9446/carbon). Use the default super admin credentials as follows:

    Username: admin@wso2.com

    Password: wso2123

    The above mentioned username and password credentials are used for demo purposes only. It is recommended to change the credentials in a production environment.

  2. Create the necessary user accounts as follows:

      • On the Main tab, click Identity > Users and Roles > Add > Add New User.

      • Create the following user:

        UserRoles
        mark@gold.com

        Internal/creator, Internal/publisher

      • Click Next > and assign roles.

      • Click Finish.

    Now that you’ve added some users to the system, you can log in as one of them to see how a typical user might work with the WSO2 Open Banking solution.

Configuring APIs

You can configure APIs through the API Publisher by signing in as a user whose role includes Internal/publisher. Follow the steps given below:

  1. Sign in to the API Publisher ( https://localhost:9443/publisher) with the credentials for mark@gold.com.

  2. Click ADD NEW API > I have an existing API

  3. Select the Swagger definition in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/1.0.0/consumer-data-standards.yaml file and configure the properties according to the open-banking specification.


    Click Start Creating.
  4. Click Next: Implement to navigate to the next level.
  5. Expand Managed API, and use the table below to select the relevant Endpoint Type from the drop down list.
  6. Check Select a message mediation policy to be executed in the message flow under Message Mediation Policies.
  7. Click Upload In Flow and select the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/1.0.0/cds-dynamic-endpoint-insequence-1.0.0.xml file.

  8. Click Next: Manage to navigate to the next level.

  9. Expand Throttling Settings. Under Subscription Tiers, check the option as Unlimited : Allows unlimited requests unless you want to limit the requests.
  10. Expand API Properties and add the following values as Additional properties:

    Property Name

    ob-spec

    Property Value

    au
  11. Click the + button to save the above values as follows:

  12. To publish the API click Save & Publish.

Summarized information for configuring APIs

APIImplement tabManage tab
Endpoint typeEndpointEnable Message mediation

In flow


API property nameAPI property value
Consumer Data Standards API v1.0.0DynamicN/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/1.0.0/cds-dynamic-endpoint-insequence-1.0.0.xml ob-spec au

What's Next

Now that you have created the APIs that allow you to initiate payments and access account information, let's try out the flows in WSO2 Open Banking: