Basic Authentication #

The Swagger security scheme of type basic can be extended by FLAT’s x-flat-basicauth property to define credentials for Basic Authentication.

Properties of x-flat-basicauth #

• users: an array of credential strings
• file: a filename to a file with credential strings (a .htpasswd file)
• realm: Basic authentication realm (optional, default Access)

📎 Only the first set of credentials matching a username is evaluated. Passwords hashed with algorithms other than bcrypt are ignored (→ Creating Password Hashes).

Example #

Here’s an example on how to protect your whole API with Basic Authentication:

swagger: "2.0"
security:
  - BasicAuth: []
paths:
  …
securityDefinitions:
  BasicAuth:
    type: basic
    x-flat-basicauth:
      realm: Login
      users:
        - "john:$2y$05$oHl6VenOMxUcJTxs6acIRe5h5LXTJi0.KT5/I/8akN6jXEQfbwV6y"
        - "joe:$2y$05$mJwzySE7bUMJEYAOMx5GieKi/7RNEDOcIjibksgpTsv5VlUdOjKGu"

Instead of an an inline array of users you can reference a file containing one username and password hash pairs per line, for example conf/htpasswd:

securityDefinitions:
  BasicAuth:
    type: basic
    x-flat-basicauth:
      file: "conf/htpasswd"

To access your API, users need to provide valid credentials in the Authorization header. Otherwise, access will be denied with a 401 status code. Using the example users list given above, the correct Base64 encoded credentials am9objpkb2U= translate to john:doe:

$ curl -i http://localhost:8080/
HTTP/1.1 401 Unauthorized
…
WWW-Authenticate: Basic realm="Login", charset="UTF-8"
…

$ curl -i -H 'Authorization: Basic am9objpkb2U=' http://localhost:8080/
HTTP/1.1 200 OK
…

$ curl -i -u john:doe http://localhost:8080/
HTTP/1.1 200 OK
…

Creating Password Hashes #

FLAT only supports bcrypt based password hashes, hashes created with other algorithms will be ignored. You can create these hashes with Apache’s htpasswd utility, for example, the one supplied in the FLAT container image. Use htpasswd with the -B option to create a bcrypt-hashed password and type the password (foo in this example) twice:

$ docker run -ti code-registry.avenga.cloud/product/flat/flat/flatrunner htpasswd -nB jane
New password:
Re-type new password:
jane:$2y$05$khzX26HXjdsF14gjuXHp6O1RwWfZKgaLpnuivFCcBzpw.5p0Rv8mi

The $2y$ prefix indicates that this hash is a bcrypt hash.

You can now add jane’s credentials to the users array in your swagger.yaml or to your password file to give jane access.

⚠️ You may have to login to the container registry using docker login before running htpasswd from the FLAT container image.