Magda access token is a JWT token signed with the private key and can be verified with the public key.
The JWT token payload contains the following fields:
iss: always be magda.io. could be configurable in future.
sub: an UUID to identify the access token.
aud: audience of the access token. Recipient who receives this access token must verify this field is agreed value.
e.g. if the token is issued for securing files from an object storage service, the audience can be used to set the initial scope of the access. e.g. its value can be set to s3://bucket1/patha/pathb. The recipient will need to verify whether the request is for bucket bucket1 and start with path /patha/pathb.
When a token is issued for a record, by default, the audience field will be generated as following:
If there is a storage source access record that is associated with the distribution record, the uri field of the storage source access record will be used to encode the aud field.
Otherwise, the default bucket configured for the system will be used as the bucket name, and the default prefix path will be generated according to this rule.
exp: The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
operation_uris: (optional); (string[]); a list of approved operation uris. when exist, the recipient who receives this access token must verify if the intended action match one of the operation uri.
authorisation_decision: (optional); (object with a list of field); When not exist, the recipient can assume the decision is true / allowed. The field & format of the decision object is same as decision API response
hasResidualRules: bool
result: (optional); any; most cases should be boolean;
unknowns: (optional); string[];
residualRules: (optional); object[];
Storage Source Access Record
A storage source access record is a metadata record that describes the external storage source access granted to one Magda distribution record. The record comes with a storage-source-access-details aspect with the following fields:
description: (optional) some text comments about this access grant
uri: a URI identifying the source and its scope. The uri field will be used to encode aud field when issue access token.
e.g. s3://bucket1/path1 indicate sharing access to any resource with path prefix /path1 on an s3 compatible storage service bucket bucket1.
https://xxx.com/path1 indicate sharing access to any resource with path prefix /path1 on an HTTPS host xxx.com
recordId: the id of the distribution record that is granted access to this storage source.
There will be only one storage source access record can be created for the same distribution record.
Please note, the storage source access record will grant the access rather than cover any actual access details (e.g. access token, key etc.). The access details should be managed directly at the access proxy services. e.g. AWS cloudfront + AWS lambda function.
What's the Usage of Magda Access Token
All Magda services should support the access token authentication in additional to api key authentication as API key is slow to verify.
Can be consumed by a lambda function and together with cloudfront over s3 service. This will allow federated / decoupled group resources authorisation.
Use case:
Assume a GeoSpatial dataset comes with a list of small size assets store in a s3 bucket
One asset / file could be a tile to be loaded into a map for visualisation.
At frontend, it might be required to request a few 100s assets depends on user's view port over the map
it will be inefficient to authorisation those request by: 1> proxy 2> authorised access to a single file
We can issue an access token that define lambda request attributes as unknowns (e.g. request url path) and issue access token with partial auth decision.
e.g. the partial decision could be req.path startWith "/myBucket/abc/def"
Supply a generic token verification function to be run as a lambda function
How Magda route the resource access requests
By default, the client may choose to send all resource access requests to the storage API
to endpoint: GET /api/v0/storage/[path to resource] with access token embedded in the Authorization header
Instead of letting storage API proxy the request, the client can also choose to send the request to an external endpoint (e.g. AWS CloudFront) with Authorization header for better performance
The client can look up an endpoint list table by the storage source access record uri to locate the endpoint where the request should be sent to.
Client can query storage API for the full list of endpoint table or lookup the endpoint by source URI
Magda Access Token Authentication Support
What's Magda Access Token
Magda access token is a JWT token signed with the private key and can be verified with the public key.
The JWT token payload contains the following fields:
iss
: always bemagda.io
. could be configurable in future.sub
: an UUID to identify the access token.aud
: audience of the access token. Recipient who receives this access token must verify this field is agreed value.audience
can be used to set the initial scope of the access. e.g. its value can be set tos3://bucket1/patha/pathb
. The recipient will need to verify whether the request is for bucketbucket1
and start with path/patha/pathb
.storage source access record
that is associated with the distribution record, theuri
field of thestorage source access record
will be used to encode theaud
field.exp
: The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.operation_uris
: (optional); (string[]); a list of approved operation uris. when exist, the recipient who receives this access token must verify if the intended action match one of the operation uri.authorisation_decision
: (optional); (object with a list of field); When not exist, the recipient can assume the decision istrue
/allowed
. The field & format of the decision object is same as decision API responsehasResidualRules
: boolresult
: (optional); any; most cases should be boolean;unknowns
: (optional); string[];residualRules
: (optional); object[];Storage Source Access Record
A
storage source access record
is a metadata record that describes the external storage source access granted to one Magda distribution record. The record comes with astorage-source-access-details
aspect with the following fields:aud
field when issue access token.s3://bucket1/path1
indicate sharing access to any resource with path prefix/path1
on an s3 compatible storage service bucketbucket1
.https://xxx.com/path1
indicate sharing access to any resource with path prefix/path1
on an HTTPS hostxxx.com
There will be only one
storage source access record
can be created for the same distribution record.What's the Usage of Magda Access Token
lambda
request attributes as unknowns (e.g. request url path) and issue access token with partial auth decision.How Magda route the resource access requests
Authorization
headerAuthorization
header for better performancestorage source access record
uri to locate the endpoint where the request should be sent to.