Add missing offline access/refresh token doc from GSMA

[jpengar]

What type of PR is this?

• documentation

What this PR does / why we need it:

As discussed and agreed in the CAMARA Identity & Consent Management Working Group (meeting call 17/01/24), and as per CAMARA TSC (Technical Steering Committee) decision, the documentation of the NBI CAMARA API interface, authZ/authN flows, purpose/consent management, etc... will only be placed in CAMARA. CAMARA can be the source of truth for northbound interfaces. GSMA Opengateway will simply adopt what is defined in CAMARA.

This PR is intended to move the GSMA Opengateway Chapter 04 Offline Access.md to CAMARA as a last step to fix #82, taking into account PR #114 as well.

Which issue(s) this PR fixes:

Fixes #82

Special notes for reviewers:

Please, I strongly suggest that we first focus on moving the necessary documentation to the CAMARA Identity & Consent WG repository as agreed. To have all the documentation here. And then, if the WG participants want to revisit the content of the documentation, we can open a new issue for that, no problem. This would allow us to wrap up a long discussion, close issue #82, and move on to the next needed discussion without blocking this track by creating new dependencies between issues.

Changelog input

 offline access / refresh token flows

Additional documentation

N/A

[AxelNennker]

Why do we need so many words?

OIDC says this about refresh tokens:

1.  Offline Access

OpenID Connect defines the following scope value to request offline access:

    offline_access
        OPTIONAL. This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the End-User is not present (not logged in). 

When offline access is requested, a prompt parameter value of consent MUST be used unless other conditions for processing the request permitting offline access to the requested resources are in place. The OP MUST always obtain consent to returning a Refresh Token that enables offline access to the requested resources. A previously saved user consent is not always sufficient to grant offline access.

Upon receipt of a scope parameter containing the offline_access value, the Authorization Server:

    MUST ensure that the prompt parameter contains consent unless other conditions for processing the request permitting offline access to the requested resources are in place; unless one or both of these conditions are fulfilled, then it MUST ignore the offline_access request,
    MUST ignore the offline_access request unless the Client is using a response_type value that would result in an Authorization Code being returned,
    MUST explicitly receive or have consent for offline access when the registered application_type is web,
    SHOULD explicitly receive or have consent for offline access when the registered application_type is native.

The use of Refresh Tokens is not exclusive to the offline_access use case. The Authorization Server MAY grant Refresh Tokens in other contexts that are beyond the scope of this specification.

A Camara API working group might want to allow or forbid offline access.

A Camara API working group might define a maximum value for the time offline access is valid after the user has given their consent.

Does the IdentityAndConsentManagement group have guide lines for API working groups on how to allow or restrict offline access?

If a user revokes their consent to offline access are our resource servers able to deny access to the API? Handling of revoked consent MUST be a test case for Camara implementations.

Do we have specific use cases for offline access in current Camara APIs? If we do not have use cases then we do not need this text, and we might explicitly forbid offline access or at least discourage it.

[AxelNennker]

Could somebody explain why this section is needed at all? I tried to rewrite the chapter but after doing so concluded that this is not needed.

A normal OIDC/OAuth2 flow: Using OIDC or OAuth2 the client, while on-net, gets a short-lived access token and long-lived refresh token for a certain API and scope. The AZ uses some IP-Address-to-MSISDN technology to identify the subscription, which in this scenario is a precondition to getting the access token and refresh token.

In OAuth2, regardless whether the client is on-net or off-net the access token can be used at the RS to use the API. Now the access token expires. The refresh token can be used to get a new access token for the same scope. Regardless whether the client is on-net or off-net the new access token can be used at the RS to use the API.

The above is normal for OIDC and OAuth2. The access token is exactly what is needed to access the API. Nothing more, nothing less.

Is there an assumption I am missing? I could imagine that the telco for some APIs requires that API access is on-net. That would be an extension to OAuth2, right? Then not the access token is authorizing the API access but the client has to be on-net for the API access as well. It seems that on-net access to the API is a security feature but not needed to fulfill the function of the API, right? Otherwise, getting an off-net access token and using it off-net at the RS would not work.

So, my assumption is: For security reasons the RS requires both the access token AND on-net access to the API. But, there are clients, who can get weaker security and request an off-net capable access token. This is my interpretation why this section we are talking about here exists.

Why refresh tokens play a special role here, I can't imagine.

This sounds like if there is a scope defined by an API and the client requests it, then in fact it is requesting an on-net-scope. Then to solve the wifi case the client would request scope="openid off-net scope" and would get an access token for off-net access.

Using "offline_access" is confusing for developers because the special scope offline_access creates an access token for the user info endpoint nothing else.

