Security Tutorial

The Light platform is following security first design as most of our customers are big financial companies and they need to ensure confidentiality, availability, and integrity first then scale the system to lower the production cost and development cost.

When the platform was designed, we focused a lot of efforts on the security details and made a lot of default configuration so that our customers won’t need to do extra things to bring up a system securely. Once they feel comfortable, they can start to configure their services based on their business requirement or non-functional requirement.

In this section, we have several tutorials related to security configurations and implementations.

Customized Decryptor

Some organizations that don’t want to use the default implementation can use their customized encryptor and decryptor. To demo how to use a customized decryptor, we have provided a test implementation DummyDecryptor. Because it doesn’t do any encryption but just adds the prefix CRYPT in front of the clear text, please don’t use it in any official environment. If you implement your decryptor in a common module, you can release it internally to the organization’s Artifactory and include it in your service dependency. Read More »

Okta Oauth 2.0 Provider

We have too many configuration examples of leveraging the light-oauth2 or the kafka-oauth for security. One of our customers is using Okta cloud for hundreds of services, and we have learned a lot of configuration variations on different light-4j products. This tutorial will show you how to use the Okta cloud OAuth 2.0 provider for security. Single Okta JWK This is the setup for a light-4j service or the http-sidecar to verify the incoming JWT token by downloading the JWK from the same OAuth server instance on the cloud. Read More »

Light Router

When deploying the light-portal to the cloud, the light-config-server won’t be accessed directly by the services deployed to the public cloud. Services will access the config server through the light-router instance which is the entry point for all the backend platform services. All services will access the config server with bootstrap.truststore to load the configuration from the config-server during the startup. It requires that the light-config-server private key will be imported to the light-router server. Read More »

Fine Grained Authorization

Light-portal To run the demo application, you need to start the light-portal locally by following the README.md in https://github.com/lightapi/portal-config-loc Upload Rule Once the portal is up and running, you need to add the rule from the publish/YAML Rule menu. account-cc-group-role-auth: ruleId: account-cc-group-role-auth host: lightapi.net description: Role-based authorization rule for account service and allow cc token and transform group to role. conditions: - conditionId: allow-cc variableName: auditInfo propertyPath: subject_claims.ClaimsMap.user_id operatorCode: NIL joinCode: OR index: 1 - conditionId: manager variableName: auditInfo propertyPath: subject_claims. Read More »

Pfx Certificate

When we require a new CA certificate for the API platform, the security team will sometimes provide a pfx file that includes CA keys and certs. A PFX file, also known as PKCS #12, is a single, password-protected certificate archive that contains the entire certificate chain plus the matching private key. Essentially it is everything that any server will need to import a certificate and private key from a single file. Read More »

Self Signed Jwt Key

The light-oauth2 server needs a private key to sign the JWT token and all servers need a public key certificate to verify the token. The following includes the steps to create both primary and secondary key pairs. keystore keytool -genkeypair -alias primary -keyalg RSA -keysize 2048 -keystore primary.jks -storepass password -keypass password -validity 9999 keytool -genkeypair -alias secondary -keyalg RSA -keysize 2048 -keystore secondary.jks -storepass password -keypass password -validity 9999 Please note that light-oauth2 token service has a config file called jwt. Read More »

Self Signed Certificate

In other tutorials, we have introduced Java keytool and other tools for certificate generation and manipulation. A lot of users still cannot grasp the complicated procedure and ask if we can provide a tutorial to list all the steps without too many options. The following is a list of steps for us to create a production API. If you have a list of APIs group together, they can share the same server. Read More »

Environment Variable for Config Value

When working with a light-4j application, there might be a lot of configuration files that need to be checked into the Git repository. For an open-source project, chances are you need to check the source code and configuration files to the public repository on the GitHub. If you have some sensitive information in one or more config files, you need to be really careful not to check the information to the public repository. Read More »

Config Server Certificate

