Consumer Data Right - Authorisation Server

This project contains source code, documentation and deployment artefacts for a FAPI 1.0 compliant Authorisation Server, built to conform to the Consumer Data Standards and CDR.

The project is used in the Participant Tooling Authorisation Server, providing the Infosec functionality. The repository is also provided to the CDR community for use within participant solutions.

Authorisation Server - Alignment

The Authorisation Server:

aligns to v1.22.0 of the Consumer Data Standards in particular FAPI 1.0 Migration Phase 4 with backwards compatbility to Migration Phase 2 and 3;
has passed v4.3.1 of the Conformance Test Suite for Data Holders; and
is certified with the FAPI 1.0 Advanced Profile .

Note: Consumer Data Standards FAPI 1.0 Migration Phase 1 is no longer supported.

Financial Grade API (FAPI) 1.0 Advanced Profile Certification

The Authorisation Server is certified by OpenID using OpenID FAPI conformance testing. Testing was completed and passed using:

FAPI 1.0 Advanced Test Plan; using
CDR Australia profile; and
the latest AU-CDR Adv. OP w/ Private Key, PAR, JARM iteration

Full test results for the Authorisation Server can be seen on the OpenID website. Certification for the Authorisation Server can be seen under the Australia CDR profile section on the OpenID website

Getting Started

The Authorisation Server can be used for providing authentication to the Banking and Energy Mock Data Holders. You can swap out any of the Mock Data Holders and Mock Data Recipient solutions with a solution of your own.

Please note that the Authorisation Server can also run as an embedded component of the Banking and Energy Mock Data Holders solution. This is not covered in this guide.

There are a number of ways that the artefacts within this project can be used:

Build and deploy the source code
Use the pre-built image

Build and deploy the source code

To get started, clone the source code.

git clone https://github.com/ConsumerDataRight/authorisation-server.git

To get help on launching and debugging the solution, see the help guide.

If you would like to contribute features or fixes back to the Authorisation Server repository, consult the contributing guidelines.

Use the pre-built image

A version of the Authorisation Server is built into a single Docker image that is made available via docker hub.

Pull the latest image

docker pull consumerdataright/authorisation-server

To get help on launching the solution in a container, see the help guide.

Try it out

Once the Authorisation Server container is running, you can use the provided Authorisation Server Postman API collection to try it out.

Certificate Management

Consult the Certificate Management documentation for more information about how certificates are used for the Authorisation Server.

Loading your own data

The Authorisation Server contains seed data files in a json format. The Authorisation Server will read directly from these files when:

Loading Customer and Account data for use in the Consent and Authorisation flow User Interface.
Adding user name claims during a token request.

The following steps required to load your own data into the container instance or code running in Visual Studio:

Within the /Source/CdrAuthServer/Data folder of the container or source code directory, make a copy of the customer-seed-data.json file for banking customers or the customer-seed-data-energy.json file for energy customers, renaming to a name of your choice, e.g. my-new-customer-seed-data.json.
Update your seed data file with your desired metadata.
Change the /Source/CdrAuthServer/appsettings.json file to load the new data file for use in the APIs:

"SeedData": {
    "FilePath": "Data/my-new-customer-seed-data.json",
},

Copy the updated seed data file to 'Source/CdrAuthServer.UI/public'
Change the /Source/CdrAuthServer.UI/.env.* file to load the new data file for use in the User Interface:

REACT_APP_DATA_FILE_NAME=my-new-customer-seed-data.json

Restart the container or restart the application in Visual Studio.

To get help on launching the solution in a container, see the help guide.

Authorisation Server - Architecture

The following diagram outlines the high level architecture of the Authorisation Server

The following diagram illustrates the docker container for the Authorisation Server

The following diagram illustrates the high level features for the Authorisation Server

Authorisation Server - Components

The Authorisation Server contains the following components:

