Skip to content

OAuth2 Security

What is OAuth2 Security Schema in AsyncAPI?

Section titled “What is OAuth2 Security Schema in AsyncAPI?”

OAuth2 is an authorization framework that enables third-party applications to obtain limited access to a user’s account on an HTTP service. In AsyncAPI, OAuth2 security schemes provide a standardized way to define OAuth2-based authentication and authorization for message brokers and APIs.

OAuth2 in AsyncAPI supports four main types of authorization flows:

  1. Authorization Code Flow: The most complete and secure flow, designed for server-side applications that can securely store client secrets.
  2. Client Credentials Flow: Designed for server-to-server authentication where no user interaction is involved.
  3. Implicit Flow: Simplified flow designed for browser-based applications or mobile apps that cannot securely store client secrets.
  4. Password Flow: Allows direct authentication using username and password, suitable for trusted first-party applications.

Each of these flows has different security characteristics and is suitable for different use cases.

When to Use OAuth2 Security Schema in AsyncAPI

Section titled “When to Use OAuth2 Security Schema in AsyncAPI”

OAuth2 security schemes in AsyncAPI are appropriate when:

  • Delegated Authorization: You need to allow third-party applications to access resources on behalf of users
  • Fine-grained Access Control: You need to control access using scopes that define specific permissions
  • Modern Authentication: You want to implement a modern, standardized authentication framework
  • Single Sign-On: You need to integrate with existing OAuth2-based SSO solutions
  • Token-based Security: You want to use short-lived access tokens with optional refresh tokens
  • Multiple Client Types: Your API needs to support different types of clients (web, mobile, server)
  • User Consent: You want users to explicitly grant permissions to applications
  • Enterprise Integration: You need to integrate with enterprise identity providers
  • Microservices Architecture: You’re building a microservices ecosystem with centralized authentication

The specific OAuth2 flow you choose depends on your application type and security requirements:

  • Use Authorization Code Flow for server-side web applications that can securely store client secrets
  • Use Client Credentials Flow for server-to-server communication with no user involvement
  • Use Implicit Flow for browser-based applications without a backend (though Authorization Code Flow with PKCE is now preferred)
  • Use Password Flow for trusted first-party applications where collecting credentials directly is acceptable

Here’s how to define an OAuth2 security scheme in AsyncAPI that supports multiple flows:

{
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://auth.example.com/authorize",
"tokenUrl": "https://auth.example.com/token",
"refreshUrl": "https://auth.example.com/refresh",
"availableScopes": {
"read:messages": "Read messages from the broker",
"write:messages": "Write messages to the broker"
}
},
"clientCredentials": {
"tokenUrl": "https://auth.example.com/token",
"availableScopes": {
"read:messages": "Read messages from the broker",
"write:messages": "Write messages to the broker"
}
}
},
"description": "OAuth2 authentication for AsyncAPI services"
}

When you want to use a specific OAuth2 flow, you can define just that flow:

{
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://auth.example.com/authorize",
"tokenUrl": "https://auth.example.com/token",
"refreshUrl": "https://auth.example.com/refresh",
"availableScopes": {
"read:messages": "Read messages from the broker",
"write:messages": "Write messages to the broker"
}
}
},
"description": "OAuth2 Authorization Code flow for secure API access"
}
{
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "https://auth.example.com/token",
"availableScopes": {
"api:read": "Read access to API resources",
"api:write": "Write access to API resources"
}
}
},
"description": "OAuth2 Client Credentials flow for server-to-server authentication"
}
{
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "https://auth.example.com/authorize",
"availableScopes": {
"read:messages": "Read messages from the broker",
"write:messages": "Write messages to the broker"
}
}
},
"description": "OAuth2 Implicit flow for browser-based applications"
}
{
"type": "oauth2",
"flows": {
"password": {
"tokenUrl": "https://auth.example.com/token",
"refreshUrl": "https://auth.example.com/refresh",
"availableScopes": {
"read:messages": "Read messages from the broker",
"write:messages": "Write messages to the broker"
}
}
},
"description": "OAuth2 Password flow for trusted first-party applications"
}

