From a07b6a54dd030eacd08b69b4dd6d7c99e0229655 Mon Sep 17 00:00:00 2001 From: MartenMeijboom98 Date: Wed, 26 Feb 2025 08:18:48 +0100 Subject: [PATCH] Add OAuth to spec: first version Signed-off-by: MartenMeijboom98 --- ...plementation-using-oauth-components.drawio | 63 +++++++ ...implementation-using-oauth-sequence.drawio | 130 ++++++++++++++ ...plementation-using-oauth-components.drawio | 72 ++++++++ ...implementation-using-oauth-sequence.drawio | 164 ++++++++++++++++++ docs/appendix/optional-security-measures.md | 43 +++++ ...-implementation-using-oauth-components.svg | 4 + ...ly-implementation-using-oauth-sequence.svg | 4 + ...-implementation-using-oauth-components.svg | 4 + ...le-implementation-using-oauth-sequence.svg | 4 + 9 files changed, 488 insertions(+) create mode 100644 diagrams/example-dso-only-implementation-using-oauth-components.drawio create mode 100644 diagrams/example-dso-only-implementation-using-oauth-sequence.drawio create mode 100644 diagrams/example-full-implementation-using-oauth-components.drawio create mode 100644 diagrams/example-full-implementation-using-oauth-sequence.drawio create mode 100644 docs/appendix/optional-security-measures.md create mode 100644 docs/assets/images/example-dso-only-implementation-using-oauth-components.svg create mode 100644 docs/assets/images/example-dso-only-implementation-using-oauth-sequence.svg create mode 100644 docs/assets/images/example-implementation-using-oauth-components.svg create mode 100644 docs/assets/images/example-implementation-using-oauth-sequence.svg diff --git a/diagrams/example-dso-only-implementation-using-oauth-components.drawio b/diagrams/example-dso-only-implementation-using-oauth-components.drawio new file mode 100644 index 00000000..f4aeae67 --- /dev/null +++ b/diagrams/example-dso-only-implementation-using-oauth-components.drawio @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/diagrams/example-dso-only-implementation-using-oauth-sequence.drawio b/diagrams/example-dso-only-implementation-using-oauth-sequence.drawio new file mode 100644 index 00000000..4d494976 --- /dev/null +++ b/diagrams/example-dso-only-implementation-using-oauth-sequence.drawio @@ -0,0 +1,130 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/diagrams/example-full-implementation-using-oauth-components.drawio b/diagrams/example-full-implementation-using-oauth-components.drawio new file mode 100644 index 00000000..4a8223b6 --- /dev/null +++ b/diagrams/example-full-implementation-using-oauth-components.drawio @@ -0,0 +1,72 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/diagrams/example-full-implementation-using-oauth-sequence.drawio b/diagrams/example-full-implementation-using-oauth-sequence.drawio new file mode 100644 index 00000000..e46261b2 --- /dev/null +++ b/diagrams/example-full-implementation-using-oauth-sequence.drawio @@ -0,0 +1,164 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/appendix/optional-security-measures.md b/docs/appendix/optional-security-measures.md new file mode 100644 index 00000000..b708e3f8 --- /dev/null +++ b/docs/appendix/optional-security-measures.md @@ -0,0 +1,43 @@ + + +# Optional security measures + +When implementing the specification, it is recommended to add additional security measures on top of the described in [message signing mechanism](message-transport-mechanism.md). +This has the main benefit of adding sender verification before actually processing a message, offering better protection against certain attacks, such as DOS style attacks. + +## OAuth 2.0 + +OAuth 2.0 is seen as the default additional measure that should be used when implementing the specification. +On top of being the industry standard, it provides a relatively simple, low-maintenance and flexible way to add endpoint security. +OAuth 2.0 also suits the flexibility that Shapeshifter aims to support. + +It can be added as an optional component to the system, with each participant deciding for themselves whether it is worthwhile to implement. +You can imagine a system where the DSO has configured an OAuth provider, while a smaller AGR might rely solely on the message signing mechanism, since the DSO is much more likely to be targeted by malicious actors. +This distinction can then be integrated into the Discovery phase, where the DSO can advertise that it requires OAuth 2.0 for communication. + +It is recommended to use the `client_credentials` grant type, as it is the most suitable for machine-to-machine communication. +Each party would get an authorized client in the OAuth provider of the parties they are communicating with. + +More information about OAuth 2.0 can be found here +* OAuth 2.0 specification: https://oauth.net/2/ +* OAuth 2.0 providers: https://oauth.net/code/ + +### Example system - both parties using OAuth 2.0 + +A system using ShapeShifter and OAuth 2.0 could look like this. +![components in a system using oauth](../assets/images/example-implementation-using-oauth-components.svg "Example") + +With the following sequence when the DSO sends a FlexRequest to the AGR. +![example system using oauth](../assets/images/example-implementation-using-oauth-sequence.svg "Example") + +### Example system - Only DSO using OAuth 2.0 + +A system where only the DSO uses OAuth 2.0 could look like this. +![components in a system using oauth](../assets/images/example-dso-only-implementation-using-oauth-components.svg "Example") + +With the following sequence when the DSO sends a FlexRequest to the AGR. +![example system using oauth](../assets/images/example-dso-only-implementation-using-oauth-sequence.svg "Example") diff --git a/docs/assets/images/example-dso-only-implementation-using-oauth-components.svg b/docs/assets/images/example-dso-only-implementation-using-oauth-components.svg new file mode 100644 index 00000000..21eb2879 --- /dev/null +++ b/docs/assets/images/example-dso-only-implementation-using-oauth-components.svg @@ -0,0 +1,4 @@ + + + +
DSO Shapeshifter implementation
AGR Shapeshifter implementation
DSO OAuth provider
Verify provided token
Request token
FlexMessage communication
without OAuth
FlexMessage communication
including token in header
 \ No newline at end of file diff --git a/docs/assets/images/example-dso-only-implementation-using-oauth-sequence.svg b/docs/assets/images/example-dso-only-implementation-using-oauth-sequence.svg new file mode 100644 index 00000000..062ae3dc --- /dev/null +++ b/docs/assets/images/example-dso-only-implementation-using-oauth-sequence.svg @@ -0,0 +1,4 @@ + + + +