Or am I missing something? Why is this special handling needed?

I fear that if we merge this as a provisional documentation of the current state we never can improve this because then operators who implemented this are going to say "We have a running system with real customers, we cannot change this".

[jpengar]

A normal OIDC/OAuth2 flow: Using OIDC or OAuth2 the client, while on-net, gets a short-lived access token and long-lived refresh token for a certain API and scope. The AZ uses some IP-Address-to-MSISDN technology to identify the subscription, which in this scenario is a precondition to getting the access token and refresh token.

In OAuth2, regardless whether the client is on-net or off-net the access token can be used at the RS to use the API. Now the access token expires. The refresh token can be used to get a new access token for the same scope. Regardless whether the client is on-net or off-net the new access token can be used at the RS to use the API.

The above is normal for OIDC and OAuth2. The access token is exactly what is needed to access the API. Nothing more, nothing less.

I fully agree with this. Precisely the use of the refresh_token to get a new access token regardless of whether the client is on-net or off-net is the agreed technical solution to cover the requirements of the Opengateway off-net scenarios.

The point is how to request and/or obtain those long long-lived refresh tokens for a specific CAMARA API (requested scope(s)).

@jogu @AxelNennker So how exactly do you propose to do that? Are you suggesting to define a specific "off-net"-like scope on each CAMARA API spec? Could you elaborate on that to see if we can find a way to agree on this matter?

If you are suggesting this, it looks to me much more complicated to manage in CAMARA, since it should be included and considered in every CAMARA API subproject. Rather than defining a common way for dozens of APIs and leaving it to the Operator Auth Server to apply the operator's policy to allow or not allow per client_id and/or API if it is allowed to request a refresh token or not. Why should we include this dependency in the API spec? The "openid" scope or "offline_access" scope are not defined at the API level for example... the thing is that OIDC does not define any other endpoint except UserInfo.

If a common way to request a refresh token is defined, how could it be?... using a new specific CAMARA scope, e.g. say "off-net" scope or similar?... But in that case why not directly use "offline_access" which is already defined and is something done by other big players and known by developers. To me, it might not make sense to ask for "offline_access" and "off-net" in the authorization request, for example.

Using "offline_access" to allow clients to request a refresh_token as documented would only need to be considered in the OIDC profiling for CAMARA. Is this really a big deal? What exactly are your security concerns?

[AxelNennker]

How about using this text to describe offline access? Does this work with Open Gateway implementations?

Offline Access

Neither OIDC not OAuth2 define a way for clients to indicate whether they need a refresh_token. In OIDC and OAuth2 refresh token issuance is optional in Authorization Code Flow and at the discretion of the AZ.

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.

---

NOTE

OIDC defines the scope offline_access and it is used to get an access token to be used at the UserInfo endpoint, and also to obtain a request token to refresh this access token.

---

The OIDC rules for offline_access as defined in OIDC Offline Access apply.

Copied to here unchanged from the OIDC standard for clarity:

When offline access is requested, a prompt parameter value of consent MUST be used unless other conditions for processing the request permitting offline access to the requested resources are in place. The OP MUST always obtain consent to returning a Refresh Token that enables offline access to the requested resources. A previously saved user consent is not always sufficient to grant offline access.

Upon receipt of a scope parameter containing the offline_access value, the Authorization Server:

MUST ensure that the prompt parameter contains consent unless other conditions for processing the request permitting offline access to the requested resources are in place; unless one or both of these conditions are fulfilled, then it MUST ignore the offline_access request,

MUST ignore the offline_access request unless the Client is using a response_type value that would result in an Authorization Code being returned,

MUST explicitly receive or have consent for offline access when the registered application_type is web,

SHOULD explicitly receive or have consent for offline access when the registered application_type is native.

The OIDC section on OIDC Using Refresh Tokens is not changed by this document.

The OIDC security and privacy considerations regarding offline access and refresh tokens apply e.g. on Token lifetime and Offline Access Privacy.

[jogu]

Using "offline_access" to allow clients to request a refresh_token as documented would only need to be considered in the OIDC profiling for CAMARA. Is this really a big deal? What exactly are your security concerns?

As I hinted at above, it's really a fine grained access concern, which gives rise to both security & privacy concerns.

I would say modern best practice would be that clients are very specific about what length of access they need and to which APIs. Whether is it worth addressing that in a generic manner or handling it per API I'm less sure.

[jpengar]

How about using this text to describe offline access? Does this work with Open Gateway implementations?

@AxelNennker Sorry for the late reply, these are tough days. I'm fine with this text, except for the part copied from the OIDC standard...

