Akwatype allows to declare the security schemes as they are defined in Open API 3.0 (OAS 3.0)

The following security schemes are supported

  • HTTP authentication
    • basic
    • bearer
    • other
  • API keys
  • OAuth 2
  • OpenID

 

Security Schemes

SecuritySchemes are declared in the service description files.

A unique name is associated to each SecurityScheme to be able to reference it in the security requirement.

The following are examples of the declaration of the different security schemes :

securityScheme BasicAuthenticationSample {
    type: http
    scheme: "basic"
}

securityScheme BearerSample {
    type: http
    scheme: "bearer"
    bearerFormat: "JWT"
}

securityScheme ApiKeySample {
    type: apiKey
    name: "api_key"
    in: header
}

securityScheme OpenIdConnectSample {
    type: openIdConnect
    openIdConnectUrl: "https://example.com/.well-known/openid-configuration"
}

securityScheme ImplicitOAuth2Sample {
    type: oauth2
    flows {
        implicit {
            authorizationUrl: "https://example.com/api/oauth/dialog"
            scopes: [
                "write:persons": "modify persons",
                "read:persons": "read persons"
            ]
        }
    }
}

securityScheme MultiAuth2Sample {
    type: oauth2
    flows {
        implicit {
            authorizationUrl: "https://example.com/api/oauth/dialog"
            scopes: [
                "write:persons": "modify persons",
                "read:persons": "read persons"
            ]
        }
        authorizationCode {
            authorizationUrl: "https://example.com/api/oauth/dialog"
            tokenUrl: "https://example.com/api/oauth/token",
            scopes: [
                "write:persons": "modify persons",
                "read:persons": "read persons"
            ]
        }
        password {
            tokenUrl: "https://example.com/api/oauth/token"
            scopes: [
                "write:persons": "modify persons",
                "read:persons": "read persons"
            ]
        }
        clientCredentials {
            tokenUrl: "https://example.com/api/oauth/token"
            scopes: [
                "write:persons": "modify persons",
                "read:persons": "read persons"
            ]
        }
    }
}

We advise you to refer to the specification of the security schemes for more explanation on security scheme 

 

Security Requirement

 

The security requirement lists the required security schemes to execute an operation

A security requirement is composed of a security scheme or a list of security schemes, each of which may have a list of scopes if necessary.

security {
    MultiAuth2Sample:["read:persons","write:persons"]
}

 

As some REST APIs support multiple authentication types, the security statement allows you to combine multiple security schemes using logical OR and AND.

 

security { A, B }                           # A AND B

security { A | B }                          # A OR B


security { A, B | C, D }                    # (A AND B) OR (C AND D)

 

Applying the security requirements

Security requirements can be applied at the service, resource or route level.

The security requirements are propagated to the lower levels service -> resource -> route if no security has already been defined at these levels.

 

Example of service level security definition

The security defined at the service level applies to routes. :

  • person, persons and other
service ServiceWithSecuritySample{
    security {
        BasicAuthenticationSample |
        MultiAuth2Sample:["read:persons","write:persons"]
    }
    url:"MyService"
    expose Persons {
        url:"persons"
        route person{
            url:"id:String"
            response: PersonDTO
        }
        route persons{
            url:"id:String"
            response: [PersonDTO]
        }
    }
     expose OtherResources{
        route other{
            url:"id:String"
            response: [OtherResource] 
        }
    }
}

Note: If we do not want to secure a lower level (a route for example) while a security has been defined at a higher level (a service for example) it is possible to declare an empty security in order not to recover the security defined at the higher level

        route person{
            security { }
            url:"id:String"
            response: PersonDTO
        }

 

Example of resource level security definition

In this this example, security defined at the resource level applies to routes. :

  • person and persons

but not to the other route. 

service ServiceWithSecuritySample2{
    url:"MyService"
    expose Persons {
        security {
            BasicAuthenticationSample |
            MultiAuth2Sample:["read:persons","write:persons"]
        }
        url:"persons"
        route person{
            url:"id:String"
            response: PersonDTO
        }
        route persons{
            url:"id:String"
            response: [PersonDTO]
        }
    }
    expose OtherResources{
        route other{
            url:"id:String"
            response: [OtherResource] 
        }
    }
}

 

Example of route level security definition

In this example, the security defined at the route level only applies to routes. :

  • person

 

service ServiceWithSecuritySample3{
    url:"MyService"
    expose Persons {
        url:"persons"
        route person{
            security {
                BasicAuthenticationSample |
                MultiAuth2Sample:["read:persons","write:persons"]
            }
            url:"id:String"
            response: PersonDTO
        }
        route persons{
            url:"id:String"
            response: [PersonDTO]
        }
    }
    expose OtherResources{
        route otherResource{
            url:"id:String"
            response: [OtherResource] 
        }
    }
}