Skip to main content
Guide
DG-3059
Version
1.0
Status
Active
Created
Updated

Quick intro

Before a client can interact with the PCA™, it needs to generate a JSON Web Token (JWT) - RFC7519 that will be used to authenticate the client to the PCA™ Identity and Access Manager.

For a practical reference on JWT, as well as debugging tools and client libraries, see https://jwt.io.

The authentication JWT shall include the claims below, and shall be signed with the client’s private key.

JWT details

In its compact form, JSON Web Tokens consist of the following three parts separated by dots (.):

  • header
  • payload
  • signature

Therefore, a JWT typically looks like the following.

xxxxx.yyyyy.zzzzz

Authentication JWT Header Values

ParameterCardinalityDetails
algMandatoryThe JWA algorithm used for signing the authentication JWT - must be RS256
kidMandatoryThe identifier of the key-pair used to sign this JWT. This identifier shall be unique within the client's JWK Set.
typMandatoryFixed value : JWT

An example for the JWT header values:

{
  "alg": "RS256",
  "kid": "eee9f17a3b598fd86417a980b591fbe6",
  "typ": "JWT"
}

Authentication JWT Claims

ParameterCardinalityDetails
issMandatoryIssuer of the JWT -- the client_id, as determined during registration with the PCA™ Identity and Access Manager (note that this is the same as the value for the sub claim)
subMandatoryThe service's client_id, as determined during registration with the PCA™ Identity and Access Manager (note that this is the same as the value for the iss claim)
audMandatoryThe PCA™ Identity and Access Manager's "token URL" (the same URL to which this authentication JWT will be posted to)
expMandatoryExpiration time integer for this authentication JWT, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). This time shall be no more than five minutes in the future.
jtiMandatoryA nonce string value that uniquely identifies this authentication JWT.

An example for the JWT claims:

{
  "iss": "8b0914e0-09b4-47d7-9fc9-eb3ddaf2f7aa",
  "sub": "8b0914e0-09b4-47d7-9fc9-eb3ddaf2f7aa",
  "aud": "https://bne-drp-trp.digitalhealth.gov.au/PcaAuthApi/v2/auth/token",
  "exp": "1352660008",
  "jti": "rand0m-n0n-reusable-jwt-1d-123"
}

Create JWT

You can then digitally sign the claims, as specified in JSON Web Signature - RFC7515.

Many wrapper libraries exist for creating JWTs. A Python example is provided to create JWT.

Using the client’s RSA private key, with RS256 hashing (as specified for an algorithm (alg) parameter value in RFC7518), the signed token value becomes:

eyJhbGciOiJSUzI1NiIsImtpZCI6ImVlZTlmMTdhM2I1OThmZDg2NDE3YTk4MGI1OTFmYmU2IiwidHlwIjoiSldUIn0.eyJhdWQiOiJodHRwczovL3NyYS12ZW5kb3ItdGVzdC5kaWdpdGFsaGVhbHRoLmdvdi5hdS9TcmFBdXRoQXBpL2F1dGgvdG9rZW4iLCJleHAiOiIxMzUyNjYwMDA4IiwiaXNzIjoiOGIwOTE0ZTAtMDliNC00N2Q3LTlmYzktZWIzZGRhZjJmN2FhIiwianRpIjoicmFuZDBtLW4wbi1yZXVzYWJsZS1qd3QtMWQtMTIzIiwic3ViIjoiOGIwOTE0ZTAtMDliNC00N2Q3LTlmYzktZWIzZGRhZjJmN2FhIn0.iRgDMWwNC8CEQT8GeC9eAF7K81dIa-KptdCWrmFepafqQ163M8sYLI96NtoxZqhReWt6qUB7GcziciTs-5eiOZhcyRjFZDukOL7QXFt6_c8TwvKCgzG6yzb0rMKOXdfn7z5ruKq-TjEHhv0ph7sgTlcC2hVPSFb10W9Rep8B1zQ02WfnatMhQq8vKfOHhX9ZM7Lbwq5wtREigjXubGTmRltjzulbgeAqLfxdylePS7h1LFNSrkK0uC_OkGtdfL0uqCBE1betfhxaXf4ADay9QXuiex9lroPcHtdqHkGYcS303a9abProG2hUUCgysuvTRW3_924Rsjq_GiAGqIdcNQ

NOTE: To inspect this example JWT, you can visit https://jwt.io.

1. Paste the signed JWT value as above into the “Encoded” field
2. Paste the my-public-key.json into the “Public Key” box of the Verify Signature block
3. The plain text JWT will be displayed in the “Decoded” field, and
4. The “Signature Verified” message will appear.

 

 Home | Back: Register clientNext: Get access token

Trade marks of the Australian Digital Health Agency: 
Provider Connect Australia™, Helping healthcare providers stay connected™

PCA logo
PCA logo

On this page