cdr

README

cdr

This is a library and set of tools to ease some of the issues we at Fiskil have had with configuring and testing interactions with other CDR entities.

Who is this library for?

This library is for accredited data recipients. This client uses the CDR specification which is restricted to data recipients registered with CDR. To become an ADR follow the instructions here; alternatively, Fiskil provides similar APIs without the requirement of becoming a data recipient. If Fiskil isn't for you there is a list of other data recipients here.

Getting started with the library

mTLS certs

Almost all of the endpoints specified by the spec require an mTLS certificate to verify clients. The functions in this library assume that mTLS certificates have already been attached to the provided http client, but also provide a way of buliding an http client with certificates:

cert := []byte(`-----BEGIN CERTIFICATE-----
MIIBhTCCASugAwIBAgIQIRi6zePL6mKjOipn+dNuaTAKBggqhkjOPQQDAjASMRAw
DgYDVQQKEwdBY21lIENvMB4XDTE3MTAyMDE5NDMwNloXDTE4MTAyMDE5NDMwNlow
EjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABD0d
7VNhbWvZLWPuj/RtHFjvtJBEwOkhbN/BnnE8rnZR8+sbwnc/KhCk3FhnpHZnQz7B
5aETbbIgmuvewdjvSBSjYzBhMA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggr
BgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdEQQiMCCCDmxvY2FsaG9zdDo1
NDUzgg4xMjcuMC4wLjE6NTQ1MzAKBggqhkjOPQQDAgNIADBFAiEA2zpJEPQyz6/l
Wf86aX6PepsntZv2GYlA5UpabfT2EZICICpJ5h/iI+i341gBmLiAFQOyTDT+/wQc
6MF9+Yw1Yy0t
-----END CERTIFICATE-----`)

privKey := []byte(`-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIIrYSSNQFaA2Hwf1duRSxKtLYX5CB04fSeQ6tF1aY/PuoAoGCCqGSM49
AwEHoUQDQgAEPR3tU2Fta9ktY+6P9G0cWO+0kETA6SFs38GecTyudlHz6xvCdz8q
EKTcWGekdmdDPsHloRNtsiCa697B2O9IFA==
-----END EC PRIVATE KEY-----`)

cli, err := cdr.New(cert, privKey)

The cdr.New returns an *http.Client with certificates attached. This http client can now be used as an argument to other functions in the libary.

Access Tokens

We have found that getting an access token for a specific data holder quickly can be challenging. To deal with this issue there is a tool attached to this library for managing refresh tokens and cdr arrangements.

Refresh tokens are stored locally with encryption at rest and associated access tokens can be easily accessed.

# To create a new token named "aus_bank" run:
go run ./cmd access set aus_bank

# You will be prompted for an encryption secret, refresh token, cdr arrangment id, and various information about the data holder.

# Once a token has been set you can access it:
go run ./cmd access fetch aus_bank

# You will again be prompted for the decryption secret.

Testing

An easy way to test interacting with the CDR is to setup a temporary test. The file my_test.go and directory my_tests are added to gitignore to encourage you to write your own stockpile of examples and references.

func TestTransactions(t *testing.T) {

	// Arrange
	is := is.New(t)
	ctx := context.Background()
	cli, err := cdr.NewFromEnv()
	is.NoErr(err)
	cdrCli, err := banking.NewClientWithResponses("https://resource.cdr-api.bankaust.com.au/cds-au/v1", banking.WithHTTPClient(cli))
	is.NoErr(err)
	tok := "insert-your-token-here"

	// Act
	res, err := cdrCli.ListAccountsWithResponse(ctx, &banking.ListAccountsParams{
		XV: "1",
	}, func(ctx context.Context, req *http.Request) error {
		req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", tok))
		return nil
	})

	// Assert
	is.NoErr(err)
	if res.StatusCode() > 299 {
		is.NoErr(fmt.Errorf("non 2xx response"))
	}

	bytes, err := json.Marshal(res.JSON200.Data)
	fmt.Println(string(bytes), err)

}

// Output: {"accounts":[{"accountId":"1","creationDate":"2022-05-19","displayName":"Everyday Access","isOwned":true,"maskedNumber":"xxxx7889","openStatus":"OPEN","productCategory":"TRANS_AND_SAVINGS_ACCOUNTS","productName":"Everyday Access"},{"accountId":"2","creationDate":"2022-06-04","displayName":"Bonus Saver","isOwned":true,"maskedNumber":"xxxx0241","nickname":"Bonus Saver","openStatus":"OPEN","productCategory":"TRANS_AND_SAVINGS_ACCOUNTS","productName":"Bonus Saver"}]}

Generating Go

Note that the cdr openapi specifications are obtained from here.

resource=banking
cd ${resource}
oapi-codegen -config config.yaml cdr_${resource}.swagger.json > ${resource}.gen.go
cd -

However, for energy additional patching is required to be compatible with AER energy API endpoints.

resource=energy
cd ${resource}
cat cdr_energy.swagger.json | json-patch -p cdr_energy.swagger.json.patch > patched_cdr_energy.swagger.json
oapi-codegen -config config.yaml patched_cdr_${resource}.swagger.json > ${resource}.gen.go
cd -

