MercuryGate APIs: Security Overview (beta)

API Security

Security for all APIs, both incoming to and outgoing from MercuryGate, must use OAuth2, specifically Authorization Code Grant using Proof Key for Code Exchange (PKCE), to obtain access and refresh tokens used to communicate on behalf of a customer.

All calls to OAuth or API endpoints must use https, and must support TLS 1.2 or greater (TLS 1.3 preferred).

Partner On-boarding

Part of the Partner on-boarding process is the generation of client credentials through Client Registration. This registration is performed on the Partner system to create a Client ID and Client Secret for MercuryGate, as well as on the MercuryGate Authorization Server to create a Client ID and Client Secret for the Partner to use.

On-boarding also includes exchanging Authorization Server urls as well as any urls needed to call the various endpoints to be used. Other agreements and exchanges of information may also be required.

Customer Authorization

Once a Partner has been onboarded and customers have performed any required data-mapping or configuration necessary to use the API layer, a customer Super-User with the authority to authorize a connection with Partners must authorize the connection to MercuryGate and/or to the Partner (depending on the APIs involved) using an Authorization Code Grant between the systems. This is a one-time setup for the customer; it is not user-specific. Users will not have the opportunity to re-authorize during the course of using the APIs, as the client will be back-end systems (not the user's browser).

The customer Super-User will initiate a process whereby they will complete whatever actions are required by MercuryGate or the Partner to authorize the connection. This may include things such as filling out forms, signing contracts, or agreeing to usage agreements. Upon completing the process, the Authorization Server will provide an authorization code to the client system. The authorization code is used by the client system to make a back-end request to the Authorization Server to request the refresh and access tokens to be used when making service calls to the remote endpoints

Note that each customer has their own tokens identifying the parties involved in the service call. The body of the call will not include the tenant or partner identifiers -- they are implicitly associated with the token, and typically stored as claims.

Terms

Access Token: An access token is a cryptographically-signed time-limited bearer token used to make API requests on behalf of a customer. It uses the standard OAuth2 format, JSON Web Token (JWT). The access token's expiration should be chosen to allow for re-use, but also to be limited to protect against attacks.
Authorization Code Grant: The Authorization Code grant is used by confidential and public clients to exchange an authorization code for an access token. In MercuryGate integrations, use of the Proof Key for Code Exchange (PKCE) extension is required.
Authorization Server: The authorization server is what the user interacts with when an application is requesting access to their account. This is the server that displays the OAuth prompt, and where the user approves or denies the application’s request. The authorization server is also responsible for granting access tokens after the user authorizes the application.
Client: The application (in this case the Partner system or MercuryGate External API layer) that is attempting to act on the customer’s behalf or access the customer’s resources.
Client ID: A unique string issued by an Authorization Server representing the registration information provided by the client. The client identifier is not a secret and is unique to the authorization server.
Client Secret: A secret (similar to a password) used by the Client to authenticate that it is the Client represented by a given Client ID. This is only used during Authorization Code grants to generate access and refresh tokens.
Partner: A MercuryGate term describing a party integrating with a MercuryGate API. A Partner may be a carrier, vendor, service aggregator, other third party, or even a customer. Parties that fall into multiple categories will be treated as separate partners, so that integrations may be segregated into private (as-a-customer integrations) vs public (as-a-vendor integrations).
Refresh Token: A cryptographically-signed time-limited token used to generate new tokens when an access token has or is about to expire. The refresh token's expiration should be chosen to be very long-lived to prevent expiration when infrequently used, or the customer may lose access and need a Super-User to re-authorize the integration. The use of refresh tokens is required by MercuryGate.
Super-User: A customer user with the training and skills required to make configuration changes, as well as the authority and access to enable integrations on behalf of the customer. Only super-users are allowed to authorize integrations.