Operation uses unknown HTTP authentication method

Issue ID: v3-operation-securityrequirement-http-unknown

Average severity: Medium

Description

The API operation uses HTTP authentication method that is not included in IANA Authentication Scheme Registry.

For more details, see the OpenAPI Specification.

Example

The following is an example of how this type of risk could look in your API definition. Here, the HTTP authentication method myAuth uses a custom authentication scheme:

{  
    "servers": [
        {
            "url": "https://my.api.server.com/",
            "description": "API server"
        }
    ],
    // ...  
    "components": {
        "securitySchemes": {
            "myAuth": {
                "type": "http",
                "scheme": "foo"
            }
        }
    },
    // ...
    "paths": {
        "/pets": {
            "post": {
                "description": "Creates a new pet in the store",
                "operationId": "addPet",
                "security": [
                    {
                        "myAuth": []
                    }
                ]
                // ...
            }
        }
    }
}

Possible exploit scenario

If the HTTP authentication you have set is not included in IANA Authentication Scheme Registry, it must be considered unknown, because it cannot be trusted to adhere to any recognized standard.

Using unknown HTTP authentication methods is risky, because it is unclear how thoroughly they have been vetted or tested. In addition, your API consumers do not know what your HTTP authentication means, or how it works.

Remediation

Do not use HTTP authentication methods that are not included in IANA Authentication Scheme Registry.

Use a more secure authentication method, like OAuth 2.0. It uses access tokens with limited lifetime and authorizations (the scopes) granted that the resource owner grants from an authorization server.

An API operation can be consumed only if the request includes an access token and the scopes of the token match the scopes that the API operation requires. Even if attackers successfully retrieved access tokens, they can only use the token on a subset of the API operation and for a limited time.

{ 
    "servers": [
        {
            "url": "https://my.api.server.com/",
            "description": "API server"
        }
    ],
    // ...
    "components": {
        "securitySchemes": {
            "OAuth2": {
                "type": "oauth2",
                "flows": {
                    "authorizationCode": {
                        "scopes": {
                            "write": "modify objects in your account",
                            "read": "read objects in your account"
                        },
                        "authorizationUrl": "https://example.com/oauth/authorize",
                        "tokenUrl": "https://example.com/oauth/token" 
                    }
                }
            }
        }
    },
    // ...
    "paths": {
        "/pets": {
            "post": {
                "description": "Creates a new pet in the store",
                "operationId": "addPet",
                "security": [
                    {
                        "OAuth2": [
                            "write",
                            "read"
                        ]
                    }
                ]
                // ...
            }
        }
    }
}