Merge pull request #201 from camaraproject/generalize-telco-and-opera…

…tor-terms

Replace telco and operator by more general terms

documentation/CAMARA-Security-Interoperability.md

@@ -39,17 +39,17 @@ This document is the CAMARA Security and Interoperability Profile. To ensure int
 The CAMARA document sharpens the following for interoperability and security: 
 
 * Of the flows defined in OIDC, CAMARA uses the [OIDC Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) and [OIDC Client Initiated Backchannel Authentication Flow](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)
-* Of the flows defined in Oauth2, Camara uses the [Client credentials grant flow](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)
+* Of the flows defined in Oauth2, CAMARA uses the [Client credentials grant flow](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)
 * Scope Parameter. Recommendations about the format of the scope parameter used in  CAMARA APIs.
 
 * Client Authentication. Specifications for client authentication within CAMARA.
 
-By encapsulating these elements within this document, it aims to provide a comprehensive guide for developers and operators, ensuring consistent implementation and adherence to standardized security measures across the CAMARA ecosystem. The defined OIDC profile not only facilitates the integration process, but also serves as a basic framework for developers wishing to leverage the CAMARA APIs while maintaining security and interoperability.
+By encapsulating these elements within this document, it aims to provide a comprehensive guide for API consumers and API providers, ensuring consistent implementation and adherence to standardized security measures across the CAMARA ecosystem. The defined OIDC profile not only facilitates the integration process, but also serves as a basic framework for developers wishing to leverage the CAMARA APIs while maintaining security and interoperability.
 
 
 ## Audience
 
-The target audience for this document is the service/technical departments of operators exposing network functions via standard CAMARA APIs and the applications or client systems that consume CAMARA standard APIs to make use of the operator's network capabilities.
+The target audience for this document is the service/technical departments of API providers exposing network functions via standard CAMARA APIs and the applications or client systems that consume CAMARA APIs to make use of the operator's network capabilities.
 
 ## Conventions
 
