From e1b7a6d26a7e8fa31034ac6d22464aa0ec155291 Mon Sep 17 00:00:00 2001 From: David Shanske Date: Sun, 29 Aug 2021 01:43:53 +0000 Subject: [PATCH 1/7] Refresh Tokens --- public/source/index.php | 51 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/public/source/index.php b/public/source/index.php index cc25f5b..c46bfff 100644 --- a/public/source/index.php +++ b/public/source/index.php @@ -531,7 +531,17 @@

The specifics of how the token endpoint verifies the authorization code are out of scope of this document, as typically the authorization endpoint and token endpoint are part of the same system and can share storage or another private communication mechanism.

-

If the request is valid, then the token endpoint can generate an access token and return the appropriate response. The token response is a JSON [[!RFC7159]] object containing the OAuth 2.0 Bearer Token [[!RFC6750]], as well as a property me, containing the canonical user profile URL for the user this access token corresponds to, and optionally the property profile with the user's profile information as defined in Profile Information. For example:

+

If the request is valid, then the token endpoint can generate an access token and return the appropriate response. The token response is a JSON [[!RFC7159]] object containing:

+ + + +

For example:

HTTP/1.1 200 OK
 Content-Type: application/json
@@ -540,7 +550,7 @@
   "access_token": "XXXXXX",
   "token_type": "Bearer",
   "scope": "create update delete",
-  "me": "https://user.example.net/"
+  "me": "https://user.example.net/",
 }

The resulting profile URL MAY be different from the URL provided to the client for discovery. This gives the authorization server an opportunity to canonicalize the user's URL, such as correcting http to https, or adding a path if required. See Differing User Profile URLs for security considerations client developers should be aware of.

@@ -679,6 +689,43 @@ +
+

Refresh Tokens

+ +

Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

+ +

Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, the client MAY obtain new access tokens by starting the authorization flow over.

+ +

Authorization servers MAY revoke refresh tokens automatically in case of a security event, such as a password change or a logout at the authorization server, or when they are redeemed, in which case a new refresh token MAY be provided. Refresh tokens SHOULD expire if the client has been inactive for some time, i.e., the refresh token has not been used to obtain fresh access tokens for some time. The expiration time is at the discretion of the authorization server.

+ +

The authorization server validates the refresh token, and if valid, issues a new access token (and, optionally, a new refresh token). + +

+

Refreshing an Access Token

+ +

To refresh an access token, the client makes a POST request to the token endpoint to exchange the refresh token for the new access token. The POST request contains the following parameters:

+ +
    +
  • grant_type=refresh_token
    • +
  • refresh_token - The refresh token previously offered to the client.
    • +
  • scope (optional) - The client may request a token with the same or fewer scopes than the original access token. If omitted, is treated as equal to the original scopes granted.
    • +
+ +

For example:

+ +
+ +

If valid and authorized, the authorization server issues an access token as noted in Access Token Response. If an authorization server chooses to issue a new refresh token, then the refresh token scope MUST be identical to the one included by the client in the request.

+ +
+
From 6393d1af2ac2cfbe5c778670223286eb095c9153 Mon Sep 17 00:00:00 2001 From: David Shanske Date: Mon, 6 Sep 2021 06:06:31 +0000 Subject: [PATCH 2/7] Clarify that a refresh token may be used at any time, not just when near expiry --- public/source/index.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/source/index.php b/public/source/index.php index c46bfff..5bac677 100644 --- a/public/source/index.php +++ b/public/source/index.php @@ -692,7 +692,7 @@

Refresh Tokens

-

Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

+

Refresh tokens are issued to the client by the authorization server and MAY be used at any time to obtain a new access token, usually when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, the client MAY obtain new access tokens by starting the authorization flow over.

From 62fec5fee43464679eaca9145d30249406f0e6b0 Mon Sep 17 00:00:00 2001 From: David Shanske Date: Sat, 11 Sep 2021 08:10:16 -0400 Subject: [PATCH 3/7] Missing close tag Co-authored-by: Jamie Tanna --- public/source/index.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/source/index.php b/public/source/index.php index 5bac677..da08fc9 100644 --- a/public/source/index.php +++ b/public/source/index.php @@ -534,7 +534,7 @@

