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.zzzzzAuthentication JWT Header Values
| Parameter | Cardinality | Details |
|---|---|---|
| alg | Mandatory | The JWA algorithm used for signing the authentication JWT - must be RS256 |
| kid | Mandatory | The identifier of the key-pair used to sign this JWT. This identifier shall be unique within the client's JWK Set. |
| typ | Mandatory | Fixed value : JWT |
An example for the JWT header values:
{
"alg": "RS256",
"kid": "eee9f17a3b598fd86417a980b591fbe6",
"typ": "JWT"
}Authentication JWT Claims
| Parameter | Cardinality | Details |
|---|---|---|
| iss | Mandatory | Issuer 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) |
| sub | Mandatory | The 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) |
| aud | Mandatory | The PCA™ Identity and Access Manager's "token URL" (the same URL to which this authentication JWT will be posted to) |
| exp | Mandatory | Expiration 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. |
| jti | Mandatory | A 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_GiAGqIdcNQNOTE: 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 client | Next: Get access token
