Skip to content
This repository was archived by the owner on Jun 13, 2025. It is now read-only.

WIP: Identities #79

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

WIP: Identities #79

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
436628a
fix outdated references in the contribution.md (#51)
sebbader Sep 23, 2022
f7d182e
Update CHANGELOG.md
ssteinbuss Sep 23, 2022
702143f
Changing structure of Communication package
ssteinbuss Sep 28, 2022
cd16a2a
Update CommunicationGuide.md
ssteinbuss Sep 28, 2022
6a45b74
add more foundational standards
sebbader-sap Sep 29, 2022
d42f16e
Merge pull request #68 from sebbader-sap/55-update-strcuture-communic…
anilturkmayali Oct 6, 2022
082dcbe
First identity token draft
milux Oct 20, 2022
5b97d9e
Added mandatory claims section
milux Nov 3, 2022
44c777c
57 common entities in a data space (#59)
ssteinbuss Nov 10, 2022
b8df07c
Branch for jim (#82)
ssteinbuss Nov 10, 2022
693207e
Merge branch '55-update-strcuture-communication' into 63-communicatio…
ssteinbuss Nov 10, 2022
fdf6836
Changes based on comments
milux Jun 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions Communication/Identities/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Identities

Connector identities according to this specification are typically represented by some sort of token.
This token contains statements about properties of the connector ("claims"), like its membership in one or more data spaces.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and it's trust level as well as it's assurance level (e.g., trust level 1 for base connector with assurance level 1 for a self-assessment).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please tell the exact claim names for the token.

In order to establish trust via these tokens, two requirements have to be met:

- Security-relevant claims within the token, or the entire token as a whole, MUST be signed by one or more trusted entities.
- There MUST exist a sound mechanism that enables a connector to proof ownership over the tokens or claims issued for this particular connector.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this means, the token belongs to the connector that is trying to establish a connection? Should we mention binding the base identity/certificate to the token?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We would also have to somehow signal the used version of a DAT to the other connector. This is facilitated by the version encoded in the issuer URL at the moment. Should we consider requirements for that?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestions welcome. (:

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO: Talk with @bellebaum about versioning schema and whether this makes sense.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this means, the token belongs to the connector that is trying to establish a connection? Should we mention binding the base identity/certificate to the token?

I think the point right below this one is supposed to express exactly this, but making the channel binding (That's what some authentication mechanisms call it) explicit may be less subtle.

We would also have to somehow signal the used version of a DAT to the other connector. This is facilitated by the version encoded in the issuer URL at the moment. Should we consider requirements for that?

As far as I am aware, there is as of now no versioning scheme for the DAT, just for the DAPS. I feel like the more appropriate thing to do is to ensure the DAT claims stay backwards compatible, and update the verification routines to include checks on newer included information.

If applicable, some sort of critical array can also be defined marking certain keys in the DAT as critical. The idea here would be that any connector MUST reject DATs for which it does not know how to handle/check a certain claim. This should of course only be done with claims adding additional proofs of applicability to the connector (like new forms of binding). C.t. https://www.rfc-editor.org/rfc/rfc5280#section-4.2

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If applicable, some sort of critical array can also be defined marking certain keys in the DAT as critical. The idea here would be that any connector MUST reject DATs for which it does not know how to handle/check a certain claim. This should of course only be done with claims adding additional proofs of applicability to the connector (like new forms of binding). C.t. https://www.rfc-editor.org/rfc/rfc5280#section-4.2

Interesting idea. This is however not yet part of any existing OAuth-related standard, is it? If we do this, should we explain it here in the IDS-G as well?

Specifically, any connector implementing a corresponding validation mechanism MUST be capable of identifying and rejecting tokens that have not been issued for the respective peer connector(s).

## X.509/OAuth2-Token-based Identities
Identities of this kind are established via X.509 certificates and corresponding private keys.
The tokens used to provide identity information to other peers are regular OAuth2 JSON Web Tokens (JWTs).
In the IDS context, the OAuth2 server issuing such tokens is called a "Dynamic Attribute Provisioning Server", or DAPS for short.

### Format and Signature
The format of Dynamic Attribute Tokens (DATs) and the interaction between DAPS and connector are described in the [DAPS Specification](../../Components/IdentityProvider/DAPS/README.md).
As DATs are JWTs with a (RSA) signature, the issuing DAPS acts as a central, trusted entity, which also manages the contained claims about the connector.

### Token Ownership Verification
The ownership over DAPS tokens is proven to peer connectors via ownership of a private key used for transport encryption, typically an RSA key belonging to a X.509 certificate.

For typical TLS encryption scenarios, the respective approach via the `transportCertsSha256` claim is documented in the [DAPS Token Response Specification](../../Components/IdentityProvider/DAPS/README.md#token-response).
This claim is specified to contain an array of SHA256 fingerprints as hex-encoded strings, or a single such hash as a string.
As per that specification, DAPS implementations SHOULD allow the `transportCertsSha256` claim to be overridden with a dynamic value when requesting the DAT.
For non-TLS encrypted communication channels, hashes of corresponding public keys or their very values (e.g. for short representations of EC keys) MAY be used instead.

For verification, a connector MUST check that the fingerprint of its peer's certificate is contained in - or equal to - the value of the `transportCertsSha256` claim.
6 changes: 3 additions & 3 deletions Components/IdentityProvider/DAPS/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,8 @@ Contains the public keys of the used transport certificates, hashed using SHA256
The identifying X509 certificate should not be used for the communication encryption.
Therefore, the receiving party needs to connect the identity of a connector by relating its hostname (from the communication encryption layer) and the used private/public key pair,
with its IDS identity claim of the DAT.
The public transportation key must be one of the `transportCertsSha256` values.
Otherwise, the receiving connector must expect that the requesting connector is using a false identity claim.
The public transportation key MUST be one of the `transportCertsSha256` values.
Otherwise, the receiving connector MUST expect that the requesting connector is using a false identity claim.
In general, this claim holds an Array of Strings, but it may optionally hold a single String instead if the Array would have exactly one element.

* **extendedGuarantee**
Expand Down Expand Up @@ -189,7 +189,7 @@ DAPS implementations are advised to explicitly white-list any requestable claims
and to check requested values as appropriate.

To allow clients to specify their own transport certificates,
DAPS implementations should support specifying values for the **transportCertsSha256** claim.
DAPS implementations SHOULD support specifying values for the **transportCertsSha256** claim.

### Example

Expand Down