Adding security

In production environments, your API may have to access a message broker that's protected by some auth mechanisms.

Some examples of these are:

• User & password
• Certificates
• API keys
• OAuth 2

If you're using AsyncAPI to define an API that connects to a message broker, you'll most probably make use of user/password or certificates. Traditionally, message brokers are infrastructure pieces that serve an internal purpose and they're not exposed to the public. That's why their security mechanisms are also simpler than what we're used to with REST APIs. However, AsyncAPI also helps you define your HTTP streaming APIs and therefore it supports more sophisticated mechanisms like OAuth2 or OpenID.

Continuing with the hello world application example, let's learn how to define a simple security scheme (mechanism) for it.

1asyncapi: '2.5.0'
2info:
3  title: Hello world application
4  version: '0.1.0'
5servers:
6  production:
7    url: broker.mycompany.com
8    protocol: amqp
9    description: This is "My Company" broker.
10    security:
11      - user-password: []
12channels:
13  hello:
14    publish:
15      message:
16        $ref: '#/components/messages/hello-msg'
17  goodbye:
18    publish:
19      message:
20        $ref: '#/components/messages/goodbye-msg'
21components:
22  messages:
23    hello-msg:
24      payload:
25        type: object
26        properties:
27          name:
28            type: string
29          sentAt:
30            $ref: '#/components/schemas/sent-at'
31    goodbye-msg:
32      payload:
33        type: object
34        properties:
35          sentAt:
36            $ref: '#/components/schemas/sent-at'
37  schemas:
38    sent-at:
39      type: string
40      description: The date and time a message was sent.
41      format: datetime
42  securitySchemes:
43    user-password:
44      type: userPassword

The example above shows how to specify that your server (a Kafka broker) requires a user and a password to establish a connection. Let's break this down:

1. There's a new property in the server object called security. It's an array and can contain multiple security mechanisms. You chose to add one called "user-password". This is simply a memorable name that you give to this security scheme. Whatever name you choose, it must be defined in the components/securitySchemes section. You might have also noticed its value is an empty array. That's because some security schemes allow for extra configuration. Since this is not the case in this example, leave the array empty.
2. We've added a new section called securitySchemes under components. Inside it, you can find the definition of your user-password mechanism. This section makes it clear that you're speaking about a user/password mechanism, which is the type: userPassword in line 44.

Conclusion

You're now able to define what security mechanisms your application needs to connect to the server. You've seen how to define the requirement of a user and a password, which is the most common use case.

At this point, you know AsyncAPI well enough to create a simple Hello world application. However, real use cases are more complicated than that. The following tutorials can teach you how to create real-world use cases, from zero to production.