hmrc / agent-access-control   0.38.0-2-g0a87ee9

Apache License 2.0 GitHub
Scala versions: 2.11

agent-access-control

Provides delegated auth rules for auth-client library to allow Agent users access to their clients' data. Teams wishing to support auth for Agent users for any of the following tax services should integrate via auth-client, not directly with agent-access-control.

  • PAYE (IR-PAYE)
  • Self-Assessment (IR-SA)
  • MTD Self-Assessment (MTDITID)
  • MTD Value Added Tax (VAT)
  • Income Record Viewer (IRV)
  • Trusts (TERS)
  • Non-Taxable-Trusts (TERSNT)
  • Capital Gains for Property Disposals (CGT-PD)
  • Plastic Packaging Tax (PPT)
  • Country by country reporting (CBC)
  • Pillar2 (PILLAR2)

Testing

In a terminal, Run the following profile:

sm --start AGENT_AUTHORISATION -r

  1. Log In as Agent

  2. Create Relationship Via Curl using Agent Arn, Client Service and Identifier.

curl -v -X PUT -H 'Authorization: Bearer Token' http://localhost:9434/agent-client-relationships/agent/AARN0002908/service/HMRC-MTD-VAT/client/VRN/267729808
  1. Curl Agent Access Control To Test Relationship Exists. E.g:
curl -v -H'Authorization: Bearer Token' http://localhost:9431/agent-access-control/mtd-vat-auth/agent/9AK6XC1JX8NE/client/267729808

Alternatively create the relationship via UI (Please speak to team about this).

Automated testing

This service is tested by the following automated test repositories:

Endpoints

GET /agent-access-control/epaye-auth/agent/:agentCode/client/:empRef

Example usage i.e. via auth-client

authorised(
   Enrolment("IR-PAYE")
     .withIdentifier("TaxOfficeNumber", "123")
     .withIdentifier("TaxOfficeReference", "123")
     .withDelegatedAuthRule("epaye-auth")) { /* your protected logic */ }
GET /agent-access-control/sa-auth/agent/:agentCode/client/:saUtr

Example usage

authorised(
   Enrolment("IR-SA")
     .withIdentifier("UTR", "123")
     .withDelegatedAuthRule("sa-auth")) { /* your protected logic */ }
GET /agent-access-control/mtd-it-auth/agent/:agentCode/client/:mtdItId

Example usage

authorised(
   Enrolment("HMRC-MTD-IT")
     .withIdentifier("MTDITID", "123")
     .withDelegatedAuthRule("mtd-it-auth")) { /* your protected logic */ }
GET /agent-access-control/mtd-it-auth-supp/agent/:agentCode/client/:mtdItId

Example usage

authorised(
   Enrolment("HMRC-MTD-IT-SUPP")
     .withIdentifier("MTDITID", "123")
     .withDelegatedAuthRule("mtd-it-auth-supp")) { /* your protected logic */ }
GET /agent-access-control/mtd-vat-auth/agent/:agentCode/client/:vrn

Example usage

authorised(
   Enrolment("HMRC-MTD-VAT")
     .withIdentifier("VRN", "123")
     .withDelegatedAuthRule("mtd-vat-auth")) { /* your protected logic */ }
GET /agent-access-control/afi-auth/agent/:agentCode/client/:nino

Example usage

authorised(
   Enrolment("HMRC-NI")
     .withIdentifier("NINO", "123")
     .withDelegatedAuthRule("afi-auth")) { /* your protected logic */ }
GET /agent-access-control/trust-auth/agent/:agentCode/client/:utr

Example usage

authorised(
   Enrolment("HMRC-TERS-ORG")
     .withIdentifier("SAUTR", "123")
     .withDelegatedAuthRule("trust-auth")) { /* your protected logic */ }
GET /agent-access-control/trust-auth/agent/:agentCode/client/:urn

Example usage

authorised(
   Enrolment("HMRC-TERSNT-ORG")
     .withIdentifier("URN", "123")
     .withDelegatedAuthRule("trust-auth")) { /* your protected logic */ }
GET /agent-access-control/cgt-auth/agent/:agentCode/client/:cgtRef

Example usage

authorised(
   Enrolment("HMRC-CGT-PD")
     .withIdentifier("CGTPDRef", "123")
     .withDelegatedAuthRule("cgt-auth")) { /* your protected logic */ }
GET /agent-access-control/ppt-auth/agent/:agentCode/client/:pptRef

Example usage

authorised(
   Enrolment("HMRC-PPT-ORG")
     .withIdentifier("EtmpRegistrationNumber", "123")
     .withDelegatedAuthRule("ppt-auth")) { /* your protected logic */  }

Note: POSTs function exactly the same.

GET /agent-access-control/cbc-auth/agent/:agentCode/client/:cbcId
authorised(
  Enrolment("HMRC-CBC-ORG" /* or HMRC-CBC-NONUK-ORG */)
    .withIdentifier("cbcId", "XYCBC1234567890")
    .withDelegatedAuthRule("cbc-auth") { /* your protected logic */  }
)
GET /agent-access-control/pillar2-auth/agent/:agentCode/client/:Pillar2Id
authorised(
  Enrolment("HMRC-PILLAR2")
    .withIdentifier("PLRID", "XYPILLAR21234567890")
    .withDelegatedAuthRule("pillar2-auth") { /* your protected logic */  }
)

Agent access groups

If an agent has opted to turn on access groups, the agent user will be granted access to a client if

  • the client has a relationship with the agent AND
  • the client and the agent user are associated by either a Custom Access Group or a Tax Service Group OR the client does not belong to any access group

If the agent has not turned on access groups, the agent user will be granted access provided the client has a relationship with the agent.

Response

Each API Will Respond with the following:

code scenario
200 {client identifier} is assigned to logged in agent for {Supported Service} (Enrolment Store Proxy check) AND the logged in user's agency (agentCode) has a valid authorisation to act on behalf of {client identifier} for dealing with {Supported Service} (HODs check).
401 The conditions are not met. Note, in these cases auth-client will respond with InsufficientEnrolments(s"$reason, $enrolments.key") where reason is one of "NO_RELATIONSHIP" or "NO_ASSIGNMENT"
502 In case of any error responses in downstream services.
504 In case of a timeout while querying downstream services.

Statistics

5 Dependencies

No Dependent