Authorization Handshake

Let's say we have two services, fixmystl.com and stlwarehouse.net. The former is a service that makes models printable, the later a service for storing model files. We need to get the two working for our user, Bob, who wants to store the STLs in stlwarehouse.net and send them to fixmystl.com.

Bob has a model that lives at https://stlwarehouse.net/model/ABC-123. He wants to provide fixmystl.com access to part of his warehouse. First he'll need to create an API key to give to fixmystl.com.

POST https://users.stlwarehouse.net/api-key/
Content-Type: application/json

{
    "name"  : "STL Warehouse"
}

Location: https://users.stlwarehouse.net/api-key/XYZ-PDQ/
X-Api-Key-Secret: 12345

He then needs to grant the ability for this api-key to access model data

POST https://users.stlwarehouse.net/api-key/XYZ-PDQ/grant/
Content-Type: application/json

{
    "namespace" : "models",
    "actions"   : ["create", "read"],
}

Now Bob has an API key that he can provide to fixmystl.com that has permission to read model data and create new models. He sends the following request to fixmystl.com:

POST https://fixmystl.com/repair-job/
Content-Type: application/json

{
    "model"     : "https://XYZ-PDQ:12345@stlwarehouse.net/model/ABC-123",
    "name"      : "My repair job",
    "callback"  : {
        "method"    : "POST",
        "url"       : "https://XYZ-PDQ:12345@stlwarehouse.net/model/",
    }
}

This instructs fixmystl.com to start a new repair job using the model resource that is found at https://XYZ-PDQ:12345@stlwarehouse.net/model/ABC-123. When the repair job is complete it will send a POST request to https://XYZ-PDQ:12345@stlwarehouse.net/model/ with the information about the job that was completed. Both URLs contain the credentials that allow fixmystl.com to operate on behalf of Bob.

When fixmystl.com makes the request to get the model data it will pass the credentials it was provided as the Authorization header. stlwarehouse.net will then look up the api-key, discover it is a key created by Bob, check that the key has access to read model data, find that it does and then provide the model data to fixmystl.com. fixmystl.com will perform the repair operation on the model and then execute the callback request.

The callback request will look something like this

POST https://stlwarehouse.net/model/
Authentication: Basic WFlaLVBEUToxMjM0NQ==
Content-Type: application/json

{
    "name"      : "My repair job",
    "content"   : "https://fixmystl.com/fix-job/111-222/?signature=abc&expires=123",
}

The name is just a passthrough on the name of the job that the user originally provided. The content is a signed URL that will allow stlwarehouse.net to pull down the contents of the fixed model. This would be similar to how Amazon's S3 service can produce signed URLs with an expiration. The specific security mechanism isn't important, we just need the URL to allow stlwarehouse.net to make a GET request and get the model data. This is necessary because the callback was a POST to the model resource and will create a new model and set the content of that model to the content provided in the URL.

The effectiveness of this scheme relies on several key points:

• Both services must work over https to protect the API tokens. Any use of http will breach security

• The services must agree on the signature of the callback requests and match them up in order to create new resources

• fixmystl.com must be able to provide a signed content link

• The user has to be pretty sophisticated to make this work. But they can make it work

The advantages to this structure include:

• The user never has to download any large data files. The user is simply orchestrating

• The system could still work with different authentication mechanisms such as OAuth, the difference would be that there would be more configuration and state

• Any new service could come along without either service having to know about it and could become part of the ecosystem