Back-end API for the mobile app
The back-end API provides the actual functionality for viewing and moving inventory from the warehouse to the store. The sample code is capable of acting as a policy enforcement point, or just providing the pure API functionality and delegating the policy enforcement to a third-party API gateway.
The configuration instructions explain how to enable the policy enforcement functionality. If policy enforcement is handled by a third-party API gateway, do not enable policy enforcement.
A sample deployment of the API is available, but should not be used for demonstration purposes. The availability of the sample deployment is not guaranteed.
To ensure that the enforcement point cannot be circumvented, the communication between the enforcement point and the back-end API needs to be secure. This can be done by network configuration, but a more common approach is to use mutual TLS authentication with client and server certificates. The sample back-end API does not feature this functionality.
The back-end API Docker container includes Swagger documentation and
sample data. You can find the Swagger documentation
at (https://<container_base:port>/swagger/index.html).
Install the back-end API
Download the Docker container from the repository and follow the installation instructions for your Docker-capable environment.
-
Container: https://github.com/orgs/ThalesGroup/packages?repo_name=sta-api-access-management
-
Source code: https://github.com/ThalesGroup/sta-api-access-management/tree/master/Backend%20API
The source code contains build instructions, in case you want to create your own container.
The response body is also defined, depending on the JWT events.
Configure the back-end API
If policy enforcement is handled by a third-party API gateway, do not enable policy enforcement. To use the back-end API without any policy enforcement, no configuration is required.
When debugging in the web profile, use the src/Store/appsettings.json file to define the settings.
When debugging in the Docker profile, use the src/Store/Properties/launchSettings.json to define the settings.
By default, the sample code does not have authorization and authentication turned on. If JwtAuthorizationAndAuthenticationEnabled is set to true, you must also set the Authority, otherwise the application will not start.
If ValidateIssuer is set to true, the Issuer must have a valid value, otherwise the JWT authorization will always fail.
If ValidateAudience is set to true, the ClientId must be a valid value, otherwise the JWT authorization will always fail.
| Setting | Value | Default |
|---|---|---|
| JwtAuthorizationAndAuthenticationEnabled | If true, enables authentication and authorization. | false |
| ValidateIssuer | If true, ensures that the Issuer (iss) in the JWT is validated. | true |
| Issuer | If ValidateIssuer is true, then the JWT issuer must match this property. | |
| ValidateAudience | If true, ensures that the Audience (aud) of the JWT is validated. | true |
| ClientId | If ValidateAudience is true, then the JWT audience must match this property. | |
| Authority | The well-known openid-configuration URL where the JWT public key is defined. It is used to validate that the token has not been tampered with. |
Sample code
The sample code demonstrates how to enable authentication and authorization on a sample Swagger API. Enabling authentication ensures that a JWT is valid. For example, a valid JWT has not been tampered with and has not expired. Enabling authorization checks that the JWT has specific claims when a JWT is used.
Middleware
The code in src/Store/Middleware/ defines both the authorization and authentication.
The JwtMiddleware is injected in Startup.cs by calling services.AddJwtAuthorizationAndAuthentication(Configuration). In this method, we define how the JWT is authenticated (using the TokenValidationParameters).
The response body is also defined, depending on the JWT events.
Authorization is defined in policies. In the sample code, two policies are defined:
-
JwtClaimMustContainManager checks that the JWT has a claim called groups and that it must have manager in the claim.
-
JwtClaimMustContainManagerOrEmployee defines that the JWT must have either manager or employee in the groups claim.
If any of this is not true, the response to the request is Unauthorized.
The implementation details for the policy can be found in the JwtClaimMustHaveSpecifiedGroup class.
Defining authorization and authentication in the back-end API
Methods that need only authorization, which is verification that the JWT has not been tampered with and has not expired, have the [Authorize] decorator. Sample code can be found here.
Methods that need both authorization and authentication that the token has manager or employee in the groups claim have the [Authorize(Policy = JwtClaimMustContainManagerOrEmployee)] decorator. Sample code can be found here.
Methods that need both authorization and authentication that the token has manager in the groups claim have the [Authorize(Policy = JwtClaimMustContainManager)] decorator. Sample code can be found here.
API functions
The following functions are available:
Before you start, call the reset endpoint, to ensure that the system is in a sane state. An initial set of sample data, including shops, warehouses and inventory, is automatically available when the Docker container is set up and running. You can do this from the demo application's setup screen.
