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:
- Authorization Code Flow: The most complete and secure flow, designed for server-side applications that can securely store client secrets.
- Client Credentials Flow: Designed for server-to-server authentication where no user interaction is involved.
- Implicit Flow: Simplified flow designed for browser-based applications or mobile apps that cannot securely store client secrets.
- 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
Examples
Section titled “Examples”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:
Authorization Code Flow Example
Section titled “Authorization Code Flow Example”{ "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"}Client Credentials Flow Example
Section titled “Client Credentials Flow Example”{ "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"}Implicit Flow Example
Section titled “Implicit Flow Example”{ "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"}Password Flow Example
Section titled “Password Flow Example”{ "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"}Implementation Considerations
Section titled “Implementation Considerations”When implementing OAuth2 authentication in your AsyncAPI-defined services:
- Security First: Always use HTTPS for all OAuth2-related endpoints
- Flow Selection: Choose the appropriate OAuth2 flow based on your client type and security requirements
- Scope Definition: Define clear, granular scopes that follow the principle of least privilege
- Token Management: Implement proper token validation, expiration, and refresh mechanisms
- Client Registration: Establish a secure process for client registration and credential management
- Error Handling: Provide clear error messages for authentication failures
- User Experience: Design a smooth authentication experience with clear permission requests
- Token Storage: Ensure secure storage of tokens on both client and server sides
- Revocation: Implement token revocation capabilities for security incidents
Related Documentation
Section titled “Related Documentation”For more detailed information about specific OAuth2 flows, refer to:
- Authorization Code OAuth Flow
- Client Credentials OAuth Flow
- Implicit OAuth Flow
- Password OAuth Flow
- OAuth2 Scopes
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: 3.0.0info: title: Orders version: 1.0.0servers: 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:readasyncapi: 2.6.0info: title: Orders version: 1.0.0servers: production: url: api.example.com protocol: wss security: - oauth: - orders:readchannels: {}components: securitySchemes: oauth: type: oauth2 description: OAuth 2.0, clientCredentials flow flows: clientCredentials: tokenUrl: https://auth.example.com/oauth/token scopes: orders:read: Receive order events orders:write: Publish order eventsFields
| Field | Type | Description |
|---|---|---|
description | string | A short description for security scheme |
typerequired | stringoauth2 | The type of the security scheme |
flowsrequired | object | |
flows.authorizationCode | object | Contains 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.authorizationUrlrequired | string | The authorization URL to be used for this flow. This MUST be in the form of an absolute URL |
flows.authorizationCode.availableScopesrequired | object | The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it |
flows.authorizationCode.refreshUrl | string | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL |
flows.authorizationCode.tokenUrlrequired | string | The token URL to be used for this flow. This MUST be in the form of an absolute URL |
flows.clientCredentials | object | Contains 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.availableScopesrequired | object | The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it |
flows.clientCredentials.refreshUrl | string | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL |
flows.clientCredentials.tokenUrlrequired | string | The token URL to be used for this flow. This MUST be in the form of an absolute URL |
flows.implicit | object | Contains 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.authorizationUrlrequired | string | The authorization URL to be used for this flow. This MUST be in the form of an absolute URL |
flows.implicit.availableScopesrequired | object | The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it |
flows.implicit.refreshUrl | string | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL |
flows.password | object | Contains 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.availableScopesrequired | object | The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it |
flows.password.refreshUrl | string | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL |
flows.password.tokenUrlrequired | string | The token URL to be used for this flow. This MUST be in the form of an absolute URL |
scopes | array of string | List 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'] }].