local auth module

The local auth module starts an authentication service which provides a UI to create and manage authentication tokens. You can issue tokens with certain sets of rights to a set of topics. If the module configuration option is defined, the local auth module will start an HTTP server that provides a RESTful API to manage a token database. Tokens have a set of privileges for reading (subscribing) and writing (publishing) on a per-topic basis.


Configuration Options

All configuration for the auth module will exist in the pubkeeper.conf under the [auth] directive.

Module and Provider configuration

The local auth module requires setting the module and provider directives:

  • modulepubkeeper.server.core.auth.local.LocalAuthModule
  • providerpubkeeper.server.core.auth.local.LocalAuthProvider

Database Connection

The local auth module stores its tokens in an SQL database. You should specify how you want to connect to that database using the database configuration option:

  • database—The URI to where the token db is located. This can be an sqlite URL or any SQL connection string: Examples:
    • sqlite:///tokens.db—Store tokens in a local SQLite file. Use three slashes.
    • postgresql://user:pass@host:port/dbname—Connect to an existing postgresql database to store tokens.

Alternatively, you can specify the connection mechanism through individual parameters. To set these, do not include the database option at all:

  • database_type—The type of connection, e.g., postgresql, sqlite.
  • database_user—The db user to connect with, e.g., root.
  • database_pass—The db password to connect with, e.g., p@$$w0rd.
  • database_host—The db host, defaults to localhost.
  • database_port—The db port, defaults to 5432.
  • database_name—The db name, defaults to pk_auth.

If the database does not exist or the schema is not set up, the local auth module will seed the database with some initial content that can be configured in the configuration file too.

  • initial_token—The token content for the seed token. This token is granted all rights on all topics.

Token Management UI

The local auth module also comes with an included UI to manage tokens.

  • enable_ui—Whether or not the included UI will be served as well. If true, the UI will be available at the root of the Pubkeeper server. i.e., http://127.0.0.1:9898.
  • allow_origin—If you want to host the token management UI on a different server than the Pubkeeper server, you will need to enable cross-origin access since the UI makes XHR requests to the PK server to manage tokens. Set this configuration to the host of your UI. Example: http://pk-auth.my-domain.com.

The login to the UI is managed by the database in the users table. The default user is created when the database is seeded and has a username and password of root. To change the default password when the database is seeded you can use the initial_password configuration option.

  • initial_password—The password to assign to the root user for UI access. This password is only populated when the database is created/seeded.

Example configuration

[auth]
module = pubkeeper.server.core.auth.local.LocalAuthModule
provider = pubkeeper.server.core.auth.local.LocalAuthProvider
database = sqlite:///tokens.db
initial_token = iamasecrettoken
initial_password = root_password
enable_ui = true

API

All payloads must be sent with the application/json Content-Type header.

With the exception of the /auth/login /auth/logout and /auth/validate endpoints, all endpoints require authentication.


/login

POST

Payload:
{
  "username": "{username}",
  "password": "{password}"
}
Returns:

200—Success
401—Unauthorized

This will log in to the connection by issuing an auth session cookie.


/logout

GET

Payload:

None

Returns:

200—Success

This will invalidate the session cookie.


/validate

POST

Payload:
{
  "token": "{shahash}"
}
Returns:

200—Success

{
  "valid": [true|false],
  "rights": [
    {
      "topic": "{topic}",
      "read": [true|false],
      "write": [true|false]
    },
    ...
  ]
}

Returns the state of the provided token. Invalid tokens will return with false and no rights array. Only tokens that both exist and are not revoked will return true and an array of rights.


/token

GET

Payload:

None

Returns:

200—Success

[
  {
    "token": "shahash",
    "revoked": [true|false],
    "description": "{description}"
  },
  ...
]

401—Unauthorized

Will return a set of tokens in the system.

POST

Payload:
{
  "token": "{shahash - OPTIONAL}",
  "description": "{description}",
  "rights": [
    {
      "topic": "{topic, with wildcards *, and **}",
      "read": [true|false],
      "write": [true|false]
    },
    ...
  ]
}
Returns:

201—Success, record created

{
  "token": "{shahash}"
}

400—The rights array was not provided or the token provided is not 256 bits in length 409—Conflict, the token provided already exists

Create a token with the provided set of rights. If a token is provided, it will try to create a token with that hash. By default, a random hash will be generated.

PUT

Payload
{
  "token": "{shahash}",
  "description": "{description}",
  "rights": [
    {
      "topic": "{topic, with wildcards *, and **}",
      "read": [true|false],
      "write": [true|false]
    },
    ...
  ]
}
Returns
  • 200—Success, Record Overwritten
{
  "token": "{shahash}"
}
  • 400 - The rights array was not provided, or, the token provided is not 256 bits in length
  • 404 - The token did not exist
  • 409 - Conflict, the token provided already exists

Update an existing a token with the provided set of rights.

DELETE

Payload:
{
  "token": "{shahash}",
}
Returns:

200—Success, record deleted
400—The token does not exist

Delete a given token from the token database.

results matching ""

    No results matching ""