If the request is valid, then the token endpoint can generate an access token and return the appropriate response. The token response is a JSON [[!RFC7159]] object containing:

    -
  • access_token (required) - the OAuth 2.0 Bearer Token [[!RFC6750]].
  • +
  • access_token (required) - the OAuth 2.0 Bearer Token [[!RFC6750]].
  • me (required) - the canonical user profile URL for the user this access token corresponds to.
  • profile (optional) - the user's profile information as defined in Profile Information.
  • expires_in (recommended) - The lifetime in seconds of the access token. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.
    • From 42779941764f58e5038a71a31f8d73e76f8c2f80 Mon Sep 17 00:00:00 2001 From: David Shanske Date: Sat, 11 Sep 2021 08:13:46 -0400 Subject: [PATCH 4/7] Errant comma Co-authored-by: Jamie Tanna --- public/source/index.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/source/index.php b/public/source/index.php index da08fc9..abfbb34 100644 --- a/public/source/index.php +++ b/public/source/index.php @@ -550,7 +550,7 @@ "access_token": "XXXXXX", "token_type": "Bearer", "scope": "create update delete", - "me": "https://user.example.net/", + "me": "https://user.example.net/" }

    The resulting profile URL MAY be different from the URL provided to the client for discovery. This gives the authorization server an opportunity to canonicalize the user's URL, such as correcting http to https, or adding a path if required. See Differing User Profile URLs for security considerations client developers should be aware of.

    From f4c59f51ca66ebc8c6cd66652241f4c2b7cb90d1 Mon Sep 17 00:00:00 2001 From: David Shanske Date: Sat, 11 Sep 2021 08:14:25 -0400 Subject: [PATCH 5/7] Note that it could be triggered in the consent flow. Co-authored-by: Jamie Tanna --- public/source/index.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/source/index.php b/public/source/index.php index abfbb34..1152433 100644 --- a/public/source/index.php +++ b/public/source/index.php @@ -694,7 +694,7 @@

    Refresh tokens are issued to the client by the authorization server and MAY be used at any time to obtain a new access token, usually when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

    -

    Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, the client MAY obtain new access tokens by starting the authorization flow over.

    +

    Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, a choice by the user authorizing the request or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, the client MAY obtain new access tokens by starting the authorization flow over.

    Authorization servers MAY revoke refresh tokens automatically in case of a security event, such as a password change or a logout at the authorization server, or when they are redeemed, in which case a new refresh token MAY be provided. Refresh tokens SHOULD expire if the client has been inactive for some time, i.e., the refresh token has not been used to obtain fresh access tokens for some time. The expiration time is at the discretion of the authorization server.

    From a454f167e45829532411d99a423ac4ea9a3a21ce Mon Sep 17 00:00:00 2001 From: David Shanske Date: Fri, 24 Sep 2021 00:16:57 +0000 Subject: [PATCH 6/7] Make suggested updates --- public/source/index.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/public/source/index.php b/public/source/index.php index 1152433..75aeed5 100644 --- a/public/source/index.php +++ b/public/source/index.php @@ -537,7 +537,7 @@
  • access_token (required) - the OAuth 2.0 Bearer Token [[!RFC6750]].
  • me (required) - the canonical user profile URL for the user this access token corresponds to.
  • profile (optional) - the user's profile information as defined in Profile Information.
    • -
  • expires_in (recommended) - The lifetime in seconds of the access token. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.
    • +
  • expires_in (recommended) - The lifetime in seconds of the access token.
  • refresh_token (optional) - The refresh token, which can be used to obtain new access tokens as defined in Refresh Tokens.
@@ -692,14 +692,12 @@

Refresh Tokens

-

Refresh tokens are issued to the client by the authorization server and MAY be used at any time to obtain a new access token, usually when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

+

Refresh tokens are issued to the client by the authorization server and MAY be used at any time to obtain a new access token, usually when the current access token becomes invalid or expires, or to obtain a new token with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, a choice by the user authorizing the request or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, the client MAY obtain new access tokens by starting the authorization flow over.

Authorization servers MAY revoke refresh tokens automatically in case of a security event, such as a password change or a logout at the authorization server, or when they are redeemed, in which case a new refresh token MAY be provided. Refresh tokens SHOULD expire if the client has been inactive for some time, i.e., the refresh token has not been used to obtain fresh access tokens for some time. The expiration time is at the discretion of the authorization server.

-

The authorization server validates the refresh token, and if valid, issues a new access token (and, optionally, a new refresh token). -

Refreshing an Access Token

@@ -708,6 +706,7 @@
  • grant_type=refresh_token
  • refresh_token - The refresh token previously offered to the client.
    • +
  • client_id - The client ID that was used when the refresh token was issued.
  • scope (optional) - The client may request a token with the same or fewer scopes than the original access token. If omitted, is treated as equal to the original scopes granted.
@@ -719,10 +718,11 @@ Accept: application/json grant_type=refresh_token -&refresh_token=xxxxxxxx +&refresh_token=xxxxxxxx&client_id=https://app.example.com ') ?> -

If valid and authorized, the authorization server issues an access token as noted in Access Token Response. If an authorization server chooses to issue a new refresh token, then the refresh token scope MUST be identical to the one included by the client in the request.

+

If valid and authorized, the authorization server issues an access token as noted in Access Token Response. The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client. If a new refresh token is issued, the refresh token scope MUST be identical to that of the refresh token included by the client in the request.

+

Refresh tokens SHOULD expire if the client has been inactive for some time, i.e., the refresh token has not been used to obtain new access tokens for some time. The expiration time is at the discretion of the authorization server.

From a5badecd7daa74d4f3d8e778e1c4a112f5ae28de Mon Sep 17 00:00:00 2001 From: Aaron Parecki Date: Wed, 13 Oct 2021 12:21:56 -0700 Subject: [PATCH 7/7] Update public/source/index.php Co-authored-by: Jamie Tanna --- public/source/index.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/source/index.php b/public/source/index.php index 3ed22fe..42bd8d1 100644 --- a/public/source/index.php +++ b/public/source/index.php @@ -694,7 +694,7 @@

Refresh tokens are issued to the client by the authorization server and MAY be used at any time to obtain a new access token, usually when the current access token becomes invalid or expires, or to obtain a new token with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

-

Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, a choice by the user authorizing the request or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, the client MAY obtain new access tokens by starting the authorization flow over.

+

Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, a choice by the user authorizing the request or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, or the refresh token expires, the client MAY obtain new access tokens by starting the authorization flow over.

Authorization servers MAY revoke refresh tokens automatically in case of a security event, such as a password change or a logout at the authorization server, or when they are redeemed, in which case a new refresh token MAY be provided. Refresh tokens SHOULD expire if the client has been inactive for some time, i.e., the refresh token has not been used to obtain fresh access tokens for some time. The expiration time is at the discretion of the authorization server.