The OIDC rules for offline_access as defined in OIDC Offline Access apply.

Copied here unchanged from the OIDC standard for clarity: ...

...mainly because I think these rules, as defined in the standard, do not fit 100% to the CAMARA use case of requesting refresh tokens for Service CAMARA APIs. They are very specific for UserInfo endpoint and Auth Code flow, which is the scenario covered in the standard, and they should be extended in CAMARA OIDC profiling as well for this off-net requirement.

For example:

MUST ignore the offline_access request unless the client uses a response_type value that would cause an authorization code to be returned,

In the case of CAMARA, Authorization Code is not the only flow to support. For example, offline_access must also be allowed for CIBA flow.

or

When offline access is requested, a prompt parameter value of consent MUST be used unless there are other conditions for processing the request that allow offline access to the requested resources. The OP MUST always obtain consent to return a refresh token that allows offline access to the requested resources. A previously stored user consent is not always sufficient to grant offline access.

As documented in the PR, there is no requirement on the prompt value to use the "offline_access" scope to request a refresh token to cover Opengateway off-net scenarios to access CAMARA Service APIs.

[jpengar]

Question: add the proposed new text into the "profile" and not here and close this PR?

@AxelNennker I think the final text we end up agreeing definitely needs to be included in the OIDC profile, as discussed earlier in this same PR.

Regarding the refresh_token/offline_access flows being included in CAMARA-API-access-and-user-consent.md in this PR, please don't forget the original goal of this PR and where it came from.

What this PR does / why we need it: As discussed and agreed in the CAMARA Identity & Consent Management Working Group (meeting call 17/01/24), and as per CAMARA TSC (Technical Steering Committee) decision, the documentation of the NBI CAMARA API interface, authZ/authN flows, purpose/consent management, etc... will only be placed in CAMARA. CAMARA can be the source of truth for northbound interfaces. GSMA Opengateway will simply adopt what is defined in CAMARA.

This PR is intended to move the GSMA Opengateway Chapter 04 Offline Access.md to CAMARA as a last step to fix https://github.com/camaraproject/IdentityAndConsentManagement/issues/82, taking into account PR https://github.com/camaraproject/IdentityAndConsentManagement/pull/114 as well.

Moving this information here was a WG decision after long discussions, including agreement with the GSMA. So not moving this information to CAMARA now, should be a WG decision as well. And If the WG now decides the opposite, at least this information will have to be kept in the "GSMA Opengateway Chapter 04 Offline Access.md" document in the GMSA repository and that document at GSMA will have to be adapted to point to offline access section of CAMARA OIDC profile when available.

[hdamker]

information will have to be kept in the "GSMA Opengateway Chapter 04 Offline Access.md" document in the GMSA repository and that document at GSMA will have to be adapted to point to offline access section of CAMARA OIDC profile when available.

If there is a consensus possible based on the text proposed by Axel (multiple times above) than this is maybe the way forward: keep the text for now in GSMA and add the agreed, adapted version of it to the OIDC profile.

At least it wouldn't make sense to have two different statements for the topic of refresh token and their use in offline scenarios in two different documents of the working group (even not for a short time).

[AxelNennker]

In CAMARA-Security-Interoperability.md the Offline Access section is a subsection of Authorization Code flow. So, only applies to that flow.

CIBA has its own rules for refresh tokens at least in PUSH mode e.g.:

In case a Refresh Token is sent to the Client, the hash value of it MUST also be added to the ID token using the urn:openid:params:jwt:claim:rt_hash claim.

I think the proposed text is good for authorization code flow. Have to think about ciba and refresh tokens. But I would rather have the proposed text for authorziation code flow then the GSMA text.

[jpengar]

I think there is no such thing as an Operator Access Token. We only have access tokens. I think that applies to the whole GSMA text. I guess every occurrence of "operator" is a candidate for a review.

@AxelNennker The operator access token is actually the access token (access tokens are issued by the operator). It is just a matter of naming, and the PR text is aligned with the rest of the document content. If we want to revisit this naming later and change it throughout the document. That's fine with me. But I don't see that as a blocker for this PR now.

[AxelNennker]

I still hope that we can have the offline access / refresh token text in https://github.com/camaraproject/IdentityAndConsentManagement/pull/121 and not here. I think the GSMA text is too operator specific. I suggested some changes but even with them applied this GSMA text appears to be to not-necessary I think the text I added this morning to #121 covers refresh token usage in authorization code flow and CIBA - there really no difference. I am going to review the refresh token issuance text again. That is part of authorization code flow section and there text for CIBA is probably written by me today.

[AxelNennker]

Closing this as agreed during the March 13th ICM meeting.