Oauth2 token that restricts access to a single resource - security

Question

We make use of a thrird party Email Service Provider (ESP) to send emails to our customers. One of the emails needs to have a file attached to it. To accomplish this we need to give the ESP a URL of the file. The ESP will download the file and attach it to the email.
We are now working on a solution to secure the URL to limit the risk of unauthorized downloads. The ESP cannot authenticate itself while making the request to the URL, so the only option we see is by making the URL hard to guess and making it valid for a limited time.
The way we want to accomplish this is by putting a token in the URL's querystring. The service that hosts the file will validate the token and authorize access. The token will need to expire in time and should only give access to a specific file.
We already have a IdentityServer 3 implementation running an oAuth2 Security Token Service. Our plan is to let this service generate the tokens that will be put in the query string of the file download URL. We are considering creating a custom oAuth2 grant type to support tokens that will only allow access to a specific resource.
This would be an example of a request to the oauth2 token endpoint with the custom grant:
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=custom_grant&scope=attachment.read&resource_id=xxxxx
The STS will return a token with a claim of the resource ID the token will give access to.
Is the right use case for a custom grant type or should we look for a different way to implement this?

Answer 1

I think what you're proposing is fine, but I personally prefer using something based on cryptographic signatures for this sort of thing.
JSON Web Token is a well-established way to do this with support in a lot of programming languages. Essentially, you sign a JSON dictionary, including an expiration time. Then you attach it to the URL (e.g. as a query parameter). When receiving an inbound request, you validate the token by checking the signature, expiration time, and the resource it says it applies to.
The advantage of this approach is that there's no needless state: you don't have to store tokens anywhere and instead just need a signing key.
Here's an example in Python that shows the basic idea:
import time
import jwt
SIGNING_SECRET = 'use-a-good-secret-here'
token = jwt.encode({
'resource_id': 'xxxxx',
# JSON spec establishes "exp" as meaning expiration time
'exp': time.time() + 1, # one second in the future for testing
}, SIGNING_SECRET, algorithm='HS256')
print(token)
def try_decoding(token):
try:
decoded = jwt.decode(token, SIGNING_SECRET, algorithms=['HS256'])
print('Valid token for "{}"'.format(decoded['resource_id']))
except jwt.exceptions.ExpiredSignatureError:
print('The token has expired.')
try_decoding(token) # prints 'Valid token for "xxxxx"'
print('Sleeping until the token expires...')
time.sleep(2)
try_decoding(token) # prints "The token has expired."