On this page

Adding security

Found an error? Have a suggestion?Edit this page on GitHub

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

Auth mechanism examples:

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

If you're using AsyncAPI to define an API that connects to a message broker, you'll probably use 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: 3.0.0
2info:
3  title: Hello world application
4  version: '0.1.0'
5servers:
6  production:
7    host: broker.mycompany.com
8    protocol: amqp
9    description: This is "My Company" broker.
10    security:
11      - type: userPassword
12channels:
13  hello:
14    address: 'hello'
15    messages:
16      sayHelloMessage:
17        $ref: '#/components/messages/hello-msg'
18  goodbye:
19    address: 'goodbye'
20    messages:
21      sayGoodbyeMessage:
22        $ref: '#/components/messages/goodbye-msg'
23operations:
24  receiveHello:
25    action: 'receive'
26    channel:
27      $ref: '#/channels/hello'
28  receiveGoodbye:
29    action: 'receive'
30    channel:
31      $ref: '#/channels/goodbye'
32components:
33  messages:
34    hello-msg:
35      payload:
36        type: object
37        properties:
38          name:
39            type: string
40          sentAt:
41            $ref: '#/components/schemas/sent-at'
42    goodbye-msg:
43      payload:
44        type: object
45        properties:
46          sentAt:
47            $ref: '#/components/schemas/sent-at'
48  schemas:
49    sent-at:
50      type: string
51      description: The date and time a message was sent.
52      format: datetime

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.

There's a property in the server object called security. It's an array and can contain multiple security mechanisms. You chose to specify only one mechanism which is userPassword.

A best practice is to put security details inside the components.securitySchemes section as it enables reusability across multiple servers. Below, you can see the same example, but this time, under server security, you see that $ref links to more security details located under the user-password object in securitySchemes.

1asyncapi: 3.0.0
2info:
3  title: Hello world application
4  version: '0.1.0'
5servers:
6  production:
7    host: broker.mycompany.com
8    protocol: amqp
9    description: This is "My Company" broker.
10    security:
11      - $ref: "#/components/securitySchemes/user-password"
12channels:
13  hello:
14    address: 'hello'
15    messages:
16      sayHelloMessage:
17        $ref: '#/components/messages/hello-msg'
18  goodbye:
19    address: 'goodbye'
20    messages:
21      sayGoodbyeMessage:
22        $ref: '#/components/messages/goodbye-msg'
23operations:
24  receiveHello:
25    action: 'receive'
26    channel:
27      $ref: '#/channels/hello'
28  receiveGoodbye:
29    action: 'receive'
30    channel:
31      $ref: '#/channels/goodbye'
32components:
33  messages:
34    hello-msg:
35      payload:
36        type: object
37        properties:
38          name:
39            type: string
40          sentAt:
41            $ref: '#/components/schemas/sent-at'
42    goodbye-msg:
43      payload:
44        type: object
45        properties:
46          sentAt:
47            $ref: '#/components/schemas/sent-at'
48  schemas:
49    sent-at:
50      type: string
51      description: The date and time a message was sent.
52      format: datetime
53  securitySchemes:
54    user-password:
55      type: userPassword
Hint

Learn more about the several kinds of security schemes.

Conclusion

You can now define what security mechanisms your application needs to connect to the server. You've also seen how to require 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.

Was this helpful?
Help us improve the docs by adding your contribution.
OR
Github:AsyncAPICreate Issue on GitHub