CAMARA API Design Guide document#441
Merged
rartych merged 11 commits intocamaraproject:mainfrom Apr 17, 2025
Merged
Conversation
Depreciation and links to new documents.
info object section simplification, corrected references
2 tasks
2 tasks
tlohmar
reviewed
Apr 8, 2025
| [Security schemes](https://spec.openapis.org/oas/v3.0.3#security-scheme-object) express security in OpenAPI. | ||
| Security can be expressed for the API as a whole or for each endpoint. | ||
|
|
||
| As specified in [Use of openIdConnect for securitySchemes](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#use-of-openidconnect-for-securityschemes), all CAMARA OpenAPI files must include the following scheme definition, with an adapted `openIdConnectUrl` in its components section. The schema definition is repeated in this document for illustration purposes, the correct format must be extracted from the link above. |
Contributor
There was a problem hiding this comment.
Note, the OpenIdConnect security scheme does not support OAuth Client Credentials off-the-shelf. The OpenIdConnect Discovery Procotol and Spec only supports Authorization Code and Implicit grant types.
Additional text is needed, when CAMARA recommends the support for Client Credentials and CIBA.
tlohmar
reviewed
Apr 8, 2025
| securitySchemes: | ||
| openId: | ||
| type: openIdConnect | ||
| openIdConnectUrl: https://example.com/.well-known/openid-configuration |
Contributor
There was a problem hiding this comment.
Might be good, when the API developing working group gives recommendations on the grant types.
tlohmar
reviewed
Apr 8, 2025
| openIdConnectUrl: https://example.com/.well-known/openid-configuration | ||
| ``` | ||
|
|
||
| The key of the security scheme is arbitrary in OAS, but convention in CAMARA is to name it `openId`. |
Contributor
There was a problem hiding this comment.
The ICM guideline require the usage of openId (see link
Suggested change
| The key of the security scheme is arbitrary in OAS, but convention in CAMARA is to name it `openId`. | |
| The key of the security scheme is arbitrary in OAS, but the required convention in CAMARA is to name it `openId`. | |
tlohmar
reviewed
Apr 8, 2025
| 1. **Simple Management**. | ||
| Securing only the APIs that need to be secure. Any time the more complex solution is made "unnecessarily", it is also likely to leave a hole. | ||
| 2. **HTTPs must be always used**. | ||
| TLS ensures the confidentiality of the transported data and that the server's hostname matches the server's SSL certificate. |
Contributor
There was a problem hiding this comment.
Might be good to refer to certificate validation, not only hostname matiching, e.g. link.
Suggested change
| TLS ensures the confidentiality of the transported data and that the server's hostname matches the server's SSL certificate. | |
| TLS ensures the confidentiality of the transported data and clients should do a full server SSL certificate verification, incl a hostname match. | |
tlohmar
reviewed
Apr 8, 2025
| Securing only the APIs that need to be secure. Any time the more complex solution is made "unnecessarily", it is also likely to leave a hole. | ||
| 2. **HTTPs must be always used**. | ||
| TLS ensures the confidentiality of the transported data and that the server's hostname matches the server's SSL certificate. | ||
| - If HTTP 2 is used to improve performance, you can even send multiple requests over a single connection, this way you will avoid the complete overhead of TCP and SSL on later requests. |
Contributor
There was a problem hiding this comment.
Suggested change
| - If HTTP 2 is used to improve performance, you can even send multiple requests over a single connection, this way you will avoid the complete overhead of TCP and SSL on later requests. | |
| - If HTTP 2 is used to improve performance, you can even send multiple requests over a single connection, this way you will avoid the complete overhead of TCP and SSL on later requests. If HTTP 1.1 is used, usage of _TCP persistent connections_ is recommended to achieve a similar performance. | |
tlohmar
reviewed
Apr 8, 2025
| There are many hashing algorithms that can be really effective for password security, | ||
| for example, PBKDF2, bcrypt and scrypt algorithms. | ||
|
|
||
| 4. **Information must not be exposed in the URLs** |
Contributor
There was a problem hiding this comment.
Suggested change
| 4. **Information must not be exposed in the URLs** | |
| 4. **Sensitive information must not be exposed in the URLs** | |
tlohmar
reviewed
Apr 8, 2025
| 5. **Authentication and authorization must be considered** | ||
| CAMARA uses the authentication and authorization protocols and flows as described in the [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md). | ||
|
|
||
| 6. **Add request time flags should be considered**. |
Contributor
There was a problem hiding this comment.
This does not sound like a security consideration. Is there another section on general considerations?
In principle, the API provider must reject any request without a custom timestamp header, otherwise, the API invoker will never add such a header.
tlohmar
reviewed
Apr 8, 2025
| - This will prevent very basic replay attacks from people trying to hack your system without changing this timestamp. | ||
|
|
||
| 7. **Entry params validation** | ||
| Validates the parameters of the request in the first step before it reaches the application logic. |
Contributor
There was a problem hiding this comment.
Is this about a format check (parameter values correctly formatted) or an authorization check (parameter values authorized to be used)?
tlohmar
reviewed
Apr 8, 2025
| ### 6.2. Security definition | ||
|
|
||
| In general, all APIs must be secured to ensure who has access to what and for what purpose. | ||
| CAMARA uses OIDC and CIBA for authentication and consent collection and to determine whether the user has, |
Contributor
There was a problem hiding this comment.
Suggested change
| CAMARA uses OIDC and CIBA for authentication and consent collection and to determine whether the user has, | |
| CAMARA uses | |
| - OIDC and CIBA for authentication and consent collection and to determine whether the user has, e.g. opted out of some API access, | |
| - Client Credentials for authorization in other cases. | |
tlohmar
reviewed
Apr 8, 2025
|
|
||
| In general, all APIs must be secured to ensure who has access to what and for what purpose. | ||
| CAMARA uses OIDC and CIBA for authentication and consent collection and to determine whether the user has, | ||
| e.g. opted out of some API access. |
Contributor
There was a problem hiding this comment.
Suggested change
| e.g. opted out of some API access. |
(appended to the previous line)
tlohmar
reviewed
Apr 8, 2025
Comment on lines
+855
to
+868
| Security requirements of an API are expressed in OpenAPI through [Security Requirement Objects](https://spec.openapis.org/oas/v3.0.3#security-requirement-object). | ||
|
|
||
| The following is an example of how to use the `openId` security scheme defined above as described in [Use of security property](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#use-of-security-property): | ||
|
|
||
| ```yaml | ||
| paths: | ||
| {path}: | ||
| {method}: | ||
| ... | ||
| security: | ||
| - openId: | ||
| - {scope} | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
hmm, this is more a repetition. CAMARA requires the usage of the openIdConnection security scheme in other places. So, what is the additional requirement (see heading)?
Co-authored-by: Kevin Smith <Kevsy@users.noreply.github.com>
Collaborator
|
As the document adopts RFC 2119 conventions, should we not capitalise all relevant uses of "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"? |
Contributor
Author
Contributor
Author
@eric-murray Good point, as RFC2119 was updated I created issue: #447 |
|
|
||
| | **Term** | Description | | ||
| |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | **API** | Application Programming Interface. It is a rule & specification group (code) that applications follow to communicate between them, used as interface among programs developed with different technologies. | |
Collaborator
There was a problem hiding this comment.
It could be more clear with following - 'It is a set of rules and specifications that enable communication between software applications.' against 'It is a rule & specification group (code) that applications follow to communicate between them'
| but if it is necessary it must be hashed to protect the system | ||
| (or minimize damage) even if it is compromised in some hacking attempts. | ||
| There are many hashing algorithms that can be really effective for password security, | ||
| for example, PBKDF2, bcrypt and scrypt algorithms. |
Collaborator
There was a problem hiding this comment.
we can refer 'Argon2' that is considered the most modern and secure instead of 'PBKDF2' which is older now.
Changes from review of @sachinvodafone
5.5.2 aligned with 5.5.1
link to CAMARA-API-Event-Subscription-and-Notification-Guide.md Co-authored-by: Pedro Díez García <pedro.diezgarcia@telefonica.com>
tlohmar
reviewed
Apr 17, 2025
| ## 5. OpenAPI Sections | ||
|
|
||
| ### 5.1. Reserved words | ||
| To avoid issues with implementation using Open API generators reserved words must not be used in the following parts of an API specification: |
Contributor
There was a problem hiding this comment.
where to find the list or reserved words? Best add a link to the slogan "reserved words"
tlohmar
reviewed
Apr 17, 2025
| ``` | ||
|
|
||
| #### 5.3.1. Title | ||
| Title describes the API shortly. The title shall not include the term "API" in it. |
Contributor
There was a problem hiding this comment.
Suggested change
| Title describes the API shortly. The title shall not include the term "API" in it. | |
| `title` object describes the API shortly. The title shall not include the term "API" in it. | |
tlohmar
reviewed
Apr 17, 2025
| Title describes the API shortly. The title shall not include the term "API" in it. | ||
|
|
||
| #### 5.3.2. Description | ||
| No special restrictions specified in CAMARA. |
Contributor
There was a problem hiding this comment.
Suggested change
| No special restrictions specified in CAMARA. | |
| `description`: There are no special restrictions specified in CAMARA. Some section are required, e.g. on authorization. |
tlohmar
reviewed
Apr 17, 2025
| No special restrictions specified in CAMARA. | ||
|
|
||
| #### 5.3.3. Version | ||
| APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group. |
Contributor
There was a problem hiding this comment.
Suggested change
| APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group. | |
| `version`: APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group. | |
tlohmar
reviewed
Apr 17, 2025
| `contact` information shall not be included. API providers may add this content when documenting their APIs. | ||
|
|
||
| #### 5.3.6. License | ||
| The license object shall include the following fields: |
Contributor
There was a problem hiding this comment.
Suggested change
| The license object shall include the following fields: | |
| The `license` object shall include the following fields: | |
tlohmar
reviewed
Apr 17, 2025
| ``` | ||
|
|
||
| #### 5.3.7. Extension field | ||
| The API shall specify the Commonalities minor release number they are compliant to, by including the `x-camara-commonalities` extension field. |
Contributor
There was a problem hiding this comment.
Suggested change
| The API shall specify the Commonalities minor release number they are compliant to, by including the `x-camara-commonalities` extension field. | |
| `x-camara-commonalities`: The API shall specify the Commonalities minor release number they are compliant to, by including the `x-camara-commonalities` extension field. | |
tlohmar
reviewed
Apr 17, 2025
| The API shall specify the Commonalities minor release number they are compliant to, by including the `x-camara-commonalities` extension field. | ||
|
|
||
| ### 5.4. ExternalDocs object | ||
| The `externalDocs` object shall have the following content: |
Contributor
There was a problem hiding this comment.
Suggested change
| The `externalDocs` object shall have the following content: | |
| The `externalDocs` object shall have the following content: | |
tlohmar
reviewed
Apr 17, 2025
|
|
||
| ### 5.3. Info Object | ||
|
|
||
| The `info` object shall have the following content: |
Contributor
There was a problem hiding this comment.
Suggested change
| The `info` object shall have the following content: | |
| The `info` object shall be present in each API specification and shall contain the below listed properties. | |
| Example `info` object: | |
rartych
added a commit
to rartych/Commonalities
that referenced
this pull request
May 23, 2025
based on comments from PR camaraproject#441
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
What this PR does / why we need it:
CAMARA-API-Design-Guide.md is the restructured document containing API Design Guidelines.
API-design-guidelines.md is marked as depreciated.
The guidelines for Event Subscription & Notification will be proposed in another PR.
Some sections are still empty - can be removed or updated in the dedicated PRs.
The references and cross-references will be added later.
Changes related to Fall25 should be prepared after merging this PR.
Which issue(s) this PR fixes:
Fixes #306
Does this PR introduce a breaking change?
Special notes for reviewers:
The main objective for now is to check if any of current guideline is not lost.
Having more reviewers would truly help to achieve this.
Changelog input
Additional documentation
The initial proposal was indicated in PR #430