From 52d98d0677b8d36c448041a2ef5ab579b2e7ff75 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Fri, 17 May 2024 15:38:03 +0200 Subject: [PATCH 01/17] Adapt to ICM Security and Interoperability Profile --- documentation/API-design-guidelines.md | 70 ++++++-------------------- 1 file changed, 16 insertions(+), 54 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7644f5ec..d48fe3cb 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -75,12 +75,14 @@ This document captures guidelines for the API design in CAMARA project. These gu |**Camel Case**| It is a kind of define the fields’ compound name or phrases without whitespaces among words. It uses a capital letter at the beginning of each word. There are two different uses:
  • Upper Camel Case: When the first letter of each word is capital.
  • Lower Camel Case: Same to that Upper one, but with the first word in lowercase.
    • | |**Header**| HTTP Headers allow client and server send additional information joined to the request or response. A request header is divided by name (No case sensitive) followed by a colon and the header value (without line breaks). White spaces on the left hand from the value are ignored.| |**HTTP**| Hypertext Transfer Protocol (HTTP) is a communication protocol that allows the information transfer using files (XHTML, HTML…) in World Wide Web.| -|**JSON**| JavaScript Object Notation| -|**JWT**| JSON Web Token (JWT) is an open standard based on JSON proposed by IETF (RFC 7519) for access token creations allowing the identity and purposes spread. | +|**JSON**| The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259) | +|**JWT**| JSON Web Token (JWT) is an open standard based on JSON [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519) | |**Kebab-case**| Practice in the words denomination where the hyphen is used to separate words. | -|**OAuth**| Open Authorization is an open standard that allows simple Authorization flows to be used in websites or applications.| +|**OAuth2**| Open Authorization is an open standard that allows simple Authorization flows to be used in websites or applications. [RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)| +|**OIDC**| [OpenId Connect](https://openid.net/specs/openid-connect-core-1_0.html) is standard based on OAuth2 that adds authentication and consent to OAuth2.| +|**CIBA**| [Client-initiated Bachckannel authentication](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) is a standard based on OIDC that enabels API consumers to intiate an authentication.| |**REST**| Representational State Transfer.| -|**TLS**| Transport Layer Security or TLS is a cryptographic protocol that provides secured network communications. | +|**TLS**| Transport Layer Security is a cryptographic protocol that provides secured network communications. | |**URI**| Uniform Resource Identifier. | |**Snake_case**|Practice in the words denomination where the underscore is used to separate words. | @@ -163,48 +165,7 @@ TM Forum further defines a set of reference APIs (TMF Open APIs) between the dif ### 2.4 Information Representation Standard -As a messaging standard, the use of JSON is proposed by default, since it is a light data exchange format and is commonly adopted by current web technologies, although this does not imply that other types of data cannot be used depending on functional and technical requirements. - -JSON is made up with two structures: - -- A collection of key/value pairs. In various languages this is known as an object, record, structure, dictionary, hash table, key list, or an associative array. -- An ordered list of values. In most languages, this is implemented as arrays, vectors, lists, or sequences. -Data exchange format that is independent of the programming language is based on universal structures supported virtually in all programming languages. - -In JSON, the following structures are represented. - -An **object** is an unordered set of key/value pairs. An object starts with a "`{`" opening brace and ends with a "`}`" closing brace. Each name is followed by a “`:`” colon and key/value pairs are separated by a “`,`” comma. -

    -drawing -

    - -An **array** is a collection of values. An array starts with “`[`“ left bracket and ends with “`]`” right bracket. Values are separated by "`,`" comma. -

    -drawing -

    - -A **value** can be a string with double quotes, or a number, or true or false or null, or an object or an array. These structures can be nested. -

    -drawing -

    - -A **character string** is a collection of zero or more Unicode characters, enclosed in double quotes, using backslash escaping. A character is represented by a character string of a single character. A character string is similar to a C or Java character string. -

    - -

    - - -A **number** is similar to a C or Java number, except that octal and hexadecimal formats are not used. -

    - -

    - -**White spaces** can be inserted between any pair of symbols. -

    -drawing -

    - -Except for minor encoding details, the above-mentioned structures provide a full description of JSON language. +As a messaging standard, the use of [JSON](https://datatracker.ietf.org/doc/html/rfc8259) is proposed as the default in Camara, since it is a light data exchange format and is commonly adopted by current web technologies, although this does not imply that other types of data cannot be used depending on functional and technical requirements. ## 2.5 Reduce telco-specific terminology in API definitions CAMARA aims to produce 'intent-based' APIs, which have two key benefits: @@ -329,7 +290,7 @@ Common errors are captured in the table below. | 206 | 206 (Partial Content) The server has fulfilled the partial GET request for the resource. | 400 | 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something perceived as a client error (for example, malformed request syntax, invalid request message structure, or incorrect routing).
    This code must be documented in all the operations in which it is necessary to receive data in the request.| | 401 | 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.
    This code has to be documented in all API operations that require subscription by a client.| -| 403 | 403 (Forbidden) status code indicates that the server understood the request, but is refusing to authorize it. A server that wants to make public why the request was prohibited can describe that reason in the response payload (if applicable).
    This code is usually documented in the operations. It will be returned when the OAuth token access does not have the required scope or when the user fails operational security.| +| 403 | 403 (Forbidden) status code indicates that the server understood the request, but is refusing to authorize it. A server that wants to make public why the request was prohibited can describe that reason in the response payload (if applicable).
    This code is usually documented in the operations. It will be returned when the OAuth2 token access does not have the required scope or when the user fails operational security.| | 404 | 404 (Not Found) status code indicates that the origin server either did not find a current representation for the target resource or is unwilling to reveal that it exists.
    This code will occur on `GET` operations when the resource is not available, so it is necessary to document this return in such situations.| | 405 | 405 (Method Not Allowed) status code indicates that the origin server knows about the method received in the request line, but the target resource does not support it.
    This code is documented at the API portal level, it should not be documented at the API level.| | 406 | 406 (Not Acceptable) status code indicates that the target resource does not have a current representation that would be acceptable to the user, based on the proactive negotiation header fields received in the request, and the server is unwilling to provide a predetermined representation. It must be reported when there is no response by default, and header fields are reported to carry out the content negotiation (Accept, Accept-Charset, Accept-Encoding, Accept-Language). | @@ -399,7 +360,7 @@ The main HTTP headers are described below: - `Accept`: this header can be used to specify certain types of data that are acceptable for the response. `Accept` headers can be used to indicate that the request is specifically limited to a small set of desired types, as in the case of a request for an image. - `Accept-Encoding`: similar to the `Accept` header, but restricting the content encodings that are acceptable in the response. - `Accept-Language`: the consumer defines the list of languages in order of preference. The server answer with the `Content-Language` field in the header with the response language. -- `Authorization`: it allows sending the authorization token for API access, initially OAuth and JWT. +- `Authorization`: it allows sending the authorization token for API access, initially OAuth2 and JWT. - `Content-Type`: it indicates the type of message sent to the recipient or, in the case of the HEAD method, the type of message that would have been sent if the request had been a GET. The MIME type of the response, or the content uploaded via POST/PUT in case it is a request. - `Content-Length`: it indicates the message size, in octets, sent to the recipient or, in the case of the HEAD method, the message size that would have been sent if the request had been a GET. The size of the response in octets (8 bits) - `Content-Encoding`: it is used as a message type modifier. The type of encoding used in the response is indicated. @@ -854,10 +815,11 @@ In notification scenarios (i.e. POST request sent towards the listener to the `w ## 10. Security -One of the key points in the API definition process is to specify and validate the security needs that will be maintained to guarantee data integrity and access control. There are multiple ways to secure a RESTful API, e.g. basic authentication, OAuth, etc., but one thing is for sure: RESTful APIs should be stateless, so authentication/authorization requests should not rely on cookies or sessions. Instead, each API request must come with some form of authentication credentials that must be validated on the server for each request. +One of the key points in the API definition process is to specify and validate the security needs that will be maintained to guarantee data integrity and access control. There are multiple ways to secure a RESTful API, e.g. basic authentication, OAuth2, OIDC, etc., but one thing is for sure: RESTful APIs should be stateless, so authentication/authorization requests should not rely on cookies or sessions. Instead, each API request must come with some form of authentication credentials that must be validated on the server for each request. Basic idea in terms of security is to understand that various types of data will require different levels of security, depending on the confidentiality of the data you are trying to obtain and the level of trust between the API Provider and the consumer. +The [CAMARA Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) defines Security and Interoperablity rules and recommendations for Camara e.g details on OIDC and CIBA. The CAMARA Security and Interoperability Profile is maintained by the [Identity and Consent Management Working Group](https://github.com/camaraproject/IdentityAndConsentManagement). ### 10.1 API REST Security @@ -891,8 +853,8 @@ Passwords should never be sent in API bodies, but if it is necessary it must has Usernames, passwords, session tokens, and API keys should not appear in the URL, as this can be captured in web server logs, making them easily exploitable. For example, this URL (```https://api.domain.com/user-management/users/{id}/someAction?apiKey=abcd123456789```) exposes the API key. Therefore, never use this kind of security. 5. **Authentication and authorization must be considered** - - The OAuth 2.0 authorization framework allows a third-party application to gain limited access to an HTTP service, either on behalf of a resource owner, by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party app get access on your behalf. - - OpenID Connect is built on the OAuth 2.0 protocol and uses an additional JSON Web Token (JWT), called an ID token, to standardize areas that OAuth 2.0 leaves up to choice, such as scopes and endpoint discovery. It is specifically focused on user authentication and is widely used to enable user logins on consumer websites and mobile apps.
    + - The OAuth2 authorization framework allows a third-party application to gain limited access to an HTTP service, either on behalf of a resource owner, by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party app get access on your behalf. + - OpenID Connect is built on the OAuth2 protocol and uses an additional JSON Web Token (JWT), called an ID token, to standardize areas that OAuth2 leaves up to choice, such as scopes and endpoint discovery. It is specifically focused on user authentication and is widely used to enable user logins on consumer websites and mobile apps.
    - All the information about the authN-authZ concepts for CAMARA APIs are documented in https://github.com/camaraproject/IdentityAndConsentManagement/tree/main/documentation/CAMARA-AuthN-AuthZ-Concept.md 6. **Add request time flags should be considered**. @@ -939,7 +901,7 @@ The API must ensure that the consumer is known and can access the requested reso a) OAuth
    -All APIs must be protected by the OAuth 2.0 Framework. All API requests must include an HTTP header called "Authorization" with a valid OAuth access token. +All APIs must be protected by the OAuth2 Framework. All API requests must include an HTTP header called "Authorization" with a valid OAuth2 access token. The following controls will be performed on the access token: - **Check if the access token is still valid**. If it is expired or revoked, the API will return an HTTP 401 (Unauthorized) code. @@ -949,7 +911,7 @@ The following controls will be performed on the access token: b) Scopes
    -The scopes allow defining the permission scopes that a system or a user has on a resource, ensuring that they can only access the parts they need and not have access to more. These restrictions are done by limiting the permissions that are granted to OAuth tokens. +The scopes allow defining the permission scopes that a system or a user has on a resource, ensuring that they can only access the parts they need and not have access to more. These restrictions are done by limiting the permissions that are granted to OAuth2 tokens. Scopes should be represented as below for all Camara APIs except the APIs that offer explicit event subscriptions: - API Name: qod, address-management, numbering-information... @@ -1049,7 +1011,7 @@ Below considerations should be checked when an API is documented: - Request Parameters ([Section 11.3](#113-request-parameters)) - Response Structure ([Section 11.4](#114-response-structure)) - Data Definitions ([Section 11.5](#115-data-definitions)) - - OAuth Definition ([Section 11.6](#116-oauth-definition)) + - Security Schemes ([Section 11.6](#116-oauth-definition)) - To avoid issues with implementation using Open API generators: - Reserved words must not be used in the following parts of an API specification: - Path and operation names From 71e6b04010938c544380b78fb41df86791fd47c6 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Fri, 17 May 2024 19:59:29 +0200 Subject: [PATCH 02/17] Type Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index d48fe3cb..bd62343e 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -80,7 +80,7 @@ This document captures guidelines for the API design in CAMARA project. These gu |**Kebab-case**| Practice in the words denomination where the hyphen is used to separate words. | |**OAuth2**| Open Authorization is an open standard that allows simple Authorization flows to be used in websites or applications. [RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)| |**OIDC**| [OpenId Connect](https://openid.net/specs/openid-connect-core-1_0.html) is standard based on OAuth2 that adds authentication and consent to OAuth2.| -|**CIBA**| [Client-initiated Bachckannel authentication](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) is a standard based on OIDC that enabels API consumers to intiate an authentication.| +|**CIBA**| [Client-Initiated Backchannel Authentication](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) is a standard based on OIDC that enabels API consumers to intiate an authentication.| |**REST**| Representational State Transfer.| |**TLS**| Transport Layer Security is a cryptographic protocol that provides secured network communications. | |**URI**| Uniform Resource Identifier. | From 44332d4b84f4c008f6da47150faaeea50514320e Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Sat, 18 May 2024 14:56:41 +0200 Subject: [PATCH 03/17] OAuth -> OAuth2 --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index bd62343e..f308a608 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -899,7 +899,7 @@ These include: The API must ensure that the consumer is known and can access the requested resources. -a) OAuth
    +a) OAuth2
    All APIs must be protected by the OAuth2 Framework. All API requests must include an HTTP header called "Authorization" with a valid OAuth2 access token. From 69030604bd1d06b53f8d5570a1d10c37792bdf80 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Sat, 18 May 2024 15:02:26 +0200 Subject: [PATCH 04/17] Adapt 11.6 Security definition to Camara Security and Interoperabitlity Profile --- documentation/API-design-guidelines.md | 54 ++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 4 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index f308a608..95e0a70e 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1224,11 +1224,57 @@ When IpAddr is used in a payload, the property objectType MUST be present to ind ### 11.6 Security definition -The [CAMARA API Specification - Authorization and authentication common guidelines](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#camara-api-specification---authorization-and-authentication-common-guidelines) are discussed and maintained by the [Identity and Consent Management Working Group](https://github.com/camaraproject/IdentityAndConsentManagement). In particular, the following aspects are detailed: +In general all APIs must be secured to assure 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. + +The [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#purpose) defines that a single purpose is encoded in the list of scope values. The purpose is defined by W3C Privacy Vocabulatory in the [purpose section](https://w3c.github.io/dpv/dpv/#vocab-purposes). + +#### OpenAPI security schemes definition + +Security in OpenAPI is expressed by [security schemes](https://spec.openapis.org/oas/v3.0.3#security-scheme-object). Security can be expressed for the API as a whole or for each endpoint. + +All Camara OpenAPI files must include the following security scheme definition, with an adapted `openIdConnectUrl` in its components section: + +```yaml +components: + securitySchemes: + openId: + type: openIdConnect + 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`. + +#### Expressing Security Requirements + +Security requirements of an API are expressed in OpenAPI through [Security Requirement Objects](https://spec.openapis.org/oas/v3.0.3#security-requirement-object). + +Following is an example on how to use the `openId` security scheme defined above: + +```yaml +paths: + {path}: + {method}: + ... + security: + - openId: + - {scope} +``` + +The name `openId` must be same as defined in the components.securitySchemes section. + +#### Mandatory template for `info.description` in CAMARA API specs + +The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs: + +``` +### Authorization and authentication + +The [CAMARA Interoperability and Security Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) specifies which OIDC, CIBA authorization flows can be used in Camara by the API Client to optain access tokens and which client authentication methods are allowed in Camara. + +Which specific protocol and which authorization flows are to be used will be determined during onboarding process, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. +``` -- Use of openIdConnect as protocol in `securitySchemes`. -- How to fill the `security` property per operation. -- How to fill the "Authorization and authentication" section in `info.description`. #### 11.6.1 Scope naming From 12864d8c1bbf46e75337fec79d2510db8c97b555 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Sat, 18 May 2024 15:05:17 +0200 Subject: [PATCH 05/17] Adapt checklist for security to Security and Interoperability Profile --- documentation/API-design-guidelines.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 95e0a70e..c67ec5c6 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -853,9 +853,7 @@ Passwords should never be sent in API bodies, but if it is necessary it must has Usernames, passwords, session tokens, and API keys should not appear in the URL, as this can be captured in web server logs, making them easily exploitable. For example, this URL (```https://api.domain.com/user-management/users/{id}/someAction?apiKey=abcd123456789```) exposes the API key. Therefore, never use this kind of security. 5. **Authentication and authorization must be considered** - - The OAuth2 authorization framework allows a third-party application to gain limited access to an HTTP service, either on behalf of a resource owner, by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party app get access on your behalf. - - OpenID Connect is built on the OAuth2 protocol and uses an additional JSON Web Token (JWT), called an ID token, to standardize areas that OAuth2 leaves up to choice, such as scopes and endpoint discovery. It is specifically focused on user authentication and is widely used to enable user logins on consumer websites and mobile apps.
    - - All the information about the authN-authZ concepts for CAMARA APIs are documented in https://github.com/camaraproject/IdentityAndConsentManagement/tree/main/documentation/CAMARA-AuthN-AuthZ-Concept.md + 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**. Along with other request parameters, a request timestamp can be added as a custom HTTP header in API requests. The server will compare the current timestamp with the timestamp of the request and will only accept the request if it is within a reasonable time frame (1-2 minutes maybe). From b7cb0fd156eb9d17a74485df980fe7037dac145d Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Tue, 21 May 2024 13:00:16 +0200 Subject: [PATCH 06/17] fix info.description --- documentation/API-design-guidelines.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index c67ec5c6..ae6a699e 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1268,12 +1268,11 @@ The documentation template below must be used as part of the API documentation i ``` ### Authorization and authentication -The [CAMARA Interoperability and Security Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) specifies which OIDC, CIBA authorization flows can be used in Camara by the API Client to optain access tokens and which client authentication methods are allowed in Camara. +CAMARA guidelines define a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA Interoperability and Security Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. -Which specific protocol and which authorization flows are to be used will be determined during onboarding process, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. +It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. ``` - #### 11.6.1 Scope naming Regarding scope naming, the guidelines are: From 709e68b47d8e150019e9ec96c8209492ba23ef60 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Mon, 27 May 2024 08:50:22 +0200 Subject: [PATCH 07/17] do not link to Security and Interoperability Profile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jesús Peña García-Oliva --- documentation/API-design-guidelines.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index ae6a699e..839fc687 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1268,7 +1268,9 @@ The documentation template below must be used as part of the API documentation i ``` ### Authorization and authentication -CAMARA guidelines define a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA Interoperability and Security Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. +### Authorization and authentication + +CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. ``` From 2e7025eda62b1c9806a0dd215f09d08db2334ee9 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 5 Jun 2024 18:03:44 +0200 Subject: [PATCH 08/17] Update documentation/API-design-guidelines.md Co-authored-by: Elisabeth-Ericsson <121795930+Elisabeth-Ericsson@users.noreply.github.com> --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 839fc687..db8ba1b9 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1231,7 +1231,7 @@ The [Camara Security and Interoperability Profile](https://github.com/camaraproj Security in OpenAPI is expressed by [security schemes](https://spec.openapis.org/oas/v3.0.3#security-scheme-object). Security can be expressed for the API as a whole or for each endpoint. -All Camara OpenAPI files must include the following security scheme definition, with an adapted `openIdConnectUrl` in its components section: +As specified in 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 a 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. ```yaml components: From 28b6b091ebbbf69dd4926eb310979d68456122f6 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 5 Jun 2024 18:04:09 +0200 Subject: [PATCH 09/17] Update documentation/API-design-guidelines.md Co-authored-by: Elisabeth-Ericsson <121795930+Elisabeth-Ericsson@users.noreply.github.com> --- documentation/API-design-guidelines.md | 1 - 1 file changed, 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index db8ba1b9..acdb4fc8 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1257,7 +1257,6 @@ paths: security: - openId: - {scope} -``` The name `openId` must be same as defined in the components.securitySchemes section. From e9a9ab3434e7d858c8b0504b0efce638565a9b3e Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 5 Jun 2024 18:04:51 +0200 Subject: [PATCH 10/17] Update documentation/API-design-guidelines.md Co-authored-by: Elisabeth-Ericsson <121795930+Elisabeth-Ericsson@users.noreply.github.com> --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index acdb4fc8..84ffcbd0 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1262,7 +1262,7 @@ The name `openId` must be same as defined in the components.securitySchemes sect #### Mandatory template for `info.description` in CAMARA API specs -The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs: +The documentation template available in https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#mandatory-template-for-infodescription-in-camara-api-specs must be used as part of the API documentation in `info.description` property in the CAMARA API specs: ``` ### Authorization and authentication From 3a744b7b7a2850be114e004aaadcadf65eb6b7ee Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 5 Jun 2024 18:05:40 +0200 Subject: [PATCH 11/17] Update documentation/API-design-guidelines.md Co-authored-by: Elisabeth-Ericsson <121795930+Elisabeth-Ericsson@users.noreply.github.com> --- documentation/API-design-guidelines.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 84ffcbd0..111cbbf5 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1263,15 +1263,6 @@ The name `openId` must be same as defined in the components.securitySchemes sect #### Mandatory template for `info.description` in CAMARA API specs The documentation template available in https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#mandatory-template-for-infodescription-in-camara-api-specs must be used as part of the API documentation in `info.description` property in the CAMARA API specs: - -``` -### Authorization and authentication - -### Authorization and authentication - -CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. - -It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. ``` #### 11.6.1 Scope naming From 206be6d3c389a13d2371af58c555c351845beb12 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 5 Jun 2024 18:23:40 +0200 Subject: [PATCH 12/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jesús Peña García-Oliva --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 111cbbf5..05e5f5a9 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1231,7 +1231,7 @@ The [Camara Security and Interoperability Profile](https://github.com/camaraproj Security in OpenAPI is expressed by [security schemes](https://spec.openapis.org/oas/v3.0.3#security-scheme-object). Security can be expressed for the API as a whole or for each endpoint. -As specified in 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 a 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. +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 a 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. ```yaml components: From 4aa0e0123a45f299c85bfe03610eb44d544a48b7 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 5 Jun 2024 18:23:59 +0200 Subject: [PATCH 13/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jesús Peña García-Oliva --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 05e5f5a9..eb58df6b 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1247,7 +1247,7 @@ The key of the security scheme is arbitrary in OAS, but convention in CAMARA is Security requirements of an API are expressed in OpenAPI through [Security Requirement Objects](https://spec.openapis.org/oas/v3.0.3#security-requirement-object). -Following is an example on how to use the `openId` security scheme defined above: +Following is an example on how to use the `openId` security scheme defined above as defined 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: From 5d91aabd421bf11f90042a7c82c8710fecb57d4c Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 5 Jun 2024 18:24:41 +0200 Subject: [PATCH 14/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jesús Peña García-Oliva --- documentation/API-design-guidelines.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index eb58df6b..93c4583b 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1262,8 +1262,7 @@ The name `openId` must be same as defined in the components.securitySchemes sect #### Mandatory template for `info.description` in CAMARA API specs -The documentation template available in https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#mandatory-template-for-infodescription-in-camara-api-specs must be used as part of the API documentation in `info.description` property in the CAMARA API specs: -``` +The documentation template available in [CAMARA API Specification - Authorization and authentication common guidelines](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#mandatory-template-for-infodescription-in-camara-api-specs) must be used as part of the authorization and authentication API documentation in the `info.description` property of the CAMARA API specs. #### 11.6.1 Scope naming From 0c89a5c131042ee633ea980e236461245e7ec871 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Mon, 10 Jun 2024 10:56:49 +0200 Subject: [PATCH 15/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jesús Peña García-Oliva --- documentation/API-design-guidelines.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 93c4583b..8636cf74 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1247,7 +1247,7 @@ The key of the security scheme is arbitrary in OAS, but convention in CAMARA is Security requirements of an API are expressed in OpenAPI through [Security Requirement Objects](https://spec.openapis.org/oas/v3.0.3#security-requirement-object). -Following is an example on how to use the `openId` security scheme defined above as defined in [Use of security property](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#use-of-security-property): +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: @@ -1257,6 +1257,7 @@ paths: security: - openId: - {scope} +``` The name `openId` must be same as defined in the components.securitySchemes section. From fb217d5e53e36318371246e035b6f5cc306a4671 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Mon, 10 Jun 2024 18:49:51 +0200 Subject: [PATCH 16/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 8636cf74..1a4c88fe 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -80,7 +80,7 @@ This document captures guidelines for the API design in CAMARA project. These gu |**Kebab-case**| Practice in the words denomination where the hyphen is used to separate words. | |**OAuth2**| Open Authorization is an open standard that allows simple Authorization flows to be used in websites or applications. [RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)| |**OIDC**| [OpenId Connect](https://openid.net/specs/openid-connect-core-1_0.html) is standard based on OAuth2 that adds authentication and consent to OAuth2.| -|**CIBA**| [Client-Initiated Backchannel Authentication](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) is a standard based on OIDC that enabels API consumers to intiate an authentication.| +|**CIBA**| [Client-Initiated Backchannel Authentication](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) is a standard based on OIDC that enables API consumers to intiate an authentication.| |**REST**| Representational State Transfer.| |**TLS**| Transport Layer Security is a cryptographic protocol that provides secured network communications. | |**URI**| Uniform Resource Identifier. | From 8faabc9be50fc9bc8046a1e9d6c9650d90b84a54 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Mon, 10 Jun 2024 18:50:20 +0200 Subject: [PATCH 17/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 1a4c88fe..9014ba0d 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1231,7 +1231,7 @@ The [Camara Security and Interoperability Profile](https://github.com/camaraproj Security in OpenAPI is expressed by [security schemes](https://spec.openapis.org/oas/v3.0.3#security-scheme-object). 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 a 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. +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. ```yaml components: