LIGHT

  • News
  • Docs
  • Community
  • Reddit
  • GitHub
Star

Token Service

This is a post endpoint to get JSON web tokens. Currently, it supports three different grant types: authorization_code, client_credentials and password. It issues subject token to identify the original human caller, access token for the client and refresh token if needed. It also supports token exchange and token chaining for maximum security.

In this implementation, we only support JSON Web Token as Simple Web Token is not scaling very well. In a microservices architecture, the tokens must be verified at each service without calling back to the authorization server.

Authorization Code Grant Type

Request

The client makes a request to the token endpoint by sending the following parameters using the “application/x-www-form-urlencoded” format.

  • grant_type

REQUIRED. Value MUST be set to “authorization_code”.

  • code

REQUIRED. The authorization code received from the authorization server.

  • redirect_uri

REQUIRED, if the “redirect_uri” parameter was included in the authorization request, and their values MUST be identical.

  • client_id:client_secret

REQUIRED, as BASIC authorization header with encoded client_id:client_secret to authenticate with the authorization server.

  • code_verifier

OPTIONAL, PKCE code verifier that used by Mobile Native App

Response

If the access token request is valid and authorized, the authorization server issues an access token and a refresh token. If the request client authentication failed or is invalid, the authorization server returns an error response.

Client Credentials Grant Type

The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server.

Request

The client makes a request to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format with a character encoding of UTF-8 in the HTTP request entity-body:

  • grant_type

REQUIRED. Value MUST be set to “client_credentials”.

  • scope

OPTIONAL. The scope of the access request.

  • client_id:client_secret

REQUIRED, as BASIC authorization header with encoded client_id:client_secret to authenticate with the authorization server.

Response

If the access token request is valid and authorized, the authorization server issues an access token. A refresh token SHOULD NOT be included. If the request failed client authentication or is invalid, the authorization server returns an error response.

Resource Owner Password Credentials Grant Type

The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application. The authorization server should take special care when enabling this grant type and only allow it when other flows are not viable. In this implementation, only clients registered as trusted can use password grant type.

This grant type is suitable for clients capable of obtaining the resource owner’s credentials (username and password, typically using an interactive form). It is also used to migrate existing clients using direct authentication schemes such as HTTP Basic or Digest authentication to OAuth by converting the stored credentials to an access token.

Request

The client makes a request to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format with a character encoding of UTF-8 in the HTTP request entity-body:

  • grant_type

REQUIRED. Value MUST be set to “password”.

  • username

REQUIRED. The resource owner username.

  • password

REQUIRED. The resource owner password.

  • scope

OPTIONAL. The scope of the access request.

  • client_id:client_secret

REQUIRED, as BASIC authorization header with encoded client_id:client_secret to authenticate with the authorization server.

Response

If the access token request is valid and authorized, the authorization server issues an access token and a refresh token. If the request failed client authentication or is invalid, the authorization server returns an error response.

Refresh Token Grant Type

If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format with a character encoding of UTF-8 in the HTTP request entity-body.

  • grant_type

REQUIRED. Value MUST be set to “refresh_token”.

  • refresh_token

REQUIRED. The refresh token issued to the client.

  • scope

OPTIONAL. The scope of the access request. The requested scope MUST NOT include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner.

Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the client to which it was issued. If the client type is confidential or the client was issued client credentials (or assigned other authentication requirements), the client MUST authenticate with the authorization server.

The authorization server MUST:

  • require client authentication for confidential clients or for any client that was issued client credentials (or with other authentication requirements),

  • authenticate the client if client authentication is included and ensure that the refresh token was issued to the authenticated client, and

  • validate the refresh token.

If valid and authorized, the authorization server issues an access token. If the request failed verification or is invalid, the authorization server returns an error response.

The authorization server issues a new refresh token and the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server revokes the old refresh token after issuing a new refresh token to the client. The new refresh token scope MUST be identical to that of the refresh token included by the client in the request.

Implementation

There is only one post endpoint for this service and the default port is 6882.

