Light Oauth2 Tutorial

This document will give you step-by-step guidelines on how to use light-oauth2. There are two types of services in light-oauth2. The first category contains code/authorize, token, key, and provider that will be accessed from clients during the runtime. The provider service is not directly accessed from the clients, but it connects federated light-oauth2 services to form a mesh of the OAuth 2.0 providers. Othe services like the user, client, and service are connected from the light-portal to make configuration changes to the light-oauth2 services. These services are protected by OAuth 2.0 authentication and authorization. By default, the security is partially disabled on these services out of the box so that users can easily test these services to learn how to use them. In later sections, there are steps to enable all security with config files.

How to generate long lived tokens

Normally, your clients or testing tools should integrate with OAuth authorization server to get tokens during runtime; however, for manual testing, it is very inconvenient to get an access token every 10 minutes. To make the testers’ jobs easier, you can generate a long-lived token for dev testing from a tool in the light-4j framework. The light-oauth2 contains two testing key pairs for testing only. Both private keys and public key certificates can be found in security module of light-4j or light-docker oauth2-token config. Read More »

Start Services

Note: the following steps use MySQL database as an example. MariaDB, SQL Server and Postgres should be the same by choosing docker-compose-oauth2-mariadb.yml, docker-compose-oauth2-sqlserver.yml or docker-compose-oauth2-postgres.yml when starting docker-compose. The current release supports four built-in databases: MySQL, MariaDB, SQLServer and Postgres. If you want to use other databases, you need include the JDBC driver into the classpath and create a datasource config in service.yml file. In production mode, all services will have docker images downloaded from hub. Read More »

Authorization Code

This is part of the authorization flow that takes the user’s credentials and redirect back authorization code to the webserver through a user agent (browser or mobile phone). The web server will use the authorization code along with client_id and client_secret to get the access token and refresh token. In this tutorial, we are using the curl command to access the service for demo purposes. In reality, this should be done by a login view single page application. Read More »

Token Endpoint

This service has only one endpoint to get access tokens. It supports authorization code grant type, and client credentials grant type. Also, it supports some customized authorization types required by our customers. These customized flows will only work on certain clients, which have to be set up as trusted clients. Authorization Grant with authorization code redirected in the previous step. Please replace the code with the newly retrieved one as it is only valid for 10 minutes. Read More »

Service Registration

OAuth2 is used to protect services, and each service must register itself with endpoints and scopes to have fine-grained access control. The OAuth 2.0 specification only mentioned client registration with scopes along with it. For a simple application or single monolithic web service, it is OK. However, if we have hundreds of services with thousands of scopes, the scope management will be a nightmare. It is easier for consumers and providers to use endpoints in discussion than meaningless scopes. Read More »

Update MySQL Docker

The deployed light-oauth2 services on the test cloud and prod cloud are using the MySQL database. To support multi-tenancy, we need to add a host column to the client and service table. The database scripts are updated in all repositories. And we need to update the live database without recreating it on test4 and prod4 server. The following are steps performed on the test4 server. ssh test4 docker ps docker exec -it [container-id] mysql -u [mysqluser] -p oauth2 ALTER TABLE client ADD host VARCHAR(32) NOT NULL DEFAULT 'lightapi. Read More »

Light Portal Authenticator

One of the essential features of light-oauth2 is its extensibility. When a bank is using an OAuth 2.0 server to authenticate users, it needs to integrate with several user management databases or services. For example, employees will be authenticated with Active Directory via LDAP or SPENGO single sign-on. For retail customers, they will be authenticated with a customer profile database in a mainframe. To make the integration with back end authenticators easier, we have provided the authhub module in light-oauth2. Read More »

React Light-oauth2 Login View

For redirect based OAuth 2.0 authorization code flow, a user agent like a web browser or mobile phone needs to be involved. In the light-oauth2 repository, we have provided a login-view single-page application based on React. In this section, we are going to walk through the application to show users the implementation details. This single-page application should be hosted in the light-router instance as a virtual host along with a customer’s application. Read More »

Test Cloud OAuth 2.0 Provider Deployment

