{"id":7910,"date":"2021-03-09T01:00:51","date_gmt":"2021-03-09T01:00:51","guid":{"rendered":"https:\/\/staging-site.42crunch.com\/?p=7910"},"modified":"2022-11-24T11:24:01","modified_gmt":"2022-11-24T11:24:01","slug":"springfox-guide-security-definitions","status":"publish","type":"post","link":"https:\/\/staging2022.42crunch.com\/springfox-guide-security-definitions\/","title":{"rendered":"Creating High Quality OAS Definitions with Springfox &#8211; Part 1: Security Definitions"},"content":{"rendered":"<p><span style=\"font-weight: 400;\">Spring Boot is a popular framework to build applications and APIs. Leveraging the Springfox project and code annotations, developers can generate OAS files with a high 42Crunch Security Audit score.<\/span><\/p>\n<h2>What is the 42Crunch Security Audit?<\/h2>\n<p><span style=\"font-weight: 400;\">The <\/span><a href=\"https:\/\/42crunch.com\/api-security-audit\/\"><span style=\"font-weight: 400;\">42Crunch Security Audit<\/span><\/a><span style=\"font-weight: 400;\"> is one of 3 services from the <\/span><a href=\"https:\/\/42crunch.com\/api-security-platform\/\"><span style=\"font-weight: 400;\">42Crunch API Security Platform<\/span><\/a><span style=\"font-weight: 400;\">: it consumes OpenAPI (Swagger) files and analyzes them along two axes: security and data.<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">At the <\/span><b>security<\/b><span style=\"font-weight: 400;\"> level, the audit service looks at the transport used (is it using TLS?), the authentication method (Basic, API keys, OAuth) and in the case of OAuth, the grant type used and scopes. Each issue is given a negative score: the value of the score depends on the data and operation sensitivity. For example, the score is more severely affected if the data is marked as highly sensitive and the operation is DELETE than if the data is insensitive and the operation is a GET.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\">At the <b>data<\/b> level, the audit service analyzes how headers, path parameters, query parameters and body payloads are specified. In particular, it detects whether strings have patterns and boundaries, numbers have boundaries and in general, if schemas are available for all responses types. The goal is to ensure that all traffic inbound and outbound is thoroughly defined to prevent unwanted traffic from going through our API firewall.<\/li>\n<\/ul>\n<h2>Producing a High Quality OpenAPI File<\/h2>\n<p><span style=\"font-weight: 400;\">Our customers use two approaches:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">API design first, where specialized editors like SwaggerHub or Stoplight are used to create the OpenAPI file.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Code first, where the OpenAPI is produced via code annotations. Spring Boot is a widely used framework and it comes with first class support for OAS generation via the<\/span><a href=\"https:\/\/springfox.github.io\/springfox\/docs\/current\/\"> <span style=\"font-weight: 400;\">Springfox framework<\/span><\/a><span style=\"font-weight: 400;\">. The framework is capable of leveraging Swagger annotations.<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">In this document, we focus on the core annotations that impact the 42Crunch audit score and therefore allow us to generate a powerful allowlist to protect your APIs.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">This is not a beginners guide to Springfox: if you&#8217;ve never used Springfox before, please start by following <\/span><a href=\"https:\/\/www.baeldung.com\/swagger-2-documentation-for-spring-rest-api\"><span style=\"font-weight: 400;\">this tutorial.<\/span><\/a><\/p>\n<h2>OAS Security Definitions<\/h2>\n<p><span style=\"font-weight: 400;\">Over 30% of the audit score is based on security definitions and how they are applied. Security definitions define how the API is secured: <\/span><i><span style=\"font-weight: 400;\">basicauth<\/span><\/i><span style=\"font-weight: 400;\">, <\/span><i><span style=\"font-weight: 400;\">api key<\/span><\/i><span style=\"font-weight: 400;\"> and <\/span><i><span style=\"font-weight: 400;\">OAuth2<\/span><\/i><span style=\"font-weight: 400;\"> are the three authentication types supported by the specification at this time.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">We will explain how to add an API key definition and then an OAuth2 definition, which are the most commonly used ones.<\/span><\/p>\n<h3>Using API keys<\/h3>\n<p>Our goal is to add the following security definition to our OAS document: in this case, we have an API key which is passed in a header called x-access-token.<\/p>\n<pre><code class=\"language-json\"> &quot;securityDefinitions&quot;: {\n        &quot;access-token&quot;: {\n            &quot;type&quot;: &quot;apiKey&quot;,\n            &quot;in&quot;: &quot;header&quot;,\n            &quot;name&quot;: &quot;x-access-token&quot;,\n            &quot;description&quot;: &quot;Most operations need to user token retrieved calling \/api\/login&quot;\n        }\n    }\n<\/code><\/pre>\n<p>We first need to add a <strong>securityScheme<\/strong> to the API Docket definition, as follows:<\/p>\n<pre data-line=\"12\"><code class=\"language-java\"> @Bean\npublic Docket apiDocket() {\n   return new Docket(DocumentationType.SWAGGER_2)\n\t       .select()\n\t       .apis(RequestHandlerSelectors.basePackage(&quot;com.xliic&quot;))\t\n\t       .paths(PathSelectors.any())\n\t       .build()\n\t       .apiInfo(getApiInfo())\n\t       .produces(DEFAULT_PRODUCES_AND_CONSUMES)\n\t       .consumes(DEFAULT_PRODUCES_AND_CONSUMES)\n\t       .useDefaultResponseMessages(false)\n\t       .securitySchemes(securitySchemes()))\n\t       .enableUrlTemplating(false)\n\t       .host(&quot;apis.xliic.com&quot;)\n\t       .protocols(Stream.of(&quot;https&quot;).collect(toSet()));\n}\n<\/code><\/pre>\n<p><span style=\"font-weight: 400;\">The security scheme operation compiles the list of security definitions that can be used in the API. Let&#8217;s start by adding a simple API key definition. <\/span><span style=\"font-weight: 400;\">We first declare the API key scheme:<\/span><\/p>\n<pre><code class=\"language-java\">\nprivate ApiKey apikeyScheme() {\n\t    return new ApiKey(&quot;access-token&quot;, &quot;x-access-token&quot;, &quot;header&quot;);\n\t}\n<\/code><\/pre>\n<p><span style=\"font-weight: 400;\">We then add this scheme to a list of schemes. The <\/span><span style=\"font-weight: 400;\">securitySchemes<\/span><span style=\"font-weight: 400;\"> on the Docket configuration expects a list of security schemes, which you can build as follows:<\/span><\/p>\n<pre data-line=\"4\"><code class=\"language-java\">\nprivate ArrayList securitySchemes () {\n    ArrayList secList = Lists.newArrayList();\n    &lt;strong&gt;secList.add(apikeyScheme());&lt;\/strong&gt;\t\t\n    return secList;\n}\n<\/code><\/pre>\n<p>The resulting OpenAPI definition looks like this:<\/p>\n<pre><code class=\"language-json\">&quot;securityDefinitions&quot;: {\n    &quot;access-token&quot;: {\n      &quot;type&quot;: &quot;apiKey&quot;,\n      &quot;name&quot;: &quot;x-access-token&quot;,\n      &quot;in&quot;: &quot;header&quot;\n    }\n  },<\/code><\/pre>\n<h3>Using OAuth as authentication scheme<\/h3>\n<p><span style=\"font-weight: 400;\">If our API is using an access token generated through OAuth, we can describe it using an OAuth scheme object.<\/span><\/p>\n<pre data-line=\"3\"><code class=\"language-java\">private OAuth oauthScheme() {\n     GrantType grantType = \n\t    new AuthorizationCodeGrant( \n\t    \tnew TokenRequestEndpoint(Constants.OAUTH_SERVER + &quot;\/authorize&quot;, &quot;CLIENT_ID&quot;, &quot;CLIENT_SECRET&quot;), \n\t    \tnew TokenEndpoint(Constants.OAUTH_SERVER + &quot;\/token&quot;, &quot;oauthtoken&quot;));\n\t    OAuth oauth = new OAuth (&quot;oauth&quot;, Arrays.asList(scopes()), Arrays.asList(grantType));\n     return oauth;\n} <\/code><\/pre>\n<p>In this function, we declare the OAuth grant type (here AuthorizationCodeGrant) including the authorization and token endpoints. If scopes are associated, they are defined in an array.<\/p>\n<pre><code class=\"language-java\">private AuthorizationScope[] scopes() {\n\t    AuthorizationScope[] scopes = { \n\t      new AuthorizationScope(&quot;read&quot;, &quot;for read operations&quot;), \n\t      new AuthorizationScope(&quot;write&quot;, &quot;for write operations&quot;), \n\t      new AuthorizationScope(&quot;delete&quot;, &quot;for delete operations&quot;) };\n\t    return scopes;\n\t}\n<\/code><\/pre>\n<p><span style=\"font-weight: 400;\">Note that the mandatory CLIENT_ID, CLIENT_SECRET, and OAuth token information are used as part of the Swagger UI rendering (they are not used in the OpenAPI file itself).<\/span><\/p>\n<p><span style=\"font-weight: 400;\">The corresponding definition within the OpenAPI definition is as follows:<\/span><\/p>\n<pre><code class=\"language-json\">\n&quot;securityDefinitions&quot;: {\n    &quot;oauth&quot;: {\n      &quot;type&quot;: &quot;oauth2&quot;,\n      &quot;authorizationUrl&quot;: &quot;https:\/\/oauth.acme.com\/authorize&quot;,\n      &quot;tokenUrl&quot;: &quot;https:\/\/oauth.acme.com\/token&quot;,\n      &quot;flow&quot;: &quot;accessCode&quot;,\n      &quot;scopes&quot;: {\n        &quot;read&quot;: &quot;for read operations&quot;,\n        &quot;write&quot;: &quot;for write operations&quot;,\n        &quot;delete&quot;: &quot;for delete operations&quot;\n      }\n    }\n  }<\/code><\/pre>\n<p><span style=\"font-weight: 400;\">Should you want to use both the APIKey and OAuth security definitions, simply add them both to the declaration, like this:<\/span><\/p>\n<pre><code class=\"language-java\">private ArrayList securitySchemes () {\n   \/\/ Add the two security definitions to a single list\n   ArrayList secList = Lists.newArrayList();\n   secList.add(apikeyScheme());\n   secList.add(oauthScheme());\n\t\t\n   return secList;\n}\n<\/code><\/pre>\n<h2><b>Applying Security<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">Once you have defined the security schemes you will have for your service (API), we can now define how to apply them over it. In our example in Part 1, we defined both schemes: API Key and OAuth, and according to the OAS specification, we can inject the schemas according to our needs, we can let the API with a global security schema, or we can have it defined using a security granularity by resource.\u00a0<\/span><\/p>\n<h3><b>Applying security at API level<\/b><\/h3>\n<p><span style=\"font-weight: 400;\">In order to define the global authentication scheme, you need to add the respective <strong>authorizations<\/strong> annotation at the controller level, as the following example:<\/span><\/p>\n<pre><code class=\"language-java\">\n@RestController\n@RequestMapping(&quot;\/v2&quot;)\n@Api(value = &quot;Set of endpoints for Creating, Retrieving, Updating and Deleting of Persons.&quot;, authorizations = {\n@Authorization(value = &quot;access-token&quot;) })\npublic class PersonController {\n<\/code><\/pre>\n<p><span style=\"font-weight: 400;\">This code snippet sets the global security scheme for this API to be\u00a0 <\/span><em><span style=\"font-weight: 400;\">access-token<\/span><\/em><span style=\"font-weight: 400;\">.<\/span><\/p>\n<h3><b>Applying security at operation level<\/b><\/h3>\n<p><span style=\"font-weight: 400;\">You may need to define a security scheme at the resource level, in other words, you can say:\u00a0<\/span><\/p>\n<ul>\n<li><span style=\"font-weight: 400;\">API MyAPI<\/span>\n<ul>\n<li><span style=\"font-weight: 400;\">\/customers<\/span>\n<ul>\n<li><span style=\"font-weight: 400;\">GET : Use APIKey<\/span><\/li>\n<li><span style=\"font-weight: 400;\">POST: Use OAuth2<\/span><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">To achieve this, you need to add the <strong>authorizations<\/strong> annotation at the API operation level, like this:\u00a0<\/span><\/p>\n<pre><code class=\"language-java\">\n@RequestMapping(method = RequestMethod.GET, path = &quot;\/person\/{id}&quot;, produces = MediaType.APPLICATION_JSON_VALUE)\n@ApiOperation(nickname = &quot;getPersonByID&quot;, value = &quot;Retrieve Person by id&quot;, notes = &quot;Returns a specific person by their identifier. 404 if does not exist.&quot;, response = Person.class,\n  authorizations = {\n     @Authorization(value = &quot;access-token&quot;) })\n<\/code><\/pre>\n<p><span style=\"font-weight: 400;\">Similarly, you can specify OAuth2 as the required security scheme for another operation, for example the DELETE operation.\u00a0<\/span><\/p>\n<pre><code class=\"language-java\">\n@RequestMapping(method = RequestMethod.DELETE, path = &quot;\/person\/{id}&quot;)\n@ApiOperation(value = &quot;Delete Person by id&quot;, notes = &quot;Deletes a person from the system. 404 if the person&#039;s identifier is not found.&quot;, \n authorizations = {\n    @Authorization(value=&quot;oauth&quot;,scopes = {@AuthorizationScope(scope=&quot;delete&quot;,description = &quot;Delete person&quot;)})})<\/code><\/pre>\n<h2>42Crunch Extensions Support<\/h2>\n<p><span style=\"font-weight: 400;\">It is possible to add custom OAS extensions via Springfox to your definitions. This can be used to inject 42Crunch specific extensions, as illustrated below:<\/span><\/p>\n<pre><code class=\"language-java\">\n@RequestMapping(method = RequestMethod.POST, path = &quot;\/login&quot;, produces = MediaType.APPLICATION_JSON_VALUE)\n@ApiOperation(value = &quot;Create a person&quot;, notes = &quot;API login &quot;, extensions = {\n@Extension(properties = { @ExtensionProperty(name = &quot;x-42c-no-authentication&quot;, value = &quot;true&quot;) })\n})\n\npublic Person login(\n@RequestParam @Min(10) @Max(50) @Pattern(regexp = Constants.EMAIL_REGEX) String email,\n@RequestParam @Min(10) @Max(50) @Pattern(regexp = Constants.PASSWORD_REGEX) String password)\n<\/code><\/pre>\n<p>This is the resulting OAS snippet:<\/p>\n<pre><code class=\"language-java\">\n&quot;paths&quot;:{\n &quot;\/login&quot;:{\n &quot;post&quot;:{\n   ...\n   &quot;deprecated&quot;:false,\n   &quot;x-42c-no-authentication&quot;:&quot;true&quot;\n}\n<\/code><\/pre>\n<p><span style=\"font-weight: 400;\">This OAS extension allows you to disable authentication checks from the 42Crunch Security Audit on operations in your API that do not need authentication, for example login or register operations used to authenticate.<\/span><br \/>\n<b><\/b><\/p>\n<h2><b>Conclusion\u00a0<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">The approach presented in this post will let you generate rich, hardened OpenAPI definitions and remediate issues reported by the <\/span><a href=\"https:\/\/42crunch.com\/api-security-audit\/\"><span style=\"font-weight: 400;\">42Crunch Security Audit<\/span><\/a><span style=\"font-weight: 400;\">. Adding annotations also brings the benefit of full synchronization between the code and the API contract, which can then be used to test and protect your APIs using additional 42Crunch platform services.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">References:<\/span><\/h3>\n<pre><a href=\"https:\/\/medium.com\/future-vision\/the-great-authenticators-of-rest-738e81109331\"><span style=\"font-weight: 400;\">https:\/\/medium.com\/future-vision\/the-great-authenticators-of-rest-738e81109331<\/span><\/a><\/pre>\n","protected":false},"excerpt":{"rendered":"<p>Spring Boot is a popular framework to build applications and APIs. Leveraging the Springfox project and code annotations, developers can generate OAS files with a high 42Crunch Security Audit score. What is the 42Crunch Security Audit? The 42Crunch Security Audit is one of 3 services from the 42Crunch API Security Platform: it consumes OpenAPI (Swagger) [&hellip;]<\/p>\n","protected":false},"author":11,"featured_media":11327,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_seopress_robots_primary_cat":"none","_seopress_titles_title":"Creating High Quality OAS Definitions with Springfox - Part 1","_seopress_titles_desc":"Leveraging the Springfox project and code annotations, developers can generate OAS (OpenAPI Specification) files with a high API audit score.","_seopress_robots_index":"","site-sidebar-layout":"default","site-content-layout":"default","ast-site-content-layout":"","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"disabled","ast-hfb-above-header-display":"disabled","ast-hfb-below-header-display":"disabled","ast-hfb-mobile-header-display":"disabled","site-post-title":"disabled","ast-breadcrumbs-content":"disabled","ast-featured-img":"disabled","footer-sml-layout":"disabled","theme-transparent-header-meta":"default","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""}},"footnotes":""},"categories":[6,26],"tags":[16,25],"_links":{"self":[{"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/posts\/7910"}],"collection":[{"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/users\/11"}],"replies":[{"embeddable":true,"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/comments?post=7910"}],"version-history":[{"count":0,"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/posts\/7910\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/media\/11327"}],"wp:attachment":[{"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/media?parent=7910"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/categories?post=7910"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/staging2022.42crunch.com\/wp-json\/wp\/v2\/tags?post=7910"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}