When implementing OAuth2 authentication in your AsyncAPI-defined services:

  1. Security First: Always use HTTPS for all OAuth2-related endpoints
  2. Flow Selection: Choose the appropriate OAuth2 flow based on your client type and security requirements
  3. Scope Definition: Define clear, granular scopes that follow the principle of least privilege
  4. Token Management: Implement proper token validation, expiration, and refresh mechanisms
  5. Client Registration: Establish a secure process for client registration and credential management
  6. Error Handling: Provide clear error messages for authentication failures
  7. User Experience: Design a smooth authentication experience with clear permission requests
  8. Token Storage: Ensure secure storage of tokens on both client and server sides
  9. Revocation: Implement token revocation capabilities for security incidents

For more detailed information about specific OAuth2 flows, refer to:

In an AsyncAPI document

Define the scheme (type: oauth2) under components.securitySchemes and reference it from every server that needs it. In AsyncAPI 3.0 a server's security lists the schemes themselves; in 2.x it lists requirement objects by name, with the scopes they need.

asyncapi.yaml
asyncapi: 3.0.0
info:
title: Orders
version: 1.0.0
servers:
production:
host: api.example.com
protocol: wss
security:
- $ref: '#/components/securitySchemes/oauth'
components:
securitySchemes:
oauth:
type: oauth2
description: OAuth 2.0, clientCredentials flow
flows:
clientCredentials:
tokenUrl: https://auth.example.com/oauth/token
availableScopes:
orders:read: Receive order events
orders:write: Publish order events
scopes:
- orders:read

Fields

FieldTypeDescription
descriptionstringA short description for security scheme
typerequiredstring
oauth2
The type of the security scheme
flowsrequiredobject
flows.authorizationCodeobjectContains information about OAuth2 Authorization Code flow. Is a secure, multi-step process where an application trades user consent for an authorization code, which is then exchanged behind the scenes for an access token
flows.authorizationCode.authorizationUrlrequiredstringThe authorization URL to be used for this flow. This MUST be in the form of an absolute URL
flows.authorizationCode.availableScopesrequiredobjectThe available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it
flows.authorizationCode.refreshUrlstringThe URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL
flows.authorizationCode.tokenUrlrequiredstringThe token URL to be used for this flow. This MUST be in the form of an absolute URL
flows.clientCredentialsobjectContains information about OAuth2 Client Credentials flow. Is a machine-to-machine (M2M) authentication method where an application uses its own unique ID and secret key to get an access token from a server
flows.clientCredentials.availableScopesrequiredobjectThe available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it
flows.clientCredentials.refreshUrlstringThe URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL
flows.clientCredentials.tokenUrlrequiredstringThe token URL to be used for this flow. This MUST be in the form of an absolute URL
flows.implicitobjectContains information about OAuth2 Implicit Grant flow. The Implicit flow was a simplified OAuth flow previously recommended for native apps and JavaScript apps where the access token was returned immediately without an extra authorization code exchange step
flows.implicit.authorizationUrlrequiredstringThe authorization URL to be used for this flow. This MUST be in the form of an absolute URL
flows.implicit.availableScopesrequiredobjectThe available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it
flows.implicit.refreshUrlstringThe URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL
flows.passwordobjectContains information about OAuth2 Implicit flow. Allows a client application to exchange a user's direct username and password for an access token. However, modern security standards strongly advise against using it because it exposes raw credentials and blocks multi-factor authentication
flows.password.availableScopesrequiredobjectThe available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it
flows.password.refreshUrlstringThe URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL
flows.password.tokenUrlrequiredstringThe token URL to be used for this flow. This MUST be in the form of an absolute URL
scopesarray of stringList of the needed scope names

Validate with JSON Schema

The OAuth2 Authentication JSON Schema from the AsyncAPI JSON Schema registry: https://schemas.asyncapi.pavelon.dev/draft-07/schemas/v3/security/oauth2/oauth2

Questions

Which OAuth 2.0 flows does AsyncAPI support?

Four, under flows: authorizationCode, clientCredentials, implicit and password. A scheme can list several.

What is the difference between scopes and availableScopes?

In AsyncAPI 3.0 each flow lists every scope it can grant in availableScopes (name to description), and the scheme's scopes lists the ones this server or operation needs. In 2.x the flow field is called scopes, and the needed scopes go in the security requirement: security: [{ oauth: ['orders:read'] }].