DSO Shapeshifter implementation
AGR Shapeshifter implementation
Verify message
DSO OAuth Provider
Request token
Return token
Send FlexRequest
Return 200 OK
Send FlexRequestResponse,
including token in header
Verify token
Return verification result
Return 200 OK
 \ No newline at end of file diff --git a/docs/assets/images/example-implementation-using-oauth-components.svg b/docs/assets/images/example-implementation-using-oauth-components.svg new file mode 100644 index 00000000..274ca51d --- /dev/null +++ b/docs/assets/images/example-implementation-using-oauth-components.svg @@ -0,0 +1,4 @@ + + + +
DSO Shapeshifter implementation
AGR Shapeshifter implementation
DSO OAuth provider
AGR OAuth provider
Verify provided token
Verify provided token
Request token
FlexMessage communication
including tokens in header
 \ No newline at end of file diff --git a/docs/assets/images/example-implementation-using-oauth-sequence.svg b/docs/assets/images/example-implementation-using-oauth-sequence.svg new file mode 100644 index 00000000..6f709c29 --- /dev/null +++ b/docs/assets/images/example-implementation-using-oauth-sequence.svg @@ -0,0 +1,4 @@ + + + +
DSO Shapeshifter implementation
AGR Shapeshifter implementation
Verify message
DSO OAuth Provider
AGR OAuth Provider
Request token
Return token
Send FlexRequest,
including token in header
Verify token
Return verification result
Return 200 OK
Request token
Return token
Send FlexRequestResponse,
including token in header
Verify token
 \ No newline at end of file