Skip to content

Authentication

APIs usually require authentication for POST, PUT and DELETE methods. OBA uses the authentication mechanisms in OpenAPI to address this issue.

Authentication in OpenAPI

OpenAPI uses the term security scheme for authentication and authorization schemes. OpenAPI 3.0 lets you describe APIs protected using the following security schemes (see more in the official documentation):

  • Basic
  • Bearer
  • other HTTP schemes as defined by RFC 7235 and HTTP Authentication Scheme Registry
  • API keys in headers, query string or cookies
  • Cookie authentication
  • OAuth 2
  • OpenID Connect Discovery

OBA supports Bearer, further described below.

Info

The descriptions in this page have been adapted from the OpenAPI official documentation

Bearer Token

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name Bearer authentication can be understood as give access to the bearer of this token. The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources: 

     Authorization: Bearer <token>

Describing Bearer Authentication

Info

OBA describes and configures the authentication in your API automatically.

In OpenAPI 3.0, Bearer authentication is a security scheme with type: http and scheme: bearer. You first need to define the security scheme under components/securitySchemes, then use the security keyword to apply this scheme to the desired scope – global (as in the example below) or specific operations: 

    openapi: 3.0.0
    ...
    # 1) Define the security scheme type (HTTP bearer)
    components:
      securitySchemes:
        bearerAuth:            # arbitrary name for the security scheme
          type: http
          scheme: bearer
          bearerFormat: JWT    # optional, arbitrary value for documentation purposes
    # 2) Apply the security globally to all operations
    security:
      - bearerAuth: []         # use the same name as above

Optional bearerFormat is an arbitrary string that specifies how the bearer token is formatted. Since bearer tokens are usually generated by the server, bearerFormat is used mainly for documentation purposes, as a hint to the clients. In the example above, it is "JWT", meaning JSON Web Token. The square brackets [] in bearerAuth: [] contain a list of security scopes required for API calls. The list is empty because scopes are only used with OAuth 2 and OpenID Connect.

In the example below, Bearer authentication is applied to the POST method: 

paths:
  post:
    description: Create a new instance of a ConfigurationSetup
    parameters:
    - description: Username
      in: path
      name: user
      required: false
      schema:
        type: string
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfigurationSetup'
      description: A new ConfigurationSetupto be created
    responses:
      201:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationSetup'
        description: Created
    security:
    - BearerAuth: []
    summary: Create a ConfigurationSetup
    tags:
    - ConfigurationSetup

Add authentication to your API

OBA supports Firebase as an authentication provider. We have created a small tutorial to help walking you through setting it up.

Warning

User management is out of the scope of OBA. Creating and deleting users will be handled by the authentication provider.

Note

If you would like us to support additional exciting features (like support for new providers), please open an issue in our GitHub repository.