In the previous form authentication local tutorial, we have deployed the light-oauth2 services on the local Ubuntu desktop along with light-router to serve the lightapi.net and signin.lighapi.net single-page applications. In this tutorial, we are going to deploy the same configuration to the test cloud so that our developers can utilize the instance for development and testing wherever they can access the Internet. They allow them to work on both frontend single page applications and the backend services locally without deploy and maintain an instance of light-oauth2 locally. Read More »

Local Form Authentication

Before we dive into the details, here is a video that walks through the demo and configurations. Introduction Recently, we have completed the form authentication in the light-oauth2 authorization code service. Now, we support Basic Authentication, Form Authentication, and SPENGO SSO. While working on the form authentication, I have to set up my local environment in a production-like configuration before deploying it to the cloud to provide services to our users. Read More »

OpenShift Deployment

The configuration files and deployment script can be found at light-config-test repo. light-config-test/light-oauth2/openshift For default Openshift environment, the default user doesn’t have permission to access Kubernetes API. If you see the following error, please follow the steps to resolve it. SEVERE: [10.101.111.226]:5701 [uat] [3.9.2] Failure executing: GET at: https://kubernetes.default.svc/api/v1/namespaces/uat1/endpoints?labelSelector=light-oauth2-cluster01%3Dtrue . Message: Forbidden!Configured service account doesn't have access. Service account may have been revoked. User "system:serviceaccount:uat1:default" cannot list endpoints in the namespace "uat1": User "system:serviceaccount:uat1:default" cannot list endpoints in project "uat1". Read More »

Kerberos/SPNEGO

Light-oauth2 supports Kerberos/SPNEGO with the built-in default authentication/authorization authenticator. This allows the user only sign-on the desktop once and call OAuth2 authorization code flow with Single Sign On on the browser. For the light-oauth2 server and AD/KDC configuration, please refer to default auth. Once you have light-oauth2 and AD/KDC servers ready, you can perform an integration test on you local Mac Book Pro with SSO to confirm that all configurations are working. Read More »

Kubernetes Cluster

In the start services section, we have introduced docker-comopse commands to start the light-oauth2 services with different databases. It is good for a dev and test environment, but not production. For production deployment, we are going to use Kubernetes or other Kubernetes implementations like Openshift. In this tutorial, we are going to walk through the deployment on a three nodes Kubernetes cluster. Introduction Here is the Kubernetes cluster information. We are going to run the command line from sandbox which is the master node of the cluster. Read More »

Custom Grant Types

Light-OAuth2 supports custom grant types and it is very easy to implement with a special client type called trusted. The trusted client type is an add-on based on the standard public or confidential client types provided in OAuth 2.0 specification. The key condition to setup a trusted client is that the client and OAuth 2.0 provider are deployed in the same organization so that OAuth 2.0 provider can trust the client on certain custom grant types. Read More »

Key Distribution

Light-Java and Light-OAuth2 support distributed security verification and this requires the JWT public key certificate to be distributed to all services. By default, all services built on top of Light-Java will include a set of certificates. But how do you distribute new certificates to thousands of running services if certificates are renewed? There is no way we can copy certificates to all the running containers as they are dynamic and new containers can be started anytime by container orchestration tool. Read More »

User Management

The OAuth2 services can be integrated with an existing Active Directory, LDAP or customer database for authentication. If there is no existing authentication service, you can register users into database as default implementation. For the light-portal we are using our own database for all users. In this tutorial, we are using curl commmand to access the API and endpoints. In reality these endpoints will only be consumed by light-portal UI. Read More »

Client Registration

Every client that accesses service(s) must register itself in order to get the access token during runtime from OAuth 2.0 provider. If it happens that the client is an service and some other client is calling it. This particular API will need to register itself twice. One as a client and one as a service. The client service provides an endpoint to create a new client, update an existing client and delete a client. Read More »

Provider Registration

The service to support federated OAuth 2.0 providers. For example, external OAuth 2.0 provider for external clients and internal OAuth 2.0 provider for internal clients. The Internal AS needs to have the public key certificate from External AS in order to allow all resource server to verify the tokens signed by both servers. Provider workflow Provider workflow diagram Provider workflow steps Pre-steps, Light-oauth server B and light-oauth server C register as light-oauth security provider on light-Oauth server A. Read More »