Security¶
If authorization is required, define security schemes with @SecurityScheme [name] [type] [parameters] and apply
them with @Security [scheme-name] [scope1] [scope2] [...].
All examples here use MyApiAuth as the name. The name can be anything; multiple named schemes are supported. Each
scheme needs its own name, except OAuth2, which supports multiple flows under the same name.
Scheme types¶
| Type | Description | Parameters | Example |
|---|---|---|---|
| HTTP | HTTP authentication using the Authorization header |
scheme: any HTTP authentication scheme | @SecurityScheme MyApiAuth basic |
| APIKey | An API key passed with the request | in: header, query or cookie; name: the field that carries the key |
@SecurityScheme MyApiAuth apiKey header X-MyCustomHeader |
| OpenIdConnect | Delegate to an OpenID Connect provider | url: the provider's discovery URL | @SecurityScheme MyApiAuth openIdConnect https://example.com/.well-known/openid-configuration |
| OAuth2AuthCode | OAuth2 authorization code flow | authorizationUrl, tokenUrl | @SecurityScheme MyApiAuth oauth2AuthCode /oauth/authorize /oauth/token |
| OAuth2Implicit | OAuth2 implicit flow | authorizationUrl | @SecurityScheme MyApiAuth oauth2Implicit /oauth/authorize |
| OAuth2ResourceOwnerCredentials | OAuth2 resource owner password flow | tokenUrl | @SecurityScheme MyApiAuth oauth2ResourceOwnerCredentials /oauth/token |
| OAuth2ClientCredentials | OAuth2 client credentials flow | tokenUrl | @SecurityScheme MyApiAuth oauth2ClientCredentials /oauth/token |
Any text after the last parameter becomes the description, for example
@SecurityScheme MyApiAuth basic Login with your admin credentials.
Applying schemes¶
Apply global security in the service description and/or per-operation security on a handler:
// Global (service description)
// @Security MyApiAuth read_user write_user
// Per-operation (handler godoc)
// @Security MyApiAuth read_user
OAuth2 scopes¶
Define scopes with @SecurityScope [scheme-name] [scope-code] [scope-description]:
// @SecurityScope MyApiAuth read_user Read a user from the system
// @SecurityScope MyApiAuth write_user Write a user to the system