Create API key for Notify to use

[dinophile]

Need to manually create a key for Notify only. Will be used as a github secret for MVP.

[cgye]

Likely 3 keys are required:

• for Notify
• for Route 53 health checks
• for general usage (i.e. does not fall into any specific categories above)

Request

The API Key should be specified in HTTP Authorization header as a Bearer token, see: rfc6750 and rfc7325:

   Authorization: Bearer <api key>

The API Key is base64 encoded (see: here)

Response

The WWW-Authenticate response header field must be used for authentication related error when a bearer token is used (see: here).

Error Codes

When a request fails, the respond contains an HTTP status code and includes one of the following error codes in the response:

• invalid_request
  • The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed.
  • The resource server SHOULD respond with the HTTP 400 (Bad Request) status code.
• invalid_token
  • The access token provided is expired, revoked, malformed, or invalid for other reasons.
  • The resource SHOULD respond with the HTTP 401 (Unauthorized) status code.

Furthermore, the error and error_description fields will be used to provide additional information about an error.

     HTTP/1.1 401 Unauthorized
     WWW-Authenticate: Bearer realm="UrlShortener",
                       error="invalid_token",
                       error_description="The api key is invalid"

If the request lacks any authentication information (e.g., the client was unaware that authentication is necessary or attempted using an unsupported authentication method), the resource server SHOULD NOT include an error code or other error information. For example:

     HTTP/1.1 401 Unauthorized
     WWW-Authenticate: Bearer realm="UrlShortener"

Notes

• RFC 6750 forbids sending api key/access token in URI query parameter (see: here) due to security weakness , including the high likelihood of URL containing the api key/access token will be logged.
• In terms of rotation requirements, in general, api key is not considered secure and should not be deployed in public environments. In controlled environments, manual rotation should be sufficient. The extra complexity required for rotating api key is not worth it. If/when there is a need to rotate api key in a scalable/automated manner, it is generally better to go with an access token implementation which is more secure and designed to work in public scalable environments. For a more elaborate discussion on this topic, see: here).

[cgye]

@sylviamclaughlin @dinophile @maxneuvians If you have some time, can you review the above spec for API key? Thx. Will also update this api doc when finalized: https://github.com/cds-snc/url-shortener/pull/196

[sylviamclaughlin]

@cgye - the spec looks good to me. Don't know if you thought about implementation yet, but Fastapi does provide some innate functionality for handling api tokens that you might want to take a look if you deem appropriate.

[cgye]

@cgye - the spec looks good to me. Don't know if you thought about implementation yet, but Fastapi does provide some innate functionality for handling api tokens that you might want to take a look if you deem appropriate.

Thanks for the link. Yes, this should make implementation easier :)

[maxneuvians]

LGTM as well! I think the JWT route is interesting in terms of that requests after the initial authentication request have a time bound token. Having a fixed API key take away some complexity on the client side ex. reauthenticating after the JWT expires. In the past we just used a straight up fixed API key https://github.com/cds-snc/scan-websites/blob/main/api/api_gateway/routers/scans.py#L64-L75 but happy to also try out the JWT route, if you think it is worth it for the additional security.

[patheard]

This has now been added. You can test the various behaviour for the /v1 shorten route with the following:

# Success
curl -v -X POST https://url-shortener.cdssandbox.xyz/v1 \
-H "Authorization: Bearer $VALID_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"original_url": "https://digital.canada.ca"}'

# Failed auth
curl -v -X POST https://url-shortener.cdssandbox.xyz/v1 \
-H "Authorization: Bearer foo" \
-H "Content-Type: application/json" \
-d '{"original_url": "https://digital.canada.ca"}'

# Missing auth
curl -v -X POST https://url-shortener.cdssandbox.xyz/v1 \
-H "Content-Type: application/json" \
-d '{"original_url": "https://digital.canada.ca"}'

As for implementation:

• I added 2 auth tokens: one for Notify and one for us (general purpose). This is currently not used as the UI implementation calls the shorten method directly (does not use the API).
• I only protected the /v1 route so a 3rd auth token for health checks isn't needed, but I could easily add this if people wanted it.

[cgye]

Cool, thanks @patheard !

[maxneuvians]

Closed in #210, #212. #213