Authorization Tokens

Each PipelineJob is secured with an authorization token that must be sent with every event or management request that could result in a change in the job’s state or availability.

There are two kinds of tokens: Document Update tokens authorize most events and actions for a specific PipelineJob. Exceptions include reset, ready, and delete events, which are only authorized by Administrative Action tokens.

Document Update Tokens

Below is an example of capturing and re-using a document token while managing a PipelineJob.

>>> mpj = ManagedPipelineJob(mongodb, pipelines, agave=agave_client, ...)
>>> mpj.setup()
>>> resp = mpj.run()
>>> token = resp.get('token')
>>> jid = resp.get('uuid')
>>> print(token, jid)
a3b29f2c62ec9d15 1071269f-b251-5a5f-bec1-6d7f77131f3f

Now, assume some magic happens and there is another process that needs to manage the job we just set up. Assume also that you remembered the job UUID and token and have passed it into the process. The example below illustrates initializing a ManagedPipelineJobInstance and using it to trigger an update event.

>>> from datacatalog.managers.pipelinejobs import ManagedPipelineJobInstance
>>> job_uuid='1071269f-b251-5a5f-bec1-6d7f77131f3f'
>>> job_token='a3b29f2c62ec9d15'
>>> mongodb={'authn': 'bW9uZ29kYjov...jRWJTI2SCUyQiy1zdGFnIwL2W1hcnk='}
>>> mpji = ManagedPipelineJobInstance(mongodb, job_uuid, token=job_token)
>>> resp = mpji.update()
>>> token = resp.get('token')
>>> print(token)
a3b29f2c62ec9d15

Administrative Action Tokens

These powerful credentials authorize any event for any PipelineJob, including reset, ready, and delete. To limit the risks of such power being included in a git commit or send over email, administrative tokens are invalidated and reset every seconds. To generate and receice an administrative token, you must supply a valid Admin Token Key, which is provided on request after a review of your planned use case and your readiness to use it safely.

Retrieve and Validate a Token

>>> from datacatalog.tokens import get_admin_token, validate_token
>>> from datacatalog.tokens import get_admin_lifetime
>>> from time import sleep
>>> akey = 'STbmczGuxqvQSN6YCaA2CmHbpet2tZHc'
>>> atoken = get_admin_token(akey)
>>> validate_token(atoken)
True
>>> sleep(get_admin_lifetime * 2)
>>> validate_token(atoken)
False
>>> atoken = get_admin_token(akey)
>>> validate_token(atoken)
True

This token can be used in lieu of a Job-scoped token. The example below illustrates using it for an update event, then for a reset event, which is priviledged action.

Use the Administrative Token

>>> from datacatalog.managers.pipelinejobs import ManagedPipelineJobInstance
>>> from datacatalog.tokens import get_admin_token
>>> mongodb={'authn': 'bW9uZ29kYjov...jRWJTI2SCUyQiy1zdGFnIwL2W1hcnk='}
>>> akey = 'STbmczGuxqvQSN6YCaA2CmHbpet2tZHc'
>>> atoken = get_admin_token(akey)
>>> mpji = ManagedPipelineJobInstance(mongodb, job_uuid, token=atoken, ...)
>>> update_doc = {'uuid': self.uuid,
                  'name': 'reset;,
                  'data': {}}
>>> mpji.handle(update_doc, atoken)
>>> reset_doc = {'uuid': self.uuid,
                 'name': 'reset;,
                 'data': {}}
>>> mpji.handle(reset_doc, atoken)