Authentication service overview
The authentication service is responsible for beqom’s authentication system, i.e. the mechanism that enables users to log into the Pay Suite application and use its features.
The authentication service is built on top of the Duende IdentityServer (an OpenID Connect and OAuth 2.0 authentication framework for ASP.NET Core) and the SAML2P component, which enables the Duende IdentityService to act as:
An identity provider which uses the OIDC flow (and could potentially be extended with SAML).
A service provider (client) to external systems, using OAuth2/OIDC and SAML flows.
The authentication service is a standalone service deployed on a separate domain. Consisting in both front-end pages and Web APIs, it can be used from internal products, such as Pay Suite) and from external integrations.
As a standard, interaction with the authentication service conforms to the OAuth2/OIDC protocols. For interactive applications, interaction is handled via a redirection or a contextual window.
This is an note/information message.
For more information about Duende IdentityServer, visit the Duende Website.
For more information about SAML2P, visit the provider's Website.
For more information about the OAuth 2.0 protocol, visit the OAuth guidance Website.
For more information about OIDC, refer to Microsoft's documentation.
High level architecture
The following diagram offers a high level view of the architecture of the authentication service and its interactions with the other components and protocols:
Pay Suite authentication diagram
Public APIs
All of the APIs offered by the authentication service are public so that unauthenticated users can access those APIs and obtain the tokens they need to access the Pay Suite application.
The authentication service is reachable via a reverse proxy mechanism that handles, among other things, DNS domain mapping and HTTP headers.
In circumstances where the authentication service needs more resources, the reverse proxy then interacts with Kubernetes cluster and redirects the calls to the currently active instances.
Users & external ID providers
Pay Suite users interact with the authentication service via REST APIs. The login process is initiated when the user issues an authentication request to the authorize endpoint (for more information about this endpoint, refer to the Duende documentation), as provided by the OpenID Connect standard.
Once the endpoint is called, one of the following scenarios unfolds:
The authentication service determines that an exchange of code/token has already recently taken place. In this case, it redirects the client toward the token endpoint (for more information about the token endpoint, refer to the Duende documentation) where it obtains a new identity token and the user immediately lands on the application main page.
The authentication service redirects the client to the identity server registered for the tenant and in which the user has an active session. A code is immediately returned and the client is redirected to the token endpoint to obtain the corresponding identity token. The user lands on the application main page without entering any credentials.
The authentication service redirects the client to the identity server of the tenant, where the user must enter their credentials. The user is presented with the login page of their own identity provider and, after entering their credentials, they land on the application main page.
The tenant offers the possibility to use form authentication using the login form offered by the Pay Suite Web application itself. The user is then presented with the Pay Suite login page where they can enter their credentials.
After the redirection to the external identity provider, the exchange of credentials across the two security domains can take place according to either OIDC or SAML. The actual protocol used depends on the settings stored per tenant in the configuration database. Each tenant can register one or several identity providers, and enable form authentication.
Given the nature of the code grant type, the authentication service interacts with the identity server of the tenant on behalf of the client and exchanges the code with the identity token in the back channel. It returns the identity token to the client from the call to the token endpoint to complete the authentication process.
Tenant discovery
Every user belongs to a tenant (i.e. a client) and every authentication request must be associated with the name of the tenant for the authentication service to know how to initiate the login process and check if the user logging in exists and has been previously registered. There are two options to identify the tenants:
The user lands on a page where the tenant ID is the DNS subdomain itself
A tenant discovery page is opened under the Pay Suite Web application domain, where the user can submit their ID explicitly.
In both cases, when the client calls the authorize endpoint to trigger the authentication process, the ID of the tenant must be specified as an acr_value in the query parameters (for more information, refer to the Duende documentation). Once the tenant is known, the authentication service attempts to direct the user to the application main page without any further interaction, or to redirect to a page where the login options available for the tenant are displayed.
Once the identity token is released, the tenant ID is included in the claims of the token so that any future request to any API can be redirected to the right tenant database.
Eternal grant & MQTT messaging
Among the features supported in the Pay Suite application, there is the possibility to invite external users to participate to surveys. Before submitting a new survey, the creator of the survey can send an invitation to users not registered in the tenant by specifying their email address. These external users then receive an email with a link to the survey: the link contains a base64 string in the query parameter that plays the role of token.
Unauthenticated users are then redirected to the authentication service, where the token in the query parameters is processed to extract the identifier of the user and the type of action that the user is supposed to perform. The control of this data is delegated to the AIM service, queried via RPC running over MQTT messages.
This custom form of authentication is implemented in the authentication service by defining a new type of grant, called "external grant".
Configuration & seeding
When the authentication service starts for the first time in a new environment, the authentication schema of the database is automatically created via .NET EF migrations.
The seeding of the authentication service database is handled by the beqom operation teams via a service named Tenant Applications Management (TAM). This service is responsible for editing the settings related to the tenants such as tenant names, aliases, list of identity providers, etc., as well as provisioning the tenant databases themselves.
The tenant applications management (TAM) service must therefore manipulate data in the authentication service database. There are three options available for the TAM to accomplish this task:
Access the authentication service database directly with a connection string retrieved from a key vault.
Use some APIs from the authentication service that are accessible only via VPN.
Use some APIs from the authentication service that require authorization. TAM performs the authentication via client credentials and specific permission grants are embedded in the JWT token.
Signing keys
At the end of the authentication flow, the authentication service releases JWT tokens that must be signed so that external services can assess their integrity. To do this, the service manages a set of keys that is stored, rotated at defined intervals and deleted at defined intervals. The keys are stored in a dedicated Azure Key Vault and maintained via Duende’s automatic key management service (for more information, refer to the Duende documentation).
Load balancing
The authentication service runs as a Docker container in a Kubernetes cluster. To implement load balancing, the authentication service exposes a couple of health check REST endpoints that can be called to monitor the service or the connection to the Postgres database.
Customer onboarding
The following table describes the flow that is followed to provide access to the Pay Suite application to any given customer.
| Step # | Step name | Description |
|---|---|---|
| 1 | Tenant creation | A tenant entity is created by the beqom operations team. |
| 2 | Tenant alias creation |
Optional If aliases are required, the beqom ops team creates them. Multiple aliases can be created for a single tenant. |
| 3 | Programmatic client creation |
Optional If the customer needs to use APIs to integrate data into the system or extract data out of the system, then a programmatic client needs to be created. |
| 4 | Custom domain setup |
Optional If a custom domain is required, it needs to be configured for authentication. To do this, an alias is created for the custom domain and the domain is added to the list of authorized redirects. |
| 5 | External provider configuration |
If SAML is used, beqom provides the following parameters:
On their side, the customer needs to provide the following information:
|
| 6 | Identity provider creation | Based on the information obtained from the customer, the identity provider is declared by beqom. |
| 7 | Identity provider connection | The identity provider is connected with the tenant using the IDs of the created entities. |
This is an note/information message.
For more information about the operations to be performed on the customer side to set up SSO, refer to .