{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"3"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"7d61bc92-e99b-4278-9b73-5b1494222d05"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"873bdce3-d14b-4a4c-80c5-35b3186f05b6"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Cross-Site Request Forgery (CSRF)","type":"text"}]},{"type":"paragraph","content":[{"text":"Cross Site Request Forgery (CSRF or XSRF) allows an attacker to forge a malicious cross origin write request to a targeted web application that invokes sensitive functions on behalf of an authenticated user. Forged requests are usually represented in the form of a hyperlink, zero-width image, in-page Javascript request, or auto-submitted form post. Some form of social engineering (e.g. a URL to a website in a phishing email), is used by the attacker to trick a victim into unknowingly submitting such a request.","type":"text"}]},{"type":"paragraph","content":[{"text":"CSRF exploits existing user session identifiers with ambient authority that are provided automatically by the browser during each request, e.g. cookies such as the ","type":"text"},{"text":"JSESSIONID","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"shib_idp_session","type":"text","marks":[{"type":"code"}]},{"text":", or the IP address of the victim. As the attacker has no way of determining/reading the results of that request, useful requests are limited to state-changing, non-idempotent (has side effects) actions that the user is allowed to perform.","type":"text"}]},{"type":"paragraph","content":[{"text":"Despite the fact the IdP does not itself represent the end resource the user will ultimately interact with, the IdP does present some user flows that could be manipulated by an attacker. For example, of particular importance is the prevention of login CSRF [2], where the attacker attempts to trick the victim into logging in as themselves (the attacker), with the aim then of:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tracking a victim's activity because it is happening in their own session.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tricking the victim into entering sensitive information into an attacker's session/account e.g. bank account details etc.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Consequently, the IdP now employs a synchroniser token pattern [1] CSRF defense. Abstractly, a cryptographically strong string token is generated and attached to the user session by the IdP each time a view is rendered and embedded into HTML forms in the view. When the form is submitted by the user back to the IdP, the IdP verifies that the token in the request matches that stored against the user's session. If they do not match, it is assumed the request was forged - the attacker would not have access to this token, and should not be able to ‘guess’ it.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CSRF attacks on the IdP","type":"text"}]},{"type":"paragraph","content":[{"text":"Performing a CSRF attack on the IdP is difficult even without specialised CSRF defence. Firstly, for the most part, the IdP does not have stable, static, endpoints listening for requests (other than for certain RESTFul admin functions). Instead, because of the underlying use of Spring Web Flow, the conversation the browser is having with the IdP must be at the correct flow state to accept a HTTP POST/GET request with a given set of manipulatable parameters. For example, using the password authentication flow, the attack opportunity only occurs when the user has progressed the flow to the ","type":"text"},{"text":"DisplayUsernamePasswordPage","type":"text","marks":[{"type":"code"}]},{"text":" view-state (login page) and no further. It is fairly unlikely, although not impossible, a user would stop at this point and navigate to a malicious website to be tricked into submitting an attacker's username and password back to the IdP.","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition, in order for Spring Web Flow to resume the flow conversation at the correct state to accept the request, the attacker must guess a suitable execution key. That said, a login would typically occur early in the conversation for a given protocol/binding, and would be fairly predictable/guessable. Finally, as with all login CSRF attacks, the attacker would need an account within the IdP’s authentication source.","type":"text"}]},{"type":"paragraph","content":[{"text":"However difficult, CSRF attacks are still possible, and these points do not detract from a robust CSRF defense by default.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"New installations","type":"text"}]},{"type":"paragraph","content":[{"text":"New installations will have CSRF protection enabled by default. This is configured by a property in ","type":"text"},{"text":"%{idp.home}/conf/idp.properties","type":"text","marks":[{"type":"em"}]},{"text":" which globally turns on CSRF protection:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yml"},"content":[{"text":"# Enable cross-site request forgery mitigation for views. \nidp.csrf.enabled = true","type":"text"}]},{"type":"paragraph","content":[{"text":"When enabled, all view-states will automatically be protected ","type":"text"},{"text":"unless","type":"text","marks":[{"type":"strong"}]},{"text":" explicitly excluded; see ","type":"text"},{"text":"excluding-views","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":". This means any custom view-state added to new or existing flows of the IdP will also be protected, and any submissions back to the IdP will require an anti-CSRF token; see ","type":"text"},{"text":"adding-csrf-token","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Upgrades","type":"text"}]},{"type":"paragraph","content":[{"text":"On upgrade, user views and IdP properties files are not overwritten by the installer. Consequently, in an upgraded state from older versions of the IdP without this feature e.g. v3, CSRF protection is disabled by default, and views will not have the velocity template content required to add anti-CSRF tokens.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Enabling After Upgrade","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The “*.idpnew*” files created after upgrading contain a fresh copy of the IdP properties and views with CSRF protection enabled. These could be referenced against your current views to highlight the changes required to enable CSRF.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"To enable CSRF protection the following property should be added to ","type":"text"},{"text":"%{idp.home}/conf/idp.properties","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yml"},"content":[{"text":"# Enable cross-site request forgery mitigation for views. \nidp.csrf.enabled = true","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Caution","type":"text"}]},{"type":"paragraph","content":[{"text":"Enabling CSRF protection and restarting the IdP without modifying required views will break authentication flows.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"paragraph","content":[{"text":"Once enabled, the following views need to be updated to include the anti-CSRF token inside HTML forms; see ","type":"text"},{"text":"adding-csrf-token","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":" for more information on injecting the tokens.","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","width":1800.0,"localId":"1dfbe94e-8af6-4977-9155-859819fbab97"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[413.0]},"content":[{"type":"paragraph","content":[{"text":"View","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[197.0]},"content":[{"type":"paragraph","content":[{"text":"Number of Forms","type":"text"},{"type":"hardBreak"},{"text":"(in distribution)","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[1183.0]},"content":[{"type":"paragraph","content":[{"text":"Others","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[413.0]},"content":[{"type":"paragraph","content":[{"text":"views/login.vm","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[197.0]},"content":[{"type":"paragraph","content":[{"text":"1","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1183.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[413.0]},"content":[{"type":"paragraph","content":[{"text":"views/intercept/attribute-release.vm","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[197.0]},"content":[{"type":"paragraph","content":[{"text":"1","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1183.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[413.0]},"content":[{"type":"paragraph","content":[{"text":"views/intercept/impersonate.vm","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[197.0]},"content":[{"type":"paragraph","content":[{"text":"1","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1183.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[413.0]},"content":[{"type":"paragraph","content":[{"text":"views/intercept/terms-of-use.vm","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[197.0]},"content":[{"type":"paragraph","content":[{"text":"2","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1183.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[413.0]},"content":[{"type":"paragraph","content":[{"text":"views/admin/unlock-keys.vm","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[197.0]},"content":[{"type":"paragraph","content":[{"text":"1","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1183.0]},"content":[{"type":"paragraph"}]}]}]},{"type":"paragraph","content":[{"text":"The IdP contains a number of other views from which CSRF has been excluded by configuration; see ","type":"text"},{"text":"excluding-views","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":" for more information on excluding views.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Token Scope ","type":"text"},{"text":"5.2","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"paragraph","content":[{"text":"By default, a new token is generated for each view rendered. This has proven to cause problems with browsers that pre-fetch URLs and mis-handle the results by associating the wrong CSRF token with the eventual form submisson. V5.2+ supports the generatioon of a single token per flow conversation, which works better on these browsers. This is off by default but can be enabled by setting the new property ","type":"text"},{"text":"idp.csrf.token.perFlow","type":"text","marks":[{"type":"strong"}]},{"text":" to true.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"excluding"},"legacyAnchorId":{"value":"Cross-SiteRequestForgery(CSRF)Protection-excluding"}},"macroMetadata":{"macroId":{"value":"c751dc29-691f-4f17-9730-fccc7f0a0766"},"schemaVersion":{"value":"1"},"title":"Anchor"}},"localId":"bf8f1380-3d3d-4aac-ba1b-36e912a4aadb"}},{"text":"Excluding Views","type":"text"}]},{"type":"paragraph","content":[{"text":"Sometimes views do not require CSRF protection, for example when they do not submit sensitive information back to the IdP. Other times, views are involved in user flows that cannot meaningfully benefit from ‘IdP led’ CSRF protection, for example, an external authentication servlet that reaches outside of the IdP and can include arbitrary user interactions. In either case, views can be excluded by annotating the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element with the following CSRF annotation attribute in the corresponding flow XML configuration file.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"CSRF excluded annotation attribute","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, to exclude an external authentication servlet:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example: exclude external authentication view","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n ...\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"adding"},"legacyAnchorId":{"value":"Cross-SiteRequestForgery(CSRF)Protection-adding"}},"macroMetadata":{"macroId":{"value":"84305d75-91be-4b88-8574-9fc33e73e5f8"},"schemaVersion":{"value":"1"},"title":"Anchor"}},"localId":"604f1f2f-e7f2-4aca-9b19-8aa10bf44dc9"}},{"text":"Injecting anti-CSRF tokens into views","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"HTML forms","type":"text"}]},{"type":"paragraph","content":[{"text":"HTML forms within protected views must include a hidden input field with both the anti-CSRF token (value attribute) and the HTTP parameter name (name attribute). The IdP comes with a velocity template fragment which adds the anti-CSRF token into a form if present. To add it, simply place the following velocity script element ","type":"text"},{"text":"inside","type":"text","marks":[{"type":"strong"}]},{"text":" the form where it is required:","type":"text"}]},{"type":"codeBlock","content":[{"text":"#parse(\"csrf/csrf.vm\")","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, inside the login form:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"If protection is enabled, the token will then be rendered similar to the output below:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":50.0},"content":[{"type":"media","attrs":{"width":1526,"id":"176c0b8e-391e-49f1-9af0-235168560e4b","collection":"contentId-3199501137","type":"file","height":74}}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The csrf.vm template can be added (using the #parse directive) safely to forms even if protection is disabled. In these cases, Velocity will not add the token to the form.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Iframe source","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"paragraph","content":[{"text":"Iframes that return control to the IdP in the source attribute also require CSRF tokens unless their parent view-state is excluded from protection. ","type":"text"},{"text":"This is required even in a GET request as Spring Web Flow does not differentiate between GET and POST to initiate or resume flows. ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"These can be added with conditional velocity logic e.g.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"It is unlikely however that iframe usage benefits much from CSRF protection, and most often the view-state can be excluded. That said, the implementer of a custom flow and or view is responsible for determining that.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Token Exposure","type":"text"}]},{"type":"paragraph","content":[{"text":"This will expose the CSRF token in browser network inspectors and possibly server logs. However, it will not display in the navigation bar, and should not appear in browser history/bookmarks. That said, a new token is generated for every GET request to a view, greatly limiting its reply value.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Hyperlinks","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"paragraph","content":[{"text":"For the same reason as the iFrame source above, if CSRF protection is enabled hyperlinks also require the CSRF token. These can be added using the same conditional velocity logic e.g.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"codeBlock","content":[{"text":"TEXT","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Custom Flows","type":"text"}]},{"type":"paragraph","content":[{"text":"If you add a new flow to the IdP, unless excluded (see ","type":"text"},{"text":"excluding-views","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":"), any view-state it contains will automatically be protected from CSRF attacks providing CSRF protection is enabled globally in the IdP's properties file. Hence, the view template of any view-state must also include the anti-CSRF token; see ","type":"text"},{"text":"inject-token","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"To cleanly handle the InvalidCSRFTokenException the IdP throws on a CSRF token mismatch, a global ","type":"text"},{"text":"on-exception","type":"text","marks":[{"type":"code"}]},{"text":" transition must be registered in appropriate flows in addition to a corresponding action/end state. In subflows, this can be added to the list of error events that are reflected back to the parent flow. For example:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Catching a CSRF exception in subflows","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n \n \n \n ...","type":"text"}]},{"type":"paragraph","content":[{"text":"In abstract parent flows, this can be added to the ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"global-transitions","type":"text","marks":[{"type":"code"}]},{"text":" transitioning to a new action state:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Catching a CSRF exception in parent flows","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n \n \n \n\n \n \n \n \n ","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"You are still protected from CSRF attacks even if you do not catch the exception, however, a generic uncaught exception error will be shown to the user instead.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"References","type":"text"}]},{"type":"paragraph","content":[{"text":"1 - ","type":"text"},{"text":"https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.md#synchronizer-token-pattern","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.md#synchronizer-token-pattern"}}]},{"type":"hardBreak"},{"text":"2 - ","type":"text"},{"text":"https://seclab.stanford.edu/websec/csrf/csrf.pdf","type":"text","marks":[{"type":"link","attrs":{"href":"https://seclab.stanford.edu/websec/csrf/csrf.pdf"}}]}]},{"type":"paragraph"}],"version":1}