Authentication
The method of authentication used when making a request to the COMS API will depend on the Authentication Modes enabled on the COMS API deployment you are using.
Note: The BC Gov Hosted COMS service currently only allows OIDC Authentication using JWT's issued by the Pathfinder SSO standard keycloak realm).
With COMS running in this mode, all requests to the COMS API must be authenticated using a User ID token (JWT) issued by an OIDC authentication realm. The JWT should be added in an Authorization header (type Bearer token).
COMS can only authenticate using JWT's issued by one OIDC realm that must be configured when COMS is deployed. JWT's are typically issued to an application and saved to a user's browser when he/she signs-in to a website through the Authorization Code Flow. Both the website (client app) and the instance of COMS must be configured to use the same OIDC authentication realm in order for the JWT to be valid.
When COMS receives the request, it will validate the JWT (by calling the OIDC realm's token endpoint). The JWT is a reliable way of verifying the the user's identity on which the COMS permission model is based.
Figure 2 - The general network flow for a typical COMS object request
The most anticipated use case for COMS is to download a specific object. Clients will first authenticate with the OIDC realm to acquire a JWT. Assuming clients are authorized, their request for an object resource will yield a 302 temporary redirect link pointing directly to the S3 endpoint. The client will be able to download their object after following the redirect. As the 302 redirect link is designed to be temporary (the signature of the link will eventually expire, usually after 300 seconds), unauthorized access direct to the S3 store is not possible as you will require COMS to generate a signed temporary link on your behalf.
COMS supports either the redirect flow as illustrated in Figure 2, or directly through COMS as a proxy. COMS uses the redirect flow by default because it avoids unnecessary network hops. For significantly large object transactions, redirection also has the added benefit of maximizing COMS microservice availability. Since the large transaction does not pass through COMS, it is able to remain capable of handling other client requests.
If 'Basic Auth Mode' is enabled in your COMS instance, requests to the COMS API can be authenticated using an HTTP Authorization header (type Basic) containing a username and password configured in COMS.
This mode offers a more direct access like a 'service account' authorized in the scope of the application rather than for a specific user and by-passes the COMS object/bucket permission model.
Basic Auth mode is not available on our hosted service.
This mode configuration is generally recommended when you expect to run COMS in a highly secured network environment and do not have concerns about access control to objects as you have another application handling that already.