Pymacaron

Star
Logo

A python microservice framework

Reference:

Overview
Quick start
Project files
OpenAPI specification
API objects
Server code
Deployment pipeline
Docker packaging
JWT authentication
Configuration
Error handling
Asynchronous execution
Database serialisation
Testing
Monitoring

JWT Authentication

JWT authentication is buit-in into PyMacaron and therefore the prefered authentication mechanism.

Generating JWT tokens

Your service should generate JWT tokens using the ‘generate_token()’ method from pymacaron.auth.

TODO: how to set token in response of an authentication endpoint

Requiring JWT authentication around an endpoint

To add JWT token authentication around an api endpoint, set the ‘x-decorate-request’ and ‘x-decorate-server’ attributes on the endpoint’s definition in your OpenAPI file:

/profile/{user_id}:
  get:
    summary: Get a user's profile.
    produces:
      - application/json
    x-bind-server: myserver.profile.do_get_profile
    x-decorate-server: pymacaron.auth.requires_auth
    x-decorate-request: pymacaron.auth.add_auth
    parameters:
      - in: path
        name: user_id
        description: User ID.
        required: true
        type: string
    responses:
      200:
        description: User Profile.
        schema:
          $ref: '#/definitions/Profile'
      default:
        description: Error
        schema:
          $ref: '#/definitions/Error'

Passing the JWT token when calling an endpoint

Authentication is achieved by passing the JWT session token in the HTTP Authorization header of api requests:

Authorization: Bearer {session token}

Alternatively, you may pass the session token as a cookie named ‘token’ and containing the string ‘Bearer {session token}’.

JWT issuer, audience and secret

The JWT issuer, audience and secret should be set via ‘pym-config.yaml’. By default, tokens are valid for 24 hours.

UserID in the JWT token

JWT tokens issued by pymacaron always have a ‘sub’ field set to a user ID. You may set this user ID when generating tokens as an argument to ‘pymacaron.auth.generate_token()’, or let pymacaron use the default user ID defined in ‘pymacaron.config.get_config().default_user_id’.