Magda Access Token Authentication Support

[t83714]

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 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