Authorisation Server
- Hosted at https://localhost:8001
- CDR Authorisation Server implementation utilising (this) cdr-auth-server
- Accessed directly (TLS only) as well as the mTLS Gateway, depending on the target endpoint.
mTLS Gateway
- Hosted at https://localhost:8002
- Provides the base URL endpoint for mTLS communications, including Infosec, Resource and Admin APIs.
- Performs certificate validation.
Resource API
- Hosted at https://localhost:8001
- Currently includes the Get Customer endpoint.
- Accessed via the mTLS Gateway.
UI
- Hosted at https://localhost:3000
Azure Function
- An Azure Function that can automate the continuous Get Data Recipients discovery process.
- To get help on the Azure Functions, see the help guide.
Repository
- A SQL database containing clients, grants and log entries for identity provider solutions.

Technology Stack

The following technologies have been used to build the Authorisation Server:

The source code has been written in C# using the .Net 6 framework.
The mTLS Gateway has been implemented using Ocelot.
The Repository utilises a SQL instance.
xUnit is the framework used for writing and running tests.
Microsoft Playwright is the framework used for Web Testing.

Features

The Authorisation Server contains the following features:

OpenID Discovery Document
JWKS endpoint
Dynamic Client Registration (DCR)
Pushed Authorization Requests
Authorization endpoint
- Support for request_uri parameter
- Hybrid and Authorization Code flow
- Conforms to Consumer Data Right CX Guidelines.
Token endpoint
- Authorization Code
- Client Credentials
- Refresh Token
UserInfo
Introspection
Token Revocation
CDR Arrangement Revocation

Endpoints

The Authorisation Server has the following endpoints:

Endpoint	Methods	Transport	Authorisation	Description
/.well-known/openid-configuration	GET	TLS	None	Open ID Discovery Document
/jwks	GET	TLS	None	JWKS endpoint
/auth	GET	TLS	None	Authorization endpoint
/registration	POST	mTLS	None	Create registration endpoint (DCR)
/registration	GET, PUT, DELETE	mTLS	Bearer	Create registration endpoint (DCR)
/par	POST	mTLS	Client Assertion	Pushed Authorization Request endpoint (PAR)
/token	POST	mTLS	Client Assertion	Token endpoint
/userinfo	POST	mTLS	Bearer	Userinfo endpoint
/introspect	POST	mTLS	Client Assertion	Introspection endpoint
/token/revocation	POST	mTLS	Client Assertion	Token revocation endpoint
/arrangement/revocation	POST	mTLS	Client Assertion	Arrangement revocation endpoint

Customisations

Standard, "out-of-the-box" Authorisation Server functionality needs to be customised in order to meet the Consumer Data Standards.

The information below lists the customisation required for each endpoint:

/.well-known/openid-configuration

No customisation required.

/jwks

No customisation required.

/auth

The authorisation flow defined for CDS is customised and includes OTP and account selection steps.

/registration

The DCR process relies on an SSA issued by the Register.
The SSA signature needs to be verified against the Register SSA JWKS.
The contents of the registration request needs to be validated against the contents of the SSA.
The contents of the registration request needs to be validated against the CDS.

/par

Validation of the request object must conform to CDS.
Need to extract and interpret the custom claims (cdr_arrangement_id, sharing_duration) from the request object.

/token

Must create a CDR arrangement, based on the sharing_duration claim.
Must return the cdr_arrangement_id claim in the payload.

/userinfo

The sub claim needs to be obfuscated using the PPID rules of the CDS.

/introspect

This endpoint can only be used for refresh tokens, not access tokens.
The payload needs to be include the cdr_arrangement_id claim.

/token/revocation

No customisation required.

/arrangement/revocation

This is a custom endpoint for CDS.

Testing

A collection of API requests has been made available in Postman in order to test the Authorisation Server (when integrated with the Banking or Energy Mock Data Holders solutions) and view the expected interactions. See the Mock Data Holder Postman and Mock Data Holder Energy Postman documentation for more information.

Automated tests have been created as part of this solution. See the Test Automation Execution Guide documentation for more information.

Contribute

We encourage contributions from the community. See our contributing guidelines.

Code of Conduct

This project has adopted the Contributor Covenant. For more information see the code of conduct.

Security Policy

See our security policy for information on security controls, reporting a vulnerability and supported versions.

License

MIT License

Notes

The Authorisation Server is provided as a development tool only. It conforms to the Consumer Data Standards.

ConsumerDataRight / authorisation-server