Security guidelines
This topic contains guidelines that help you set up secure connections with Web APIs.
Authentication & authorization
Authentication and authorization are important concepts related to Web API security.
- Authentication is the process of knowing the identity of the user trying to access the Web API.
- Authorization describes the level of access that the authenticated user has: what actions can the user perform, and what resources does the user have access to?
note
We strongly recommend using existing frameworks and middleware rather than trying to develop your own Oauth 2.0 and OpenID Connect integration. There is a number of excellent products available on the market, ranging from extendable frameworks to lightweight middleware.
We recommend the iCore Identity Server - a modern, technically profficient product which is easy to set up and use. The Identity Server is currently available as a free preview version.
For more information, see Securing a Web API with OAuth 2.0 (iCore Identity Server).
Claims and permissions
Information about a user in OpenID Connect is presented as claims,
such as the claim subject ("sub") representing the user id for the user
with the issuer, or the claim "email" representing a known email
address for the user. There are a number of commonly shared claims
types, which can be found in (for example)
System.Security.Claims.ClaimTypes or
IdentityModel.JwtClaimTypes.
Regarding claims, the following is important to keep in mind:
- Always try to configure as few claims as possible (mainly to conserve space in cookies).
- Only store points of data which is unlikely to change frequently.
Do not store permissions as claims on an identity. While it may be fairly simple to add a claim to an identity, it can be quite hard to remove it. Keep in mind that the resource which consumes your claims today may want certain information, but the resources you add later may find the information completely redundant. For example, information such as family name or date of birth are suitable to configure as claims, but "has temporary access to website X" is not. In conclusion: Identify the minimum number of claims you need to be able to look up a greater amount of detail only where it is needed.
The recommended way to handle permissions is to grant them using policies, by writing requirements and requirement handlers which evaluate claims and resources. In ASP.NET Core the Authenticate attribute still exists but you are no longer expected to write your own implementation. Instead the recommended process is to create policies which consists of one or more requirements.
The following rules apply:
- A resource can have zero or more Authenticate attributes. All attributes must be valid before access is granted.
- A policy can consist of one or more requirements. All requirements must be met for the policy to be fulfilled.
- A requirement can be evaluated by one or more requirement handlers. All handlers must consider the requirement fulfilled for the whole requirement to be fulfilled.
Keep in mind that if you register multiple handlers for a requirement, all handlers will be called. For this reason, you should only mark requirements as 'failed' if something is seriously wrong, for example if one of the handlers notices that a critical database is offline. If a handler simply cannot confirm a requirement, it should not provide a response at all. In other words, the absence of a yes means no.
For more information, see https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies#security-authorization-policies-based.
Client secrets
In Web APIs, a client secret is a secret known only to the application and the authorization server.
We recommend that you establish a secure way to store sensitive information. For example, you can limit security vulnerabilities by avoiding hardcoding of sensitive information into an application, and instead only make it available during runtime and when specifically requested. This approach also makes it easier to securely use the same credentials on different machines, as the different APIs and clients can fetch them from a central storage.
There are many different options available for storing credentials, for example Azure Key Vault (see https://docs.microsoft.com/sv-se/aspnet/core/security/key-vault-configuration) or Amazon Key Management. In iCore Integration Suite, you have the option to use protected attribute values on Partner, Setting, and Node attributes.
HTTP or HTTPS?
We recommend that HTTPS is always used in environments where the Web API is publicly published (i.e. it can be accessed from outside the firewall).
HTTPS requires that your Web API uses a certificate issued by a trusted certificate authority, for example Let's Encrypt (https://letsencrypt.org/). Let's Encrypt is a non-profit organization supported by well-known companies such as Facebook, Cisco, Google and others. The certificates are compatible with most current browsers (Chrome, Edge, Firefox >=2.0 etc.). Let's Encrypt is a good place to start if you do not want to immediately commit to a paid certificate.
IIS or Kestrel?
When a Web Api is deployed to iCore runtime, it is hosted in its own process on a Kestrel server. While Kestrel is the default cross-platform HTTP server for ASP.NET Core, we currently recommend that you avoid using Kestrel by itself if the Web API is to be exposed outside the local host. In this scenario, always use a more mature server like IIS as a reverse proxy to handle requests from the Internet before they are forwarded to the Kestrel site.
For more information, see https://docs.microsoft.com/sv-se/aspnet/core/fundamentals/servers/kestrel#when-to-use-kestrel-with-a-reverse-proxy.