Here is the specification.

swagger: '2.0'

info:
  version: "1.0.0"
  title: OAuth2 Service Token Service
  description: OAuth2 Service that issues access tokens. 
  contact:
    email: [email protected]
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: oauth2.networknt.com
schemes:
  - http
  - https

consumes:
  - application/x-www-form-urlencoded   
produces:
  - application/json

paths:
  /oauth2/token:
    post:
      description: JSON object that contains access token
      operationId: postToken
      parameters:
      - name: authorization
        description: "encoded client_id and client_secret pair"
        in: header
        type: string
        required: true      
      - name: grant_type
        type: string
        enum: 
        - authorization_code
        - client_credentials
        - password
        - refresh_token
        required: true
        in: formData
      - name: code
        description: "used in authorization_code to specify the code" 
        type: string
        in: formData
      - name: username
        description: "mandatory in password grant type"
        type: string
        in: formData
      - name: password
        description: "mandatory in password grant type"
        type: string
        in: formData
      - name: scope
        description: "used by all flows to specify scope in the access token"
        type: string
        in: formData
      - name: redirect_uri
        description: "used in authorization code if code endpoint with rediret_uri"
        type: string
        in: formData
      - name: refresh_token
        description: "refresh token used to get another access token"
        type: string
        in: formData
      responses:
        200:
          description: "Successful Operation"

/oauth2/token

When a post request is received, the following validations and processes will be performed.

  • The handler expects a x-www-form-urlencoded form and if it doesn’t exist, the following error will be returned.
  "ERR12000": {
    "statusCode": 400,
    "code": "ERR12000",
    "message": "UNABLE_TO_PARSE_FORM_DATA",
    "description": "Unable to parse x-www-form-urlencoded form data."
  }
  • The parameter grant type should only allowed client_credentials and authorization_code. If other grant_type is passed in, the following error will be returned.
  "ERR12001": {
    "statusCode": 400,
    "code": "ERR12001",
    "message": "UNSUPPORTED_GRANT_TYPE",
    "description": "Unsupported grant type %s. Only authorization_code and client_credentials are supported."
  }
  • When this endpoint is called, the client_id and client_secret must be base64 encoded and put into the Authorization header. If there is no Authorization header available in the request, the following error will be returned.
  "ERR11017": {
    "statusCode": 400,
    "code": "ERR11017",
    "message": "VALIDATOR_REQUEST_PARAMETER_HEADER_MISSING",
    "description": "Header parameter '%s' is required on path '%s' but not found in request."
  }
  • When validating client_id and client_secret, the first thing is to check the client_id in the client cache in memory. If client_id doesn’t exist, the following error will be returned.
  "ERR12014": {
    "statusCode": 404,
    "code": "ERR12014",
    "message": "CLIENT_NOT_FOUND",
    "description": "Client %s is not found."
  }
  • The encoded client_id:client_secret combination will be decoded and then the client secret will be checked with hashed and salted in memory client secret to make sure it is correct. If the client secret is not correct, the following error will be returned.
  "ERR12007": {
    "statusCode": 401,
    "code": "ERR12007",
    "message": "UNAUTHORIZED_CLIENT",
    "description": "Unauthorized client with wrong client secret."
  }
  • If the basic client_id:client_secret cannot be decoded and parsed correctly, the following error will be returned.
  "ERR12004": {
    "statusCode": 401,
    "code": "ERR12004",
    "message": "INVALID_BASIC_CREDENTIALS",
    "description": "Invalid Basic credentials %s."
  }
  • If there is no Basic authorization header passed in, i.e. a bearer token is passed in, the following error will be returned.
  "ERR12003": {
    "statusCode": 401,
    "code": "ERR12003",
    "message": "INVALID_AUTHORIZATION_HEADER",
    "description": "Invalid authorization header %s. Basic authentication with credentials is required."
  }