When new cdr resource type definitions are published they can be appended to the current package using the diff-gen subcommand of the cdr cli. diff-gen will generate go models from the provided openAPI/Swagger definition but omit those already declared in the package.

./cdr diff-gen ./energy ./energy/cdr_energy.swagger.1.2.4.json 

Documentation

Index

• Variables
• func New(cert []byte, privKey []byte) (*http.Client, error)
• func NewFromEnv() (*http.Client, error)
• type ErrNon2xxResponse
  • func (e *ErrNon2xxResponse) Error() string
• type RefreshTokenResponse
  • func RefreshToken(ctx context.Context, cli *http.Client, tokenEndpoint string, ...) (RefreshTokenResponse, error)

Examples

• New
• RefreshToken

Variables

var (
	// ErrInvalidKeys is when certificates cannot be created for an http client.
	ErrInvalidKeys = fmt.Errorf("cdr : invalid mTLS cert/key combination")
)

Functions

func New

func New(cert []byte, privKey []byte) (*http.Client, error)

New creates a new http client with certificates attached to it. Most of the funcitons in this cdr package require a *http.Client as an argument. This is the way to build that client.

Example

package main

import (
	"github.com/fiskil/cdr"
)

func main() {
	cert := []byte(`-----BEGIN CERTIFICATE-----
	MIIBhTCCASugAwIBAgIQIRi6zePL6mKjOipn+dNuaTAKBggqhkjOPQQDAjASMRAw
	DgYDVQQKEwdBY21lIENvMB4XDTE3MTAyMDE5NDMwNloXDTE4MTAyMDE5NDMwNlow
	EjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABD0d
	7VNhbWvZLWPuj/RtHFjvtJBEwOkhbN/BnnE8rnZR8+sbwnc/KhCk3FhnpHZnQz7B
	5aETbbIgmuvewdjvSBSjYzBhMA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggr
	BgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdEQQiMCCCDmxvY2FsaG9zdDo1
	NDUzgg4xMjcuMC4wLjE6NTQ1MzAKBggqhkjOPQQDAgNIADBFAiEA2zpJEPQyz6/l
	Wf86aX6PepsntZv2GYlA5UpabfT2EZICICpJ5h/iI+i341gBmLiAFQOyTDT+/wQc
	6MF9+Yw1Yy0t
	-----END CERTIFICATE-----`)
	privKey := []byte(`-----BEGIN EC PRIVATE KEY-----
	MHcCAQEEIIrYSSNQFaA2Hwf1duRSxKtLYX5CB04fSeQ6tF1aY/PuoAoGCCqGSM49
	AwEHoUQDQgAEPR3tU2Fta9ktY+6P9G0cWO+0kETA6SFs38GecTyudlHz6xvCdz8q
	EKTcWGekdmdDPsHloRNtsiCa697B2O9IFA==
	-----END EC PRIVATE KEY-----`)

	client, _ := cdr.New(cert, privKey)
	_ = client
}

func NewFromEnv

func NewFromEnv() (*http.Client, error)

NewFromEnv creates a new http client taking its certificates from environment variables. This ishelpful if the certificates are const. The environment variables are:

CDR_MTLS_CERTIFICATE
CDR_MTLS_PRIVATE_KEY

Types

type ErrNon2xxResponse

type ErrNon2xxResponse struct {
	StatusCode int
	Response   io.ReadCloser
	URL        *url.URL
}

ErrNon2xxResponse is returned when a non 2xx status code is received.

func (*ErrNon2xxResponse) Error

func (e *ErrNon2xxResponse) Error() string

type RefreshTokenResponse

type RefreshTokenResponse struct {
	AccessToken    string `json:"access_token"`
	IDToken        string `json:"id_token"`
	ExpiresIn      int    `json:"expires_in"`
	Scope          string `json:"scope"`
	RefreshToken   string `json:"refresh_token"`
	CDRArrangement string `json:"cdr_arrangement_id"`
}

RefreshTokenResponse is a response you get from exchanging a refresh token.

func RefreshToken

func RefreshToken(ctx context.Context, cli *http.Client, tokenEndpoint string, refreshToken string, clientID string, clientAssertion string) (RefreshTokenResponse, error)

RefreshToken gets a new access token from a refresh token.

Example

package main

import (
	"context"

	"github.com/fiskil/cdr"
	"github.com/fiskil/cdr/assertions"
)

func main() {

	ctx := context.Background()
	// Get a new http client with mTLS certs attached.
	cli, _ := cdr.NewFromEnv()

	// Get the token endpoint from the data holders well known config
	tokenEndpoint := "https://identity-mtls.cdr-api.bankaust.com.au/token"
	refreshToken := "my-refresh-token"
	clientID := "data-holders-client-id-for-me"
	signer, _ := assertions.NewSignerFromEnv()
	assertion, _ := signer.ClientAssertions(clientID, tokenEndpoint)

	tokenResponse, _ := cdr.RefreshToken(ctx, cli, tokenEndpoint, refreshToken, clientID, assertion)

	_ = tokenResponse
}