Ports, Middleware & Security

A complete example

# services/orders/.genexy/component.yaml
type: go-gnx-di # or axum, spring-boot, aspnet-core, nodejs, nestjs
 
exposes:
  - name: public # key of the port in the configuration
    protocol: http
    port: 8080
    contracts:
      - $ref: api/orders.openapi.yaml
    security: auth # the security module that checks tokens on this port
    middleware:
      cors: { allowedOrigins: ['https://shop.example.com'], allowCredentials: true, maxAge: 10m }
      rateLimit: { limit: 100, window: 1m, key: ip }
      maxRequestBytes: 1MiB
      requestTimeout: 30s
      securityHeaders: { hsts: true, contentSecurityPolicy: "default-src 'none'" }
      compression: true
      accessLog: true
    validation:
      unknownProperties: reject
  - name: admin
    port: 8081
    contracts:
      - $ref: api/admin.openapi.yaml
    security: none # reachable only inside the cluster, no tokens
 
modules:
  - name: auth
    type: security
    provider: oidc
    issuer: https://sso.example.com/realms/shop
    audience: orders-api

Ports

Every entry of exposes is a port with its own web server. A port serves the operations of its contracts and nothing else: an admin operation never answers on the public port. The same contract can be served on several ports, and a port can serve several contracts. If two contracts on one port use the same path and method, generation stops with an error.

Tests start every port on a free number and ask the application for its address. The generator pages show how in each language.

Middleware

The values in middleware are the defaults of the port. The generator writes them into the generated configuration file, so you can still change them per environment without regenerating: in your own configuration file or with environment variables (see Configuration). A value the generator does not understand stops the generation with the reason. A wrong value in the configuration stops the application at startup.

Every request also gets an X-Request-ID: the one the caller sent, or a new one. It is returned in the response and written into the logs; all generators but Spring Boot also put it into the problem details (requestId), and the generated REST clients forward it.

/healthz answers 204 on every port whose contract does not define it (all generators but Spring Boot), and is never rate limited or authenticated.

Validation

The generated code validates every request against the contract before your code runs, so the service methods receive only valid input. The validation covers types, required properties and null, formats (date, date-time, uuid, email, uri…), enum, const, string lengths, pattern, number ranges, array sizes, nested objects, array items and map values. All violations of a request are returned in one 400 response:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request",
  "instance": "/api/v1/orders",
  "requestId": "4f1c…",
  "errors": [
    { "field": "items[0].quantity", "message": "must be at least 1" },
    { "field": "bogus", "message": "is not a known property" }
  ]
}

coerceParameters, responses, errorFormat, maxErrors and formats are planned. Today they produce a warning.

Authentication (JWT / OIDC)

A module of type security verifies the bearer tokens of the ports that use it. The contract decides what each operation needs. You do not write any security code, and no generator adds a security framework. The tokens are verified with the cryptography of the language (Go and Java standard library, System.Security.Cryptography, ring in Rust, node:crypto), so the behaviour is the same everywhere.

The security module

modules:
  # Keycloak or another OpenID Connect provider: the keys come from its discovery document
  - name: auth
    type: security
    provider: oidc
    issuer: https://sso.example.com/realms/shop
    audience: orders-api
 
  # A JWKS URL without discovery
  - name: partners
    type: security
    provider: jwt
    issuer: https://partners.example.com
    jwksUrl: https://partners.example.com/.well-known/jwks.json
 
  # A shared secret (HS256); keep the value out of the repository
  - name: internal
    type: security
    provider: jwt
    secret: ${INTERNAL_JWT_SECRET}

A token is accepted when its signature is valid and its exp has not passed. exp is required. If set, nbf, iss and aud must also match. A module with keys accepts only signed algorithms with keys, and a module with a secret accepts only HS algorithms. A token with alg: none or with an algorithm of the other kind is refused. The keys are cached for an hour. An unknown key id reloads them at most every 30 seconds (key rotation). When the provider cannot be reached, the keys already loaded keep working.

exposes[].security picks the module of a port. Without it, a component with one security module uses that module on every port. With several modules every port must name one, or none.

What an operation requires

The contract describes it, the generated code enforces it:

security: # default of every operation of the contract
  - bearer: []
paths:
  /orders:
    get:
      security:
        - keycloak: [orders:read] # scopes the token must have
    post:
      security: # alternatives: one of them is enough
        - keycloak: [orders:write]
        - keycloak: [orders:admin]
  /orders/{id}:
    delete:
      x-genexy-roles: [admin] # roles the caller must have (all of them)
  /catalog:
    get:
      security: [] # public: no token needed
components:
  securitySchemes:
    bearer: { type: http, scheme: bearer, bearerFormat: JWT }
    keycloak:
      type: oauth2
      flows:
        {
          clientCredentials:
            {
              tokenUrl: https://sso.example.com/…/token,
              scopes: { orders:read: '', orders:write: '', orders:admin: '' }
            }
        }

• Schemes of type http with scheme: bearer, oauth2 and openIdConnect are checked with the bearer token.
• security: [] or an empty requirement {} makes an operation public. A token sent anyway is still verified, and your code sees its caller.
• On a port with a security module, an operation that declares nothing requires a valid token.
• apiKey and basic schemes are not checked yet. The generator warns and leaves them out.
• A port without a security module gets the warning “security requirements are not enforced” when its contracts require tokens.

All of them are problem details. Unknown paths still answer 404.

The caller in your code

A principal has the subject (sub), the username, the roles, the scopes, all claims, and HasRole / HasScope. Your code never sees a JWT library or a framework type.

Errors on the wire

Every error is an RFC 9457 problem detail (application/problem+json) with type, title, status, detail and instance (all generators but Spring Boot add requestId), with the same status codes in every generator.

Configuration

The generator writes the values of the spec into a generated configuration file that you do not edit. Put your changes into your own file or into environment variables. They win over the generated file.

Values can read environment variables with ${NAME} or ${NAME:default}, for example issuer: ${AUTH_ISSUER:http://localhost:8180/realms/shop}. In every generator but Spring Boot, a component with only one port also takes its number from the PORT variable (container platforms). Node.js and NestJS keep the settings in TypeScript: settings.ts holds the values of the spec, the startServer / startPorts options override them per port and per module, and GENEXY_PORTS_<NAME>_PORT sets a port number.

Differences