If all validation is passed, a JWT token will be generated and returned in a JSON object.

  • About Light
    • Overview
    • Testimonials
    • What is Light
    • Features
    • Principles
    • Benefits
    • Roadmap
    • Community
    • Articles
    • Videos
    • License
    • Why Light Platform
  • Getting Started
    • Get Started Overview
    • Environment
    • Light Codegen Tool
    • Light Rest 4j
    • Light Tram 4j
    • Light Graphql 4j
    • Light Hybrid 4j
    • Light Eventuate 4j
    • Light Oauth2
    • Light Portal Service
    • Light Proxy Server
    • Light Router Server
    • Light Config Server
    • Light Saga 4j
    • Light Session 4j
    • Webserver
    • Websocket
    • Spring Boot Servlet
  • Architecture
    • Architecture Overview
    • API Category
    • API Gateway
    • Architecture Patterns
    • CQRS
    • Eco System
    • Event Sourcing
    • Fail Fast vs Fail Slow
    • Integration Patterns
    • JavaEE declining
    • Key Distribution
    • Microservices Architecture
    • Microservices Monitoring
    • Microservices Security
    • Microservices Traceability
    • Modular Monolith
    • Platform Ecosystem
    • Plugin Architecture
    • Scalability and Performance
    • Serverless
    • Service Collaboration
    • Service Mesh
    • SOA
    • Spring is bloated
    • Stages of API Adoption
    • Transaction Management
    • Microservices Cross-cutting Concerns Options
    • Service Mesh Plus
    • Service Discovery
  • Design
    • Design Overview
    • Design First vs Code First
    • Desgin Pattern
    • Service Evolution
    • Consumer Contract and Consumer Driven Contract
    • Handling Partial Failure
    • Idempotency
    • Server Life Cycle
    • Environment Segregation
    • Database
    • Decomposition Patterns
    • Http2
    • Test Driven
    • Multi-Tenancy
    • Why check token expiration
    • WebServices to Microservices
  • Cross-Cutting Concerns
    • Concerns Overview
  • API Styles
    • Light-4j for absolute performance
    • Style Overview
    • Distributed session on IMDG
    • Hybrid Serverless Modularized Monolithic
    • Kafka - Event Sourcing and CQRS
    • REST - Representational state transfer
    • Web Server with Light
    • Websocket with Light
    • Spring Boot Integration
    • Single Page Application
    • GraphQL - A query language for your API
    • Light IBM MQ
    • Light AWS Lambda
    • Chaos Monkey
  • Infrastructure Services
    • Service Overview
    • Light Proxy
    • Light Mesh
    • Light Router
    • Light Portal
    • Messaging Infrastructure
    • Centralized Logging
    • COVID-19
    • Light OAuth2
    • Metrics and Alerts
    • Config Server
    • Tokenization
    • Light Controller
  • Tool Chain
    • Tool Chain Overview
  • Utility Library
  • Service Consumer
    • Service Consumer
  • Development
    • Development Overview
  • Deployment
    • Deployment Overview
    • Frontend Backend
    • Linux Service
    • Windows Service
    • Install Eventuate on Windows
    • Secure API
    • Client vs light-router
    • Memory Limit
    • Deploy to Kubernetes
  • Benchmark
    • Benchmark Overview
  • Tutorial
    • Tutorial Overview
  • Troubleshooting
    • Troubleshoot
  • FAQ
    • FAQ Overview
  • Milestones
  • Contribute
    • Contribute to Light
    • Development
    • Documentation
    • Example
    • Tutorial
“Token Service” was last updated: April 5, 2021: Issue246 (#256) (50b1c10)
Improve this page
  • News
  • Docs
  • Community
  • Reddit
  • GitHub
  • About Light
  • Getting Started
  • Architecture
  • Design
  • Cross-Cutting Concerns
  • API Styles
  • Infrastructure Services
  • Tool Chain
  • Utility Library
  • Service Consumer
  • Development
  • Deployment
  • Benchmark
  • Tutorial
  • Troubleshooting
  • FAQ
  • Milestones
  • Contribute