TWG / 11/05/2017 / UNCLASSIFIED
format / Audience / Date / Classification
Created By STP
TA210 - STP Authentication and Authorisation
TA210 - Logical Solution Architecture
Version 0.1
UNCLASSIFIED / Document Owner:
STP
INSERT CLASSIFICATION / PAGE1 OF 3
INSERT CLASSIFICATION / TA210 - LOGICAL SOLUTION ARCHITECTURE TEMPLATE
TA210 - Logical Solution Architecture
ENDORSEMENT/VERSION CONTROL
CURRENT VERSION NUMBER / 0.2 / DATE / 11/05/2017APPROVAL
[approver’s name] / [approver’s position] / [approved/endorsed] / [date]
[approver’s name] / [approver’s position] / [approved/endorsed] / [date]
[approver’s name] / [approver’s position] / [approved/endorsed] / [date]
VERSION CONTROL
Version / Revision date / Author / Summary of Change0.1 / 11/05/2017 / Sam Boulad / Initial Draft
0.2 / 22/05/2017 / Sam Boulad / Updates based on comments
Document versioning is described in IT Standard 03
DO NOT deletethe section break above this page.
INSERT CLASSIFICATION / Version 0.2 / PAGE1 OF 17INSERT CLASSIFICATION / TA210 - LOGICAL SOLUTION ARCHITECTURE TEMPLATE
TA210 - Logical Solution Architecture
Table of contents
1Introduction
1.1References
1.2Definitions
1.3Stakeholders
1.4Discussion History
1.5Assumptions
2Functionality Overview & System Requirements
2.1Functional Overview
2.1.1Main Objectives
2.1.2Context and Features
2.2System Requirements
2.2.1Normal Business Process Requirements
2.2.2Business Use Case Diagram
2.2.3Non-Functional Requirements
3Logical Solution Architecture Specification
3.1Key Design Drivers
3.2Solution Execution Architecture
3.2.1Overview
3.2.2Determining handlers
3.2.3Authentication and Authorisation
When you have completed your document, right mouse click on the table of contents above and select Update Field to create your table of contents.
DO NOT deletethe section break above this page.
INSERT CLASSIFICATION / Version 0.2 / PAGE1 OF 17INSERT CLASSIFICATION / TA210 - LOGICAL SOLUTION ARCHITECTURE TEMPLATE
TA210 - Logical Solution Architecture
1Introduction
STP Payroll processing is not straight forward. Messages can go through multiple hops before reaching ATO. These hops include:
- Employer; could send payroll information in any format including paper to an intermediary or vendor that can transform and prepare the data.
- Intermediary; could transform and prepare the data using BMS software, this could also be cloud.
- Cloud Software Provider; prepares and transforms payroll data to be either sent directly or via an SSP.
- Sending Service Provider
This raises a number of issues, these being:
- Message privacy
- Ensuring messages have not been circumvented by vendors or entities that are either not authorised or do not have an agreement in place.
This document defines the high level solution architecture to address these issues within STP. The solution outlined will be “Multiple SSP Capture” (option 2) from the Transmission Flow Scenarios. This option outlined the following:
- Check an SSID is linked to a cloud provider
- Check a link exists between a reporting party and intermediary
- White list sending providers
Figure 1 Option 2
Document Scope
In Scope / Rationale for InclusionOperational Framework / This states where ATO responsibility lays in terms of security; this will have a bearing on the initial solution.
Authentication / There is already an authentication mechanism in place; however SSPs will be handled differently.
Authorisation / Ensuring that only vendors with agreements and/or authorisations within AM have handled the message enroute to ATO. This relates to the multi-hops that messages will go through.
The following is not in scope for this document
Out of Scope / Rationale for ExclusionEncryption / Possible options will be outlined; however message encryption won’t be part of the TT18 solution.
1.1References
Name / Document Owner / Document Location/Description1ATO Glossary / ATO Corporate / The ATO Glossary contains definitions of commonly used terms and acronyms in use at the ATO
2PL201 – STP Requirements Matrix Ver 1.0 / ATO / Link
3TA210 Overarching Solution Architecture V1.11 / ATO / Link
4Security Architecture eCommerce Platform V0.10 / IBM / Link
5AP450 AusKey in the cloud V1.0 / ATO / Link
6SBR ebMS3 Web Services Implementation Guide V1.3 / IBM / Link
7PL210 Single Touch Payroll Addendum / ATO / Link
8STP Payroll Processing Solution Summary V4.0 / ATO / Link
9BR200 eCommerce Non Functional Requirements V1.0 / ATO / Link
10STP AA Transmission Flow Options Paper V0.3
11Software Developer Networks for SBR V0.4
12Operational Framework / ATO
1.2Definitions
The majority of ATO terms and their definitions are contained in the ATO business glossary (see References above). ATODM terms and definitions are contained in the ATODM Guidebook. This section only contains terms not already contained in one of these sources or requiring further clarification. For each definition provided indicate whether it must be added to the ATO Business Glossary.
Term/Acronym / Expanded / Definition
SSP / Sending Service Provider / The SSP sends data in ebMS3 format directly to ATO. I.e. invokes the SBR service on behalf of other entities.
RI / Registered Intermediary / This is the registered agent. I.e. a tax or BAS agent.
CSP / Cloud Service Provider / This BMS software hosted in the cloud.
TT18 / Tax Time 2018
1.3Stakeholders
Stakeholders in this document are:
Team/Person / InterestSTP Designers / STP Project design team
ATO architects / Governance of high level design and understanding as it relates to other systems and business processes.
ATO Online Project Team / For Project Implementation work.
Technical Working Group / Members of this group are consumers of the SBR service.
1.4Discussion History
Issues/Question/Meeting / Discussion Matter / SMEs Contacted / Date1.5Assumptions
The table below lists the assumptions upon which this document is based.
Ref # / Assumption1 / This paper will discuss options for encryption, however it is not expected to be part of the solution outlined for July 2018
2 / The solution for July 2018 will address authorisation, however enforcement of all message hops may not be part of the July 2018 solution. I.e. digital signature will be outlined as a possible future option.
2
Functionality Overview & System Requirements
2.1Functional Overview
The design is to enable processing payroll messages through multiple hops. A message can be handled by a number of different entities before reaching ATO, these can be:
- Reporting Parties
- Businesses
- Intermediaries
- Cloud Service Providers
- Send Service Providers
Payroll messages can be in any format i.e. paper, soft copy (Spreadsheet), digital (any message format such as SOAP, ebMS3, REST), however the final leg to ATO must be ebMS3 or XML over HTTPS.
2.1.1Main Objectives
The main objective of the design is to describe what is expected from message handlers in terms of message traceability i.e. which entities handled the message. Authorisation, integrity, non-repudiation and privacy will be dealt with as options.
2.1.2Context and Features
Figure 2 Context
System / DescriptionBusiness Management Software (BMS) /
- Can format and translate payroll data into ebMS3 format
- Send and receive SBR requests to/from ATO via the SDK
Secure Token Service (STS) /
- Generates a security token based on an entities AUSkey
- Provides STS +D functionality for delegation purposes
Core Services /
- Authenticates messages via ISF
- Authorises messages via AM
- Processes and routes messages on the relevant middle-tier/back-end services
SDK / An embeddable client that enables:
- Requesting tokens
- Message Service Handler (MSH) to allow sending of messages using ebMS3
Access Manager /
- Retrieves and injects a UID related to a SAML token into the header
- Checks link between and Intermediary and Payer
- Checks Cross Entity Authorisations (XEA) for act-on-behalf situations
- Maintains and checks link between a client’s Software Subscription ID (SSID) and a cloud hosted BMS provider
Internet Security Framework /
- Has a trust relationship with the VANguard STS
- Verifies tokens
- Authenticates requests
Figure 3 Overview
2.2System Requirements
2.2.1Normal Business Process Requirements
These are the relevant requirements outlined in the PL201. These requirements only cover option 1 of the STP AA Transmission Flow Options.
Identifier / Description32 / The system shall authenticate an employer lodging an STP payroll event.
33 / The system shall recognise the relationship between an employer and an intermediary who has been authorised to lodge STP payroll events on the employer’s behalf.
266 / In authenticating the payroll event, access manager will use the ABN of the Intermediary submitting the payroll event file.
267 / A relationship check will be done on an intermediary and the employers they are reporting payroll data for to ensure they have the required authorisation to do so.
289 / The system shall authenticate an employer lodging an STP Update event.
290 / The system shall recognise the relationship between an employer and an intermediary who has been authorised to lodge STP Update events on the employer’s behalf.
? / SoftwareSubscriptionId will be added to wsse:security within the soap header. This is used to link businesses to a cloud provider and allow message integrity.
Figure 4 Requirements
2.2.2Business Use Case Diagram
The following diagram(s) show the business use cases that will be implemented by the solution.
Figure 5 Use Cases
2.2.3Non-Functional Requirements
Please refer to the BR200 for non-functional requirements.
3
Logical Solution Architecture Specification
This section defines the logical architecture for the solution, covering the execution and development architectures of the end-to-end solution.
Figure 6 Logical
3.1Key Design Drivers
For the initial design i.e. July 2018 is to reuse functionality already available within VANguard, SBR, AM and the SDK to process messages. The key drivers are:
- Register entities such Sending Service Providers with AM as allowing to use the Payroll SBR services where there is no link to a reporting party i.e. intermediary to payer link
- Verify where an entity is using a cloud provider via the SSID
- Verify that entity is authorised to act on behalf of another
- Allow the handling of messages to be routed to any combination of handlers
- Verify that a link exists between an intermediary and a payer
- Specify what information is to be added to the message by handlers on its way to ATO
3.2Solution Execution Architecture
3.2.1Overview
The scenarios that could occur are too numerous to detail here. Some of the scenarios identified are listed in the table below, however they are by no means all possible scenarios. There might be scenarios where there are multiple Intermediaries or Cloud Service Providers.
Reporting Party (RP) / Intermediary (INT) / Cloud Service Provider (CSP) / Sending Service Provider (SSP)*
* / *
* / *
* / * / *
* / *
* / * / *
* / * / *
* / * / * / *
Figure 7 Scenarios
3.2.2Determining handlers
In order to determine who handled and processed the message on its route to ATO, each entity must provide additional information in the HTTP header. This is optional for the reporting party or the entity that uses its AUSkey to connect directly to ATO. This solution was chosen as it is message format independent. We do not want this functionality to be tied down to SOAP or ebMS3 messages exclusively.
The information required in the HTTP header is as follows:
Field Name / DescriptionTs / The timestamp the message was handled. This is used for sequencing the order of hops.
Id / The external ID of the entity handling the message at the current hop. I.e. this will most likely be an ABN.
Type / The External ID type of the entity handling the message at the current hop. The types could be:
- TAN- Tax agent number
- RAN- Registered agent number
- ABN- Australian business number
- WPN?- Withholder payer number
Role / The role type of the entity handling the message at the current hop. Roles could be:
- RP- reporting party
- INT- intermediary
- BUS- business
- CSP- cloud service provider
- SSP- sending service provider
Ssid / For cloud providers, this would be the subscriber ID of the entity logged in.
Action / Since authorisation is not part of the initial solution, it is not expected this field will be used; however we will still record it for future use. This is the action the entity is carrying out on the message at the current hop. Values could be:
- SENDER
- TRANSLATOR
- ENCRYPTOR
- CONSTRUCTOR
- TRANSMITTER
Format / This is the format of the payroll data. This could be:
- PAPER- the payroll data was sent via paper
- ELECTRONIC- the payroll data was sent electronically such as email
- XML- the payroll data was sent via an XML service
- ebMS3- the payroll data was sent via an ebMS3 service
Figure 8 Hop fields
So if we run through our previous scenario, we would have:
Message / DescriptionHandlerHop : ts=Fri, 19 May 2018 08:49:37 GMT; id=11111111111; type=ABN; role=RP; format=PAPER / The reporting party sent his payroll data onto an intermediary via paper.
HandlerHop : ts=Fri, 19 May 2018 08:49:39 GMT; id=22222222222; type=ABN; role=INT; action=TRANSLATOR; format=XML / The intermediary sent the payroll data onto the cloud provider via an XML service
HandlerHop : ts=Fri, 19 May 2018 08:49:41 GMT; id=33333333333; type=ABN; role=CSP; ssid=1234567891; action=CONSTRUCTOR; format=XML / The cloud provider sends on the data to a sending provider via an XML message.
HandlerHop : ts=Fri, 19 May 2018 08:49:44 GMT; id=44444444444; type=ABN; role=SSP; action=TRANSMITTER; format=ebMS3 / The sending provider sends the payroll data onto the ATO via an ebMS3 service.
Figure 9 Hop Example
3.2.3Authentication and Authorisation
In this section will go through one scenario and detail what would happen if the scenario varies i.e. the handler connecting to ATO is different. Any prechecks done by SBR to check the authenticated user against the header should be disabled for cloud and sending providers.
Figure 10 Execution
The actions that occur are outlined below in the table. Regardless of which entity connects to ATO, they must:
- Request a token from the VANguard STS, the SBR SDK handles this and is standard functionality already employed. The token is placed within wsse:security in the soap header
- Send an ebMS3 message to ATO
- ISF will verify the token and embed a UID in the message to be used for authorisation checks by AM
Step / Actions
1 / The reporting party has two options, these are:
- Send payroll data directly to ATO as ebMS3 requests or;
- Send payroll data onto one of the following (could be any protocol and format?):
- Intermediary
- Sending Service Provider
- Send payroll data via a cloud hosted BMS, I.e. Cloud Service provider. The reporting party must have previously logged into the AM portal and associated their SSID with the cloud providers ABN
2 / An intermediary again has two options, these are:
- Send payroll data directly to ATO as ebMS3 requests or;
- Send payroll data via a Sending Service Provider, this could be in any format.
- Send payroll data via a cloud hosted BMS; I.e. Cloud Service Provider. The reporting party must have previously logged into the AM portal and associated their SSID with the cloud providers ABN
3 / The cloud provider can either send payroll data directly to the ATO or use a sending provider. Regardless of which route, the cloud provider must set the SoftwareSubscriptionId of the entity whose payroll data is being sent.
4 / Sending Service Provider sends on behalf of other entities
- The sending party needs to be white listed i.e. allowed to use the payroll services
- The sending provider requests a token from the VANguard STS
- Sending provider sends the ebMS3 message to ATO
- ISF verifies the token then embeds a UID
- AM allows the sending party is he is white listed
5 / ISF has a trust relationship with the VANguard STS. It verifies the token presented by the service consumer and either rejects or allows the request. If the request is allowed, a UID is embedded into the request to be used by SBR and AM.
6 / SBR core services will process the payroll data provided. As part of this processing, AM will be called for each bulk. The AM authorisation calls are made to the AM Authorisation Checker Service. Calls depending on which entity presented their token would be made as follows:
Reporting Party
Core calls authorisation checker to verify that the reporting party in each bulk is the same as the UID provided by ISF. i.e.
SelectedClientId = Payer ABN or WPN
Intermediary
Core calls authorisation checker to verify that the intermediary from each bulk is the same as the intermediary UID provided by ISF and that there is a link between the intermediary and the reporting party.
SelectedClientId = Payer ABN or WPN
SelectedIntermediaryId = Intermediary ABN or RAN
Cloud Service Provider
Since SoftwareSubscriptionId is populated in the soap header, core calls authorisation checker to verify that:
- SoftwareSubscriptionId is associated with UID provided by ISF.
- Where the SoftwareSubscriptionId is not an intermediary, AM will check that the external Id of the SoftwareSubscriptionId is the same as the reporting party in the bulk
- Where the SoftwareSubscriptionId is an intermediary, AM will also check that there is a link between the intermediary and the reporting party in each bulk
SelectedIntermediaryId= Intermediary ABN or RAN where SSID is an intermediary
SelectedSubscriptionId = SoftwareSubscriptionId
Sending Service Provider
In the case when a sending provider connects to ATO, ISF will verify the token and allow the request. The authorisation is done purely from the information provided in the bulk message and the soap header.
Where there is no SoftwareSubscriptionId in the soap header then authorisation is achieved as per sections Reporting party and Intermediary above; however, where a SoftwareSubscriptionId has been specified, there is no link between the SSP and the SSID, so how do we determine the ABN of the CSP? This can be achieved by retrieving the last HandlerHop from the HTTP header with a role of CSP.
SelectedClientId = Payer ABN or WPN where SSID is not an intermediary
SelectedIntermediaryId= Intermediary ABN or RAN where SSID is an intermediary
SelectedSubscriptionId = ssid from last HandlerHop with role of CSP
7 / AM will either accept or reject authorisation request based on the following logic.
Figure 11 Execution Steps
INSERT CLASSIFICATION / Version 0.2 / PAGE1 OF 17