For light-4j services, there are four options to get the configuration values for each handler or cross-cutting concern. externalized configuration files with all the final values. externalized configuration files with values.yml to inject into the config file templates. externalized configuration files with system properties to inject into the config file templates. config files/values served by light-config-server instance. When option four is chosen, we need to ensure that the service can connect to the light-config-server instance(s) with a secure channel. Read More »

Running ligh-4j service on port 443

The default light-codegen generated project will have HTTPS and HTTP2 enabled on port 8443. Typically, HTTPS servers run on port 443. But this port is considered privileged on Unix/Linux systems, and the process using them must be owned by root. Unless your service is running in a dedicated locked down VM, we don’t recommend running as root - it should be run as its own user. For most of our customers, they have F5 facing the Internet and it can route the traffic to the IP and port combination. Read More »

Basic Terminologies and Formats of Certs and Keys

There’s some confusion for the light-4j users about how to control which certificates are used for one-way TLS and two-way TLS. In this section, we will clear up the general terminology and formats about the certificate and private key to make it easier to understand other tutorials. Basic Terminology CERTIFICATE OR CERT The public half of a public/private key pair, though it’s not generally referred to as a key. Read More »

Convert CA-signed certificate to server.keystore

A lot of our users are using Let’s Encrypt to get free certificates to install on their public-facing light-4j instances. i.e., light-router as an external access point or BFF for single page applications. In the let’s encrypt tutorial, we have shown you how to get the certificate and key with certbot. In this tutorial, we are going to walk through the step to convert the full chain certificate and the key to a server. Read More »

Free Let's Encrypt Certificate

If you are using light-router as a public facing access point on a static IP or expose your services to the public, it makes perfect sense to use a CA-signed certificate instead of self-signed. If you don’t want to foot the cost of the certificate, Let’s Encrypt provides free certificates which can be recognized by almost all browsers. The following is the process to get a certificate on my public facing VMs. Read More »

Install Certificate

For all light-4j instances, it is highly recommended to use HTTPS/HTTP2 instead of HTTP unless your infrastructure doesn’t support HTTPS. That is why HTTPS/2 are enabled right out of the light-codegen with a set of built-in keystores and truststores for development. Before moving to an official testing environment, you need to replace the self-signed certificates with your self-signed or commercial certificates. Please be aware that client.yml, client.keystore, and client.truststore will only be generated when you have the following config attribute in the config. Read More »

Adding server certificate to client.truststore

In the keystore and truststore tutorial, we have discussed the difference of between keystore and truststore and in which case, you need to update the following files to enable one-way TLS or two-way TLS. client.keystore - client private key. client.truststore - public key certificates the client can trust. server.keystore - server private key. server.truststore - public key certificates the server can trust. Also, there are another two files related to the certificates in oauth config folder. Read More »

Keystore Truststore

The main difference between trustStore and keyStore is that trustStore (as name suggest) is used to store certificates from trusted Certificate authorities(CA) which are used to verify certificate presented by Server in SSL Connection, while keyStore is used to store private keys and identity certificates which programs should present to other parties (Server or client) to verify its identity. That was a one-liner difference between trustStore and keyStore in Java, but no doubt these two terms are quite confusing not just for anyone who is configuring SSL connection in Java for the first time, but also many intermediate and senior level programmers. Read More »

Encrypt and Decrypt

In this tutorial, we are going to show you how to use the light-encryptor command line utility to encrypt a sensitive property value with a picked master key and to decrypt an encrypted value in a config file within a project with a master key environment variable on the server. Decryptor Interface The following is the interface that is used for decryption. This class is in the decryptor module of light-4j. Read More »

Bootstrap From Key Service

When you are planning to turn it on in security.yml, you must ensure that you have light-oauth2 microservices up and running. Also, you need to ensure that your client.yml is configured to connect to the key endpoint correctly. Once it is set up correctly, your service instance will automatically goes to light-oauth2 key service to get public key certificate to verify JWT token according to the kid in the header. For more details please refer to security cross-cutting concern. Read More »