Theory of operation

Host: This is the DNS name where a service can be accessed. This DNS name can be a Kubernetes service, or a load balancer, or even a host FQDN.
IPs: Is a list of IPs where the service can be accessed. If a Host is provided above, there is no need to provide a list of IPs. The Aporeto system will automatically create certificates that match either the host or list of IPs. If you want to be able to access your services over IP addresses you must provide the list here so that proper certificates can be created.
ExposedPort: This is the port that a load balancer is listening for the service. In Kubernetes this would be the node port or load balancer port of the service. In ECS, this would be the port that the ALB/ELB is listening on. In Docker deployments this could be the host port where a container port is forwarded to. So, assuming that the service is exposed as http://www.example.com, your other containers that are accessing the service can simply issue an HTTP request to the same URI. All TLS functions are transparently handled.
Port: This is the port that the actual application is listening for the corresponding service. In container deployments this is the internal port of the container. In Linux service deployments this is simply the port of the process.
PublicApplicationPort: In addition to the above ports the configuration can include a port where external users can access the application. Assume for example that you have an application http://www.example.com listening on port 80. The moment you deploy the enforcer the connection is upgraded to HTTPS and you would now have to access the application as https://www.example.com:80. This is both unnatural and not user friendly. You can define a public application port as 443 and now you can access the application as https://www.example.com. The enforcer will implement all the corresponding port translations. Note that enforcers can be also configured to accept HTTP-only traffic in the PublicApplicationPort. This is needed in some cases where you need to expose public APIs without encryption, as for example in the case of load balancers doing health checks on the application.

Services and certificates for user authentication

Server certificate
: the certificate that the server will advertise to clients. There can be multiple certificates that a server advertises depending on the type of client. For example, when process protected by Aporeto are communicating the certificate that is advertised by the server is the one created by Aporeto. When a user is accessing the application over the PublicApplicationPort the certificate that is advertised can be either the Aporeto issued certificate or a server certificate. Assume for example that you create a service as https://www.example.com and get a certificate from a public certificate authority. In this case, you would like clients to receive this certificate when they try to access your service. The public server certificates are provided through the TLSCertificate and TLSCertificateKey parameters. The TLSType parameter allows you to define the type of certificate that can be advertised:
Aporeto: the server will advertise the Aporeto issued certificate.
External: the server will advertise an external certificate that is provided in the TLSCertificate and TLSCertificateKey parameters.
LetsEncrypt: will guide enforcers to automatically derive public certificates from Let’s Encrypt. This will work if a process is directly exposed to the internet and there is no Load Balancer that is actually terminating the user requests. (This will be implemented in the next release).
None: This is indicates no TLS at all on the Public Application Port. This can be used for Load Balancer health checks. It is not recommended to allow user access over HTTP. Even in that case though, only the public APIs will be accessible. If an API requires authorization it cannot be accessible over an HTTP service.
Client certificate
: is the certificate that a client can present to the server to authenticate itself. Client certificates can be issued by the Aporeto system or by any third party certificate authority. If the client certificate is issued by a CA other than Aporeto, then you need to configure in the system the CA certificate chain that can validate these certificates.
Client Root CA
is the CA that issues the client certificates. If it is Aporeto it is auto-discovered. If it is an external CA, the user must provide the corresponding CA certificate chain. The server will use this chain to validate and authenticate the client certificate. The chain is provided through the MTLSCertificateAuthority parameter.

IP addresses of the process as it can be accessed by external systems. These is essentially the list of IPs from the corresponding attribute plus the list of local IPs discovered by the enforcers.
DNS names as they are defined in a service definition.
SPIFFE URIs based on the namespace and the service.

SAN IPs: 10.1.1.2, 10.1.1.3, 127.0.0.1, and IPs of the local host.
SAN DNS: myservice.com
SAN URI: spiffe://aporeto/foo/bar

Supported client authorization methods

MTLS
: By presenting a certificate that is signed by a trusted CA, the server can validate the client. This is also referred as mutual TLS. Note that the MTLSCertificateAuthority must be defined if the client certificates are not issued by Aporeto.
JWT
: The client can also present a JWT that is signed by a public key that the enforcer can trust. The JWT must be presented in the Authorization header as Authorization: Bearer $JWT. In this case, the enforcer must know the signing certificate of the JWT, since we assume that these are PKI JWTs. The JWT signing certificate can be configured using the JWTSigningCert attribute.
OpenID Connect (OIDC)
: This is also a JWT-based client authentication, but in this case the JWT is dynamically issued and validated through an identity provider. The enforcer will force clients to get a JWT from the identity provider and will verify the validity of the token by communicating directly with the identity provider.
IP address
: There is a less secure method for identifying a client through its IP address. This mode is not recommended and it is only supported for some very specific use cases where you want to limit access to APIs based on IP addresses. In general we recommend against using IP addressers as a client identifier since they can be easily spoofed.

Processing unit to processing unit authorization

HTTPResourceSpec is needed in all API service definitions and it defines the REST API that a service exposes. The specification details a list of URIs and associated permissions for each URI. An example specification is below. It defines three endpoints /admin/*, /public/* and /internal/* and it associates different scopes with these endpoints. Note that the /public/* endpoint is given public access and thus any client will be allowed to access this API. The specification allows wild-chars. * indicates any string expansion. ? indicates that one level of the URI can be ignored. For example an endpoint /a/?/c will match /a/b/c/ and /a/d/c but it will not match /a/b/d/c.

name: apispec
associatedTags:
- spec:api=demo
description: My Demo API Service
endpoints:
- URI: /admin/*
  methods:
  - GET
  public: false
  scopes:
  - scope:admin
- URI: /internal/*
  methods:
  - GET
  public: false
  scopes:
  - data:organization=example
- URI: /public/*
  methods:
  - GET
  public: true
  scopes: []

Service: For a simple processing unit to processing unit communication the service definition needs minimal configuration as below. You need to define the host, IPs, port, and exposedPort. In addition you need to define a selector for the exposedAPIs of the service and a selector for the processing units that are implementing the service.

name: Example Service
description: "Simple service definition"
hosts:
- myservice.example.com
IPs: []
exposedAPIs:
- - spec:api=demo
exposedPort: 8000
port: 80
selectors:
- - app=service
type: HTTP

TokenScopePolicies: In order for client processing units to be able to access the restricted APIs you must also define a token scope policy that associates scopes with specific processing units. In other words you have to define for all the client processing units what types of scopes are they allowed to access. This is the same type of operation as assigning scopes to users in an identity provider. An example token scope policy is below and it defines that all processing units in a given namespace will have access to the scope app=internal.

name: Example Scopes
assignedScopes:
- app=internal
subject:
- - $namespace=/apomux/services

Network policy: Note that you still need to define a network policy in order to allow processing unit to processing unit communication at layer 3. In most cases this already defined by your organization. An example network policy below allows access between any two processing units in the same namespace.

- name: fallback namespace
action: Allow
encryptionEnabled: false
object:
- - $namespace=/apomux/services
subject:
- - $namespace=/apomux/services

Processing unit to processing unit authorization with layer 7 load balancers

name: Example Service
description: "Simple service definition"
hosts:
- myservice.example.com
IPs: []
exposedAPIs:
- - spec:api=demo
exposedPort: 8000
port: 80
selectors:
- - app=service
type: HTTP
trustedCertificateAuthorities: |-
  -----BEGIN CERTIFICATE-----
  MIIBqTCCAVCgAwIBAgIRAOyNIvUnmNvn1edRSdl1gsUwCgYIKoZIzj0EAwIwKjEZ
  .....
  -----END CERTIFICATE-----