@@ -68,12 +68,12 @@ The OIDC Authorization Code Flow is defined in [OpenID Connect](https://openid.n
 
 ### Cross-Site Request Forgery Protection
 
-CAMARA REQUIRES cross-site request forgery protection.
+CAMARA REQUIRES cross-site request forgery (CSRF) protection.
 
 CAMARA RECOMMENDS PKCE for CSRF protection. 
-CAMARA Authorization Servers SHOULD implement PKCE. If PKCE is not used by the Client then the CAMARA AZ must handle **state** and **nonce** as defined in OAuth2.
+CAMARA Authorization Servers SHOULD implement PKCE. If PKCE is not used by the API consumer then the CAMARA authorization server must handle **state** and **nonce** as defined in OAuth2.
 
-CAMARA Clients SHOULD use PKCE if the CAMARA AZ supports PKCE.
+CAMARA API consumers SHOULD use PKCE if the CAMARA authorization server supports PKCE.
 
 If nonce for CSRF-protection is used then implementers must ensure that sufficient entropy is present in the nonce value.
 Please see [OAuth 2.0 Security Best Current Practice](https://oauthstuff.github.io/draft-ietf-oauth-security-topics/draft-ietf-oauth-security-topics.html#name-protecting-redirect-based-f).
@@ -84,11 +84,11 @@ The [Client-Initiated Backchannel Authentication (CIBA)](https://openid.net/spec
 
 Communication with the Backchannel Authentication Endpoint MUST utilize TLS.
 
-CIBA allows the Client to get the authentication result in three ways: poll, ping, or push. This profile allows clients to use the *poll* mode. In the Poll mode, the authentication result is retrieved by the Client by polling the OP's token endpoint using the new grant type. 
+CIBA allows the Client to get the authentication result in three ways: poll, ping, or push. This profile allows clients to use the *poll* mode. In the Poll mode, the authentication result is retrieved by the Client by polling the token endpoint using the new grant type. 
 
 ### Optional Parameters
 
-The parameters `binding_message`, `user_code`, and `requested_expiry` are currently not implemented in Camara and for interoperability this document defines that the authorization server SHOULD ignore them. 
+The parameters `binding_message`, `user_code`, and `requested_expiry` are currently not implemented in CAMARA and for interoperability this document defines that the authorization server SHOULD ignore them. 
 
 
 ### Authentication Request
@@ -125,9 +125,9 @@ This CAMARA document clarifies the values used in login_hint in the following wa
 #### Refresh Token Issuance
 
 Neither OIDC, CIBA, nor OAuth2 define a way for clients to indicate whether they need a refresh_token. 
-Refresh token issuance is optional and at the discretion of the AZ.
+Refresh token issuance is optional and at the discretion of the authorization server.
 
-Camara uses the scope `offline_access` in the authorization request to indicate to the AZ that the client requests a refresh token additionally to the access token for Camara API access.
+CAMARA uses the scope `offline_access` in the authorization request to indicate to the authorization server that the client requests a refresh token additionally to the access token for CAMARA API access.
 
 ---
 **NOTE**
@@ -166,7 +166,7 @@ Considering [OAuth2 Refresh Token Protection](https://datatracker.ietf.org/doc/h
 
 ## Client Credentials Flow
 
-The [OAuth 2.0 Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type is used to obtain a 2-legged Access Token that does not represent a user. The grant-type can only be used if agreed between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API (cf. [CAMARA API Specification - Authorization and authentication common guidelines](CAMARA-API-access-and-user-consent.md#camara-api-specification---authorization-and-authentication-common-guidelines)).
+The [OAuth 2.0 Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type is used to obtain a 2-legged Access Token that does not represent a user. The grant-type can only be used if agreed between the API consumer and the API provider exposing the API, taking into account the declared purpose for accessing the API (cf. [CAMARA API Specification - Authorization and authentication common guidelines](CAMARA-API-access-and-user-consent.md#camara-api-specification---authorization-and-authentication-common-guidelines)).
 
 ## Handling of acr_values
 
@@ -177,11 +177,11 @@ OIDC specifies in [Mandatory to Implement Features for All OpenID Providers](htt
 
 OIDC also defines that the parameter acr_values is OPTIONAL and does not specify possible values. This leads to interoperability issues.
 
-This documents defines that Camara OpenId Providers MUST ignore the parameter acr_values. 
+This documents defines that CAMARA OpenId Providers MUST ignore the parameter acr_values. 
 
-This document defines that Camara Clients SHOULD not use the acr_values parameter. 
+This document defines that CAMARA API consumers SHOULD not use the acr_values parameter. 
 
-> To foster interoperability a future version of this document might define values for the acr_values parameter acceptable in Camara.
+> To foster interoperability a future version of this document might define values for the acr_values parameter acceptable in CAMARA.
 
 ## Access Token Request
 
@@ -192,13 +192,13 @@ The client MUST authenticate with the authorization server as described in [Clie
 ## The Scope Parameter
 
 
-Scope values determine the specific CAMARA services being requested by the Service Provider, subject to the SP being registered to use those services. The scope values must be documented in the API OAS files by all Camara API subprojects. This document does not change OIDC definitions of scope values.
+Scope values determine the specific CAMARA services being requested by the Service Provider, subject to the SP being registered to use those services. The scope values must be documented in the API OAS files by all CAMARA API subprojects. This document does not change OIDC definitions of scope values.
 
 
 ---
 **NOTE**
 
-Scope values are an integral part of any OAuth2 and OIDC implementation. The RS enforces API access based on scope (if the Camara API subproject defines scopes).
+Scope values are an integral part of any OAuth2 and OIDC implementation. The API implementation enforces API access based on scope (if the CAMARA API subproject defines scopes).
 Therefore scopes should be available to API implementations.
 
 ---
@@ -222,11 +222,11 @@ If "openid" is missing in the scope value but a claim that is standardized in OI
 Clients SHOULD follow the OIDC and CIBA standard and SHOULD include `openid` in the list of requested scopes.
 The [id token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) contains the `sub` field which is the identifier of the subject of the [OIDC authorization code](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) request respectively the [CIBA authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request). 
 
-The Camara authorization server creates the `sub` value. Globally unique identifiers, like the MSISDN, should be avoided for privacy reasons.
+The CAMARA authorization server creates the `sub` value. Globally unique identifiers, like the MSISDN, should be avoided for privacy reasons.
 
 ## Purpose
 
-In Camara `purpose` is used to convey to the user for which purpose an API is used. E.g.: Does the client request the user's location because it wants to show relevant tourist information or is the user's location information protecting the user when they withdraw money from an ATM? 
+In CAMARA `purpose` is used to convey to the user for which purpose an API is used. E.g.: Does the client request the user's location because it wants to show relevant tourist information or is the user's location information protecting the user when they withdraw money from an ATM? 
 
 Purpose has always to be reflected and audited when personal information is accessed or managed in certain legislations (e.g. in EU GDPR). To ensure interoperability across different legislations this profile requires that the purpose must always be declared within the supported OIDC or OAuth2 token requests if personal information is accessed or managed.
 
@@ -248,7 +248,7 @@ Further format discussion will happen, e.g. how to handle multiple purposess, be
 
 ## ID Token
 
-Camara uses ID Token as defined in [OpenID Connect Core 1.0 incorporating errata set 2](https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken). ID token must be a part of a successul response parameter as specified in  [Successful Token Response section](https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse).
+CAMARA uses ID Token as defined in [OpenID Connect Core 1.0 incorporating errata set 2](https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken). ID token must be a part of a successul response parameter as specified in  [Successful Token Response section](https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse).
 
 ### ID Token sub claim
 
@@ -277,7 +277,7 @@ This document RECOMMENDS that for OIDC CIBA the audience SHOULD be the [Backchan
 
 ## OpenId Foundation Certification
 
-Camara recommends that implementations run the OIDF interoperability suite and achieve [OIDF certification](https://openid.net/certification/).
+CAMARA recommends that implementations run the OIDF interoperability suite and achieve [OIDF certification](https://openid.net/certification/).
 
 ## References