├── .circleci └── config.yml ├── .editorconfig ├── .github ├── CODEOWNERS └── workflows │ ├── archive.yml │ ├── ghpages.yml │ ├── publish.yml │ └── update.yml ├── .gitignore ├── .note.xml ├── CONTRIBUTING.md ├── LICENSE.md ├── Makefile ├── README.md ├── draft-ietf-oauth-v2-1.md └── oauth-v2-0.md /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | jobs: 3 | build: 4 | docker: 5 | - image: martinthomson/i-d-template:latest 6 | resource_class: small 7 | working_directory: ~/draft 8 | 9 | steps: 10 | - run: 11 | name: "Print Configuration" 12 | command: | 13 | xml2rfc --version 14 | gem list -q kramdown-rfc 15 | echo -n 'mmark '; mmark --version 16 | 17 | - restore_cache: 18 | name: "Restoring cache - Git" 19 | keys: 20 | - v2-cache-git-{{ .Branch }}-{{ .Revision }} 21 | - v2-cache-git-{{ .Branch }} 22 | - v2-cache-git- 23 | 24 | - restore_cache: 25 | name: "Restoring cache - References" 26 | keys: 27 | - v1-cache-references-{{ epoch }} 28 | - v1-cache-references- 29 | 30 | # Workaround for https://discuss.circleci.com/t/22437 31 | - run: 32 | name: Tag Checkout 33 | command: | 34 | if [ -n "$CIRCLE_TAG" ] && [ -d .git ]; then 35 | remote=$(echo "$CIRCLE_REPOSITORY_URL" | \ 36 | sed -e 's,/^git.github.com:,https://github.com/,') 37 | git fetch -f "$remote" "refs/tags/$CIRCLE_TAG:refs/tags/$CIRCLE_TAG" || \ 38 | (echo 'Removing .git cache for tag build'; rm -rf .git) 39 | fi 40 | 41 | - checkout 42 | 43 | # Build txt and html versions of drafts 44 | - run: 45 | name: "Build Drafts" 46 | command: make 47 | 48 | # Update editor's copy on gh-pages 49 | - run: 50 | name: "Update GitHub Pages" 51 | command: | 52 | if [ "${CIRCLE_TAG#draft-}" == "$CIRCLE_TAG" ]; then 53 | make gh-pages 54 | fi 55 | 56 | # For tagged builds, upload to the datatracker. 57 | - deploy: 58 | name: "Upload to Datatracker" 59 | command: | 60 | if [ "${CIRCLE_TAG#draft-}" != "$CIRCLE_TAG" ]; then 61 | make upload 62 | fi 63 | 64 | # Archive GitHub Issues 65 | - run: 66 | name: "Archive GitHub Issues" 67 | command: "make archive || make archive DISABLE_ARCHIVE_FETCH=true && make gh-archive" 68 | 69 | # Create and store artifacts 70 | - run: 71 | name: "Create Artifacts" 72 | command: "make artifacts CI_ARTIFACTS=/tmp/artifacts" 73 | 74 | - store_artifacts: 75 | path: /tmp/artifacts 76 | 77 | - run: 78 | name: "Prepare for Caching" 79 | command: "git reflog expire --expire=now --all && git gc --prune=now" 80 | 81 | - save_cache: 82 | name: "Saving Cache - Git" 83 | key: v2-cache-git-{{ .Branch }}-{{ .Revision }} 84 | paths: 85 | - ~/draft/.git 86 | 87 | - save_cache: 88 | name: "Saving Cache - Drafts" 89 | key: v1-cache-references-{{ epoch }} 90 | paths: 91 | - ~/.cache/xml2rfc 92 | 93 | 94 | workflows: 95 | version: 2 96 | build: 97 | jobs: 98 | - build: 99 | filters: 100 | tags: 101 | only: /.*?/ 102 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # See http://editorconfig.org 2 | 3 | root = true 4 | 5 | [*.{md,xml,org}] 6 | charset = utf-8 7 | insert_final_newline = true 8 | trim_trailing_whitespace = true 9 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Automatically generated CODEOWNERS 2 | # Regenerate with `make update-codeowners` 3 | draft-ietf-oauth-v2-1.md dick.hardt@gmail.com aaron@parecki.com torsten@lodderstedt.net 4 | -------------------------------------------------------------------------------- /.github/workflows/archive.yml: -------------------------------------------------------------------------------- 1 | name: "Archive Issues and Pull Requests" 2 | 3 | on: 4 | schedule: 5 | - cron: '0 0 * * 0,2,4' 6 | repository_dispatch: 7 | types: [archive] 8 | workflow_dispatch: 9 | 10 | jobs: 11 | build: 12 | name: "Archive Issues and Pull Requests" 13 | runs-on: ubuntu-latest 14 | steps: 15 | - name: "Checkout" 16 | uses: actions/checkout@v2 17 | 18 | - name: "Update Archive" 19 | uses: martinthomson/i-d-template@v1 20 | with: 21 | make: archive 22 | token: ${{ github.token }} 23 | 24 | - name: "Update GitHub Pages" 25 | uses: martinthomson/i-d-template@v1 26 | with: 27 | make: gh-archive 28 | token: ${{ github.token }} 29 | 30 | - name: "Save Archive" 31 | uses: actions/upload-artifact@v4 32 | with: 33 | path: archive.json 34 | -------------------------------------------------------------------------------- /.github/workflows/ghpages.yml: -------------------------------------------------------------------------------- 1 | name: "Update Editor's Copy" 2 | 3 | on: 4 | push: 5 | paths-ignore: 6 | - README.md 7 | - CONTRIBUTING.md 8 | - LICENSE.md 9 | - .gitignore 10 | pull_request: 11 | paths-ignore: 12 | - README.md 13 | - CONTRIBUTING.md 14 | - LICENSE.md 15 | - .gitignore 16 | 17 | jobs: 18 | build: 19 | name: "Update Editor's Copy" 20 | runs-on: ubuntu-latest 21 | env: 22 | BUNDLE_PATH: /tmp/.gems 23 | VENVDIR: /tmp/.venv 24 | steps: 25 | - name: "Checkout" 26 | uses: actions/checkout@v3 27 | 28 | - name: "Setup" 29 | id: setup 30 | run: date -u "+::set-output name=date::%FT%T" 31 | 32 | - name: "Caching" 33 | uses: actions/cache@v3 34 | with: 35 | path: | 36 | ${{ env.XML2RFC_REFCACHEDIR }} 37 | ${{ env.VENVDIR }} 38 | ${{ env.BUNDLE_PATH }} 39 | node_modules 40 | .targets.mk 41 | key: i-d-${{ steps.setup.outputs.date }} 42 | restore-keys: i-d- 43 | 44 | - name: "Build Drafts" 45 | uses: martinthomson/i-d-template@v1 46 | with: 47 | token: ${{ github.token }} 48 | 49 | - name: "Update GitHub Pages" 50 | uses: martinthomson/i-d-template@v1 51 | if: ${{ github.event_name == 'push' }} 52 | with: 53 | make: gh-pages 54 | token: ${{ github.token }} 55 | 56 | - name: "Archive Built Drafts" 57 | uses: actions/upload-artifact@v4 58 | with: 59 | path: | 60 | draft-*.html 61 | draft-*.txt 62 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: "Publish New Draft Version" 2 | 3 | on: 4 | push: 5 | tags: 6 | - "draft-*" 7 | 8 | jobs: 9 | build: 10 | name: "Publish New Draft Version" 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: "Checkout" 14 | uses: actions/checkout@v3 15 | 16 | # See https://github.com/actions/checkout/issues/290 17 | - name: "Get Tag Annotations" 18 | run: git fetch -f origin ${{ github.ref }}:${{ github.ref }} 19 | 20 | - name: "Setup" 21 | id: setup 22 | run: date -u "+::set-output name=date::%FT%T" 23 | 24 | - name: "Caching" 25 | uses: actions/cache@v3 26 | with: 27 | path: | 28 | ${{ env.XML2RFC_REFCACHEDIR }} 29 | ${{ env.VENVDIR }} 30 | ${{ env.BUNDLE_PATH }} 31 | node_modules 32 | .targets.mk 33 | key: i-d-${{ steps.setup.outputs.date }} 34 | restore-keys: i-d- 35 | 36 | - name: "Build Drafts" 37 | uses: martinthomson/i-d-template@v1 38 | with: 39 | token: ${{ github.token }} 40 | 41 | - name: "Upload to Datatracker" 42 | uses: martinthomson/i-d-template@v1 43 | with: 44 | make: upload 45 | 46 | - name: "Archive Submitted Drafts" 47 | uses: actions/upload-artifact@v4 48 | with: 49 | path: "draft-*-[0-9][0-9].xml" 50 | -------------------------------------------------------------------------------- /.github/workflows/update.yml: -------------------------------------------------------------------------------- 1 | name: "Update Generated Files" 2 | # This rule is not run automatically. 3 | # It can be run manually to update all of the files that are part 4 | # of the template, specifically: 5 | # - README.md 6 | # - CONTRIBUTING.md 7 | # - .note.xml 8 | # - .github/CODEOWNERS 9 | # - Makefile 10 | # 11 | # 12 | # This might be useful if you have: 13 | # - added, removed, or renamed drafts (including after adoption) 14 | # - added, removed, or changed draft editors 15 | # - changed the title of drafts 16 | # 17 | # Note that this removes any customizations you have made to 18 | # the affected files. 19 | on: workflow_dispatch 20 | 21 | jobs: 22 | build: 23 | name: "Update Files" 24 | runs-on: ubuntu-latest 25 | steps: 26 | - name: "Checkout" 27 | uses: actions/checkout@v2 28 | 29 | - name: "Update Generated Files" 30 | uses: martinthomson/i-d-template@v1 31 | with: 32 | make: update-files 33 | token: ${{ github.token }} 34 | 35 | - name: "Push Update" 36 | run: git push 37 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | *.pdf 3 | *.redxml 4 | *.swp 5 | *.txt 6 | *.upload 7 | *~ 8 | .tags 9 | /*-[0-9][0-9].xml 10 | /.refcache 11 | /.targets.mk 12 | /.vscode/ 13 | /lib 14 | /node_modules/ 15 | /versioned/ 16 | Gemfile.lock 17 | archive.json 18 | draft-ietf-oauth-v2-1.xml 19 | package-lock.json 20 | report.xml 21 | .DS_Store 22 | -------------------------------------------------------------------------------- /.note.xml: -------------------------------------------------------------------------------- 1 | 2 | Discussion of this document takes place on the 3 | OAuth Working Group mailing list (oauth@ietf.org), 4 | which is archived at . 5 | Source for this draft and an issue tracker can be found at 6 | . 7 | 8 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | This repository relates to activities in the Internet Engineering Task Force 4 | ([IETF](https://www.ietf.org/)). All material in this repository is considered 5 | Contributions to the IETF Standards Process, as defined in the intellectual 6 | property policies of IETF currently designated as 7 | [BCP 78](https://www.rfc-editor.org/info/bcp78), 8 | [BCP 79](https://www.rfc-editor.org/info/bcp79) and the 9 | [IETF Trust Legal Provisions (TLP) Relating to IETF Documents](http://trustee.ietf.org/trust-legal-provisions.html). 10 | 11 | Any edit, commit, pull request, issue, comment or other change made to this 12 | repository constitutes Contributions to the IETF Standards Process 13 | (https://www.ietf.org/). 14 | 15 | You agree to comply with all applicable IETF policies and procedures, including, 16 | BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being 17 | subject to a Simplified BSD License) in Contributions. 18 | 19 | ## Working Group Information 20 | 21 | Discussion of this work occurs on the [Web Authorization Protocol 22 | Working Group mailing list](mailto:oauth@ietf.org) 23 | ([archive](https://mailarchive.ietf.org/arch/browse/oauth/), 24 | [subscribe](https://www.ietf.org/mailman/listinfo/oauth)). 25 | In addition to contributions in GitHub, you are encouraged to participate in 26 | discussions there. 27 | 28 | **Note**: Some working groups adopt a policy whereby substantive discussion of 29 | technical issues needs to occur on the mailing list. 30 | 31 | You might also like to familiarize yourself with other 32 | [Working Group documents](https://datatracker.ietf.org/wg/oauth/documents/). 33 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # License 2 | 3 | See the 4 | [guidelines for contributions](https://github.com/oauth-wg/oauth-v2-1/blob/main/CONTRIBUTING.md). 5 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | LIBDIR := lib 2 | include $(LIBDIR)/main.mk 3 | 4 | $(LIBDIR)/main.mk: 5 | ifneq (,$(shell grep "path *= *$(LIBDIR)" .gitmodules 2>/dev/null)) 6 | git submodule sync 7 | git submodule update $(CLONE_ARGS) --init 8 | else 9 | git clone -q --depth 10 $(CLONE_ARGS) \ 10 | -b main https://github.com/martinthomson/i-d-template $(LIBDIR) 11 | endif 12 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The OAuth 2.1 Authorization Framework 2 | 3 | This is the working area for the IETF [OAUTH Working Group](https://datatracker.ietf.org/wg/oauth/documents/) Internet-Draft, "The OAuth 2.1 Authorization Framework". 4 | 5 | * [Editor's Copy](https://drafts.oauth.net/oauth-v2-1/draft-ietf-oauth-v2-1.html) 6 | * [Datatracker Page](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1) 7 | * [Working Group Draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1) 8 | 9 | 10 | 11 | ## Contributing 12 | 13 | See the 14 | [guidelines for contributions](https://github.com/oauth-wg/oauth-v2-1/blob/main/CONTRIBUTING.md). 15 | 16 | Contributions can be made by creating pull requests. 17 | The GitHub interface supports creating pull requests using the Edit (✏) button. 18 | 19 | 20 | ## Command Line Usage 21 | 22 | Formatted text and HTML versions of the draft can be built using `make`. 23 | 24 | ```sh 25 | $ make 26 | ``` 27 | 28 | Command line usage requires that you have the necessary software installed. See 29 | [the instructions](https://github.com/martinthomson/i-d-template/blob/main/doc/SETUP.md). 30 | 31 | -------------------------------------------------------------------------------- /oauth-v2-0.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: The OAuth 2.0 Authorization Framework 3 | docname: rfc6749 4 | date: 2012-10-01 5 | 6 | ipr: trust200902 7 | area: OAuth 8 | kw: Internet-Draft 9 | cat: std 10 | 11 | coding: us-ascii 12 | pi: 13 | toc: yes 14 | sortrefs: yes 15 | symrefs: yes 16 | 17 | author: 18 | - 19 | ins: D. Hardt 20 | name: Dick Hardt 21 | email: dick.hardt@gmail.com 22 | uri: http://dickhardt.org 23 | 24 | normative: 25 | RFC2119: 26 | RFC2246: 27 | RFC2616: 28 | RFC2617: 29 | RFC2818: 30 | RFC3629: 31 | RFC3986: 32 | RFC4627: 33 | RFC4949: 34 | RFC5226: 35 | RFC5234: 36 | RFC5246: 37 | RFC6125: 38 | USASCII: 39 | title: "Coded Character Set -- 7-bit American Standard Code for Information Interchange, ANSI X3.4" 40 | author: 41 | name: "American National Standards Institute" 42 | date: 1986 43 | W3C.REC-html401-19991224: 44 | W3C.REC-xml-20081126: 45 | 46 | informative: 47 | OAuth-HTTP-MAC: 48 | title: "Message Authentication Code (MAC) Tokens" 49 | author: 50 | - name: Justin Richer 51 | ins: J. Richer 52 | org: The MITRE Corporation 53 | - name: William Mills 54 | ins: W. Mills 55 | org: Yahoo! Inc. 56 | - name: Hannes Tschofenig 57 | ins: H. Tschofenig 58 | - name: Phil Hunt 59 | ins: P. Hunt 60 | org: Oracle Corporation 61 | date: 2014-01-15 62 | RFC7522: 63 | RFC6819: 64 | RFC5849: 65 | RFC6750: 66 | 67 | 68 | --- abstract 69 | 70 | The OAuth 2.0 authorization framework enables a third-party 71 | application to obtain limited access to an HTTP service, either on 72 | behalf of a resource owner by orchestrating an approval interaction 73 | between the resource owner and the HTTP service, or by allowing the 74 | third-party application to obtain access on its own behalf. This 75 | specification replaces and obsoletes the OAuth 1.0 protocol described 76 | in RFC 5849. 77 | 78 | --- middle 79 | 80 | # Introduction {#introduction} 81 | 82 | In the traditional client-server authentication model, the client 83 | requests an access-restricted resource (protected resource) on the 84 | server by authenticating with the server using the resource owner's 85 | credentials. In order to provide third-party applications access to 86 | restricted resources, the resource owner shares its credentials with 87 | the third party. This creates several problems and limitations: 88 | 89 | * Third-party applications are required to store the resource 90 | owner's credentials for future use, typically a password in 91 | clear-text. 92 | 93 | * Servers are required to support password authentication, despite 94 | the security weaknesses inherent in passwords. 95 | 96 | * Third-party applications gain overly broad access to the resource 97 | owner's protected resources, leaving resource owners without any 98 | ability to restrict duration or access to a limited subset of 99 | resources. 100 | 101 | * Resource owners cannot revoke access to an individual third party 102 | without revoking access to all third parties, and must do so by 103 | changing the third party's password. 104 | 105 | * Compromise of any third-party application results in compromise of 106 | the end-user's password and all of the data protected by that 107 | password. 108 | 109 | OAuth addresses these issues by introducing an authorization layer 110 | and separating the role of the client from that of the resource 111 | owner. In OAuth, the client requests access to resources controlled 112 | by the resource owner and hosted by the resource server, and is 113 | issued a different set of credentials than those of the resource 114 | owner. 115 | 116 | Instead of using the resource owner's credentials to access protected 117 | resources, the client obtains an access token -- a string denoting a 118 | specific scope, lifetime, and other access attributes. Access tokens 119 | are issued to third-party clients by an authorization server with the 120 | approval of the resource owner. The client uses the access token to 121 | access the protected resources hosted by the resource server. 122 | 123 | For example, an end-user (resource owner) can grant a printing 124 | service (client) access to her protected photos stored at a photo- 125 | sharing service (resource server), without sharing her username and 126 | password with the printing service. Instead, she authenticates 127 | directly with a server trusted by the photo-sharing service 128 | (authorization server), which issues the printing service delegation- 129 | specific credentials (access token). 130 | 131 | This specification is designed for use with HTTP ({{RFC2616}}). The 132 | use of OAuth over any protocol other than HTTP is out of scope. 133 | 134 | The OAuth 1.0 protocol ({{RFC5849}}), published as an informational 135 | document, was the result of a small ad hoc community effort. This 136 | Standards Track specification builds on the OAuth 1.0 deployment 137 | experience, as well as additional use cases and extensibility 138 | requirements gathered from the wider IETF community. The OAuth 2.0 139 | protocol is not backward compatible with OAuth 1.0. The two versions 140 | may co-exist on the network, and implementations may choose to 141 | support both. However, it is the intention of this specification 142 | that new implementations support OAuth 2.0 as specified in this 143 | document and that OAuth 1.0 is used only to support existing 144 | deployments. The OAuth 2.0 protocol shares very few implementation 145 | details with the OAuth 1.0 protocol. Implementers familiar with 146 | OAuth 1.0 should approach this document without any assumptions as to 147 | its structure and details. 148 | 149 | 150 | ## Roles 151 | 152 | OAuth defines four roles: 153 | 154 | "resource owner": 155 | : An entity capable of granting access to a protected resource. 156 | When the resource owner is a person, it is referred to as an 157 | end-user. 158 | 159 | "resource server": 160 | : The server hosting the protected resources, capable of accepting 161 | and responding to protected resource requests using access tokens. 162 | 163 | "client": 164 | : An application making protected resource requests on behalf of the 165 | resource owner and with its authorization. The term "client" does 166 | not imply any particular implementation characteristics (e.g., 167 | whether the application executes on a server, a desktop, or other 168 | devices). 169 | 170 | "authorization server": 171 | : The server issuing access tokens to the client after successfully 172 | authenticating the resource owner and obtaining authorization. 173 | 174 | The interaction between the authorization server and resource server 175 | is beyond the scope of this specification. The authorization server 176 | may be the same server as the resource server or a separate entity. 177 | A single authorization server may issue access tokens accepted by 178 | multiple resource servers. 179 | 180 | 181 | ## Protocol Flow 182 | 183 | ~~~~~~~~~~ 184 | +--------+ +---------------+ 185 | | |--(1)- Authorization Request ->| Resource | 186 | | | | Owner | 187 | | |<-(2)-- Authorization Grant ---| | 188 | | | +---------------+ 189 | | | 190 | | | +---------------+ 191 | | |--(3)-- Authorization Grant -->| Authorization | 192 | | Client | | Server | 193 | | |<-(4)----- Access Token -------| | 194 | | | +---------------+ 195 | | | 196 | | | +---------------+ 197 | | |--(5)----- Access Token ------>| Resource | 198 | | | | Server | 199 | | |<-(6)--- Protected Resource ---| | 200 | +--------+ +---------------+ 201 | ~~~~~~~~~~ 202 | {: #fig-protocol-flow title="Abstract Protocol Flow"} 203 | 204 | The abstract OAuth 2.0 flow illustrated in {{fig-protocol-flow}} describes the 205 | interaction between the four roles and includes the following steps: 206 | 207 | 1. The client requests authorization from the resource owner. The 208 | authorization request can be made directly to the resource owner 209 | (as shown), or preferably indirectly via the authorization 210 | server as an intermediary. 211 | 212 | 2. The client receives an authorization grant, which is a 213 | credential representing the resource owner's authorization, 214 | expressed using one of four grant types defined in this 215 | specification or using an extension grant type. The 216 | authorization grant type depends on the method used by the 217 | client to request authorization and the types supported by the 218 | authorization server. 219 | 220 | 3. The client requests an access token by authenticating with the 221 | authorization server and presenting the authorization grant. 222 | 223 | 4. The authorization server authenticates the client and validates 224 | the authorization grant, and if valid, issues an access token. 225 | 226 | 5. The client requests the protected resource from the resource 227 | server and authenticates by presenting the access token. 228 | 229 | 6. The resource server validates the access token, and if valid, 230 | serves the request. 231 | 232 | The preferred method for the client to obtain an authorization grant 233 | from the resource owner (depicted in steps (1) and (2)) is to use the 234 | authorization server as an intermediary, which is illustrated in 235 | Figure 3 in Section 4.1. 236 | 237 | 238 | ## Authorization Grant 239 | 240 | An authorization grant is a credential representing the resource 241 | owner's authorization (to access its protected resources) used by the 242 | client to obtain an access token. This specification defines four 243 | grant types -- authorization code, implicit, resource owner password 244 | credentials, and client credentials -- as well as an extensibility 245 | mechanism for defining additional types. 246 | 247 | 248 | ### Authorization Code 249 | 250 | The authorization code is obtained by using an authorization server 251 | as an intermediary between the client and resource owner. Instead of 252 | requesting authorization directly from the resource owner, the client 253 | directs the resource owner to an authorization server (via its 254 | user-agent as defined in {{RFC2616}}), which in turn directs the 255 | resource owner back to the client with the authorization code. 256 | 257 | Before directing the resource owner back to the client with the 258 | authorization code, the authorization server authenticates the 259 | resource owner and obtains authorization. Because the resource owner 260 | only authenticates with the authorization server, the resource 261 | owner's credentials are never shared with the client. 262 | 263 | The authorization code provides a few important security benefits, 264 | such as the ability to authenticate the client, as well as the 265 | transmission of the access token directly to the client without 266 | passing it through the resource owner's user-agent and potentially 267 | exposing it to others, including the resource owner. 268 | 269 | 270 | ### Implicit 271 | 272 | The implicit grant is a simplified authorization code flow optimized 273 | for clients implemented in a browser using a scripting language such 274 | as JavaScript. In the implicit flow, instead of issuing the client 275 | an authorization code, the client is issued an access token directly 276 | (as the result of the resource owner authorization). The grant type 277 | is implicit, as no intermediate credentials (such as an authorization 278 | code) are issued (and later used to obtain an access token). 279 | 280 | When issuing an access token during the implicit grant flow, the 281 | authorization server does not authenticate the client. In some 282 | cases, the client identity can be verified via the redirection URI 283 | used to deliver the access token to the client. The access token may 284 | be exposed to the resource owner or other applications with access to 285 | the resource owner's user-agent. 286 | 287 | Implicit grants improve the responsiveness and efficiency of some 288 | clients (such as a client implemented as an in-browser application), 289 | since it reduces the number of round trips required to obtain an 290 | access token. However, this convenience should be weighed against 291 | the security implications of using implicit grants, such as those 292 | described in Sections 10.3 and 10.16, especially when the 293 | authorization code grant type is available. 294 | 295 | 296 | ### Resource Owner Password Credentials 297 | 298 | The resource owner password credentials (i.e., username and password) 299 | can be used directly as an authorization grant to obtain an access 300 | token. The credentials should only be used when there is a high 301 | degree of trust between the resource owner and the client (e.g., the 302 | client is part of the device operating system or a highly privileged 303 | application), and when other authorization grant types are not 304 | available (such as an authorization code). 305 | 306 | Even though this grant type requires direct client access to the 307 | resource owner credentials, the resource owner credentials are used 308 | for a single request and are exchanged for an access token. This 309 | grant type can eliminate the need for the client to store the 310 | resource owner credentials for future use, by exchanging the 311 | credentials with a long-lived access token or refresh token. 312 | 313 | ### Client Credentials 314 | 315 | The client credentials (or other forms of client authentication) can 316 | be used as an authorization grant when the authorization scope is 317 | limited to the protected resources under the control of the client, 318 | or to protected resources previously arranged with the authorization 319 | server. Client credentials are used as an authorization grant 320 | typically when the client is acting on its own behalf (the client is 321 | also the resource owner) or is requesting access to protected 322 | resources based on an authorization previously arranged with the 323 | authorization server. 324 | 325 | 326 | ## Access Token 327 | 328 | Access tokens are credentials used to access protected resources. An 329 | access token is a string representing an authorization issued to the 330 | client. The string is usually opaque to the client. Tokens 331 | represent specific scopes and durations of access, granted by the 332 | resource owner, and enforced by the resource server and authorization 333 | server. 334 | 335 | The token may denote an identifier used to retrieve the authorization 336 | information or may self-contain the authorization information in a 337 | verifiable manner (i.e., a token string consisting of some data and a 338 | signature). Additional authentication credentials, which are beyond 339 | the scope of this specification, may be required in order for the 340 | client to use a token. 341 | 342 | The access token provides an abstraction layer, replacing different 343 | authorization constructs (e.g., username and password) with a single 344 | token understood by the resource server. This abstraction enables 345 | issuing access tokens more restrictive than the authorization grant 346 | used to obtain them, as well as removing the resource server's need 347 | to understand a wide range of authentication methods. 348 | 349 | Access tokens can have different formats, structures, and methods of 350 | utilization (e.g., cryptographic properties) based on the resource 351 | server security requirements. Access token attributes and the 352 | methods used to access protected resources are beyond the scope of 353 | this specification and are defined by companion specifications such 354 | as {{RFC6750}}. 355 | 356 | 357 | ## Refresh Token 358 | 359 | Refresh tokens are credentials used to obtain access tokens. Refresh 360 | tokens are issued to the client by the authorization server and are 361 | used to obtain a new access token when the current access token 362 | becomes invalid or expires, or to obtain additional access tokens 363 | with identical or narrower scope (access tokens may have a shorter 364 | lifetime and fewer permissions than authorized by the resource 365 | owner). Issuing a refresh token is optional at the discretion of the 366 | authorization server. If the authorization server issues a refresh 367 | token, it is included when issuing an access token (i.e., step (D) in 368 | Figure 1). 369 | 370 | A refresh token is a string representing the authorization granted to 371 | the client by the resource owner. The string is usually opaque to 372 | the client. The token denotes an identifier used to retrieve the 373 | authorization information. Unlike access tokens, refresh tokens are 374 | intended for use only with authorization servers and are never sent 375 | to resource servers. 376 | 377 | 378 | ~~~~~~~~~~ 379 | +--------+ +---------------+ 380 | | |--(1)------- Authorization Grant --------->| | 381 | | | | | 382 | | |<-(2)----------- Access Token -------------| | 383 | | | & Refresh Token | | 384 | | | | | 385 | | | +----------+ | | 386 | | |--(3)---- Access Token ---->| | | | 387 | | | | | | | 388 | | |<-(4)- Protected Resource --| Resource | | Authorization | 389 | | Client | | Server | | Server | 390 | | |--(5)---- Access Token ---->| | | | 391 | | | | | | | 392 | | |<-(6)- Invalid Token Error -| | | | 393 | | | +----------+ | | 394 | | | | | 395 | | |--(7)----------- Refresh Token ----------->| | 396 | | | | | 397 | | |<-(8)----------- Access Token -------------| | 398 | +--------+ & Optional Refresh Token +---------------+ 399 | ~~~~~~~~~~ 400 | {: #fig-refresh-token-flow title="Refreshing an Expired Access Token"} 401 | 402 | The flow illustrated in {{fig-refresh-token-flow}} includes the following steps: 403 | 404 | 1. The client requests an access token by authenticating with the 405 | authorization server and presenting an authorization grant. 406 | 407 | 2. The authorization server authenticates the client and validates 408 | the authorization grant, and if valid, issues an access token 409 | and a refresh token. 410 | 411 | 3. The client makes a protected resource request to the resource 412 | server by presenting the access token. 413 | 414 | 4. The resource server validates the access token, and if valid, 415 | serves the request. 416 | 417 | 5. Steps (3) and (4) repeat until the access token expires. If the 418 | client knows the access token expired, it skips to step (7); 419 | otherwise, it makes another protected resource request. 420 | 421 | 6. Since the access token is invalid, the resource server returns 422 | an invalid token error. 423 | 424 | 7. The client requests a new access token by authenticating with 425 | the authorization server and presenting the refresh token. The 426 | client authentication requirements are based on the client type 427 | and on the authorization server policies. 428 | 429 | 8. The authorization server authenticates the client and validates 430 | the refresh token, and if valid, issues a new access token (and, 431 | optionally, a new refresh token). 432 | 433 | Steps (3), (4), (5), and (6) are outside the scope of this 434 | specification, as described in Section 7. 435 | 436 | 437 | ## TLS Version 438 | 439 | Whenever Transport Layer Security (TLS) is used by this 440 | specification, the appropriate version (or versions) of TLS will vary 441 | over time, based on the widespread deployment and known security 442 | vulnerabilities. At the time of this writing, TLS version 1.2 443 | {{RFC5246}} is the most recent version, but has a very limited 444 | deployment base and might not be readily available for 445 | implementation. TLS version 1.0 {{RFC2246}} is the most widely 446 | deployed version and will provide the broadest interoperability. 447 | 448 | Implementations MAY also support additional transport-layer security 449 | mechanisms that meet their security requirements. 450 | 451 | 452 | ## HTTP Redirections 453 | 454 | This specification makes extensive use of HTTP redirections, in which 455 | the client or the authorization server directs the resource owner's 456 | user-agent to another destination. While the examples in this 457 | specification show the use of the HTTP 302 status code, any other 458 | method available via the user-agent to accomplish this redirection is 459 | allowed and is considered to be an implementation detail. 460 | 461 | 462 | ## Interoperability 463 | 464 | OAuth 2.0 provides a rich authorization framework with well-defined 465 | security properties. However, as a rich and highly extensible 466 | framework with many optional components, on its own, this 467 | specification is likely to produce a wide range of non-interoperable 468 | implementations. 469 | 470 | In addition, this specification leaves a few required components 471 | partially or fully undefined (e.g., client registration, 472 | authorization server capabilities, endpoint discovery). Without 473 | these components, clients must be manually and specifically 474 | configured against a specific authorization server and resource 475 | server in order to interoperate. 476 | 477 | This framework was designed with the clear expectation that future 478 | work will define prescriptive profiles and extensions necessary to 479 | achieve full web-scale interoperability. 480 | 481 | 482 | ## Notational Conventions 483 | 484 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 485 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 486 | specification are to be interpreted as described in {{RFC2119}}. 487 | 488 | This specification uses the Augmented Backus-Naur Form (ABNF) 489 | notation of {{RFC5234}}. Additionally, the rule URI-reference is 490 | included from "Uniform Resource Identifier (URI): Generic Syntax" 491 | {{RFC3986}}. 492 | 493 | Certain security-related terms are to be understood in the sense 494 | defined in {{RFC4949}}. These terms include, but are not limited to, 495 | "attack", "authentication", "authorization", "certificate", 496 | "confidentiality", "credential", "encryption", "identity", "sign", 497 | "signature", "trust", "validate", and "verify". 498 | 499 | Unless otherwise noted, all the protocol parameter names and values 500 | are case sensitive. 501 | 502 | 503 | # Client Registration 504 | 505 | Before initiating the protocol, the client registers with the 506 | authorization server. The means through which the client registers 507 | with the authorization server are beyond the scope of this 508 | specification but typically involve end-user interaction with an HTML 509 | registration form. 510 | 511 | Client registration does not require a direct interaction between the 512 | client and the authorization server. When supported by the 513 | authorization server, registration can rely on other means for 514 | establishing trust and obtaining the required client properties 515 | (e.g., redirection URI, client type). For example, registration can 516 | be accomplished using a self-issued or third-party-issued assertion, 517 | or by the authorization server performing client discovery using a 518 | trusted channel. 519 | 520 | When registering a client, the client developer SHALL: 521 | 522 | * specify the client type as described in Section 2.1, 523 | 524 | * provide its client redirection URIs as described in Section 3.1.2, 525 | and 526 | 527 | * include any other information required by the authorization server 528 | (e.g., application name, website, description, logo image, the 529 | acceptance of legal terms). 530 | 531 | 532 | ## Client Types 533 | 534 | OAuth defines two client types, based on their ability to 535 | authenticate securely with the authorization server (i.e., ability to 536 | maintain the confidentiality of their client credentials): 537 | 538 | "confidential": 539 | : Clients capable of maintaining the confidentiality of their 540 | credentials (e.g., client implemented on a secure server with 541 | restricted access to the client credentials), or capable of secure 542 | client authentication using other means. 543 | 544 | "public": 545 | : Clients incapable of maintaining the confidentiality of their 546 | credentials (e.g., clients executing on the device used by the 547 | resource owner, such as an installed native application or a web 548 | browser-based application), and incapable of secure client 549 | authentication via any other means. 550 | 551 | The client type designation is based on the authorization server's 552 | definition of secure authentication and its acceptable exposure 553 | levels of client credentials. The authorization server SHOULD NOT 554 | make assumptions about the client type. 555 | 556 | A client may be implemented as a distributed set of components, each 557 | with a different client type and security context (e.g., a 558 | distributed client with both a confidential server-based component 559 | and a public browser-based component). If the authorization server 560 | does not provide support for such clients or does not provide 561 | guidance with regard to their registration, the client SHOULD 562 | register each component as a separate client. 563 | 564 | This specification has been designed around the following client 565 | profiles: 566 | 567 | "web application": 568 | : A web application is a confidential client running on a web 569 | server. Resource owners access the client via an HTML user 570 | interface rendered in a user-agent on the device used by the 571 | resource owner. The client credentials as well as any access 572 | token issued to the client are stored on the web server and are 573 | not exposed to or accessible by the resource owner. 574 | 575 | "user-agent-based application": 576 | : A user-agent-based application is a public client in which the 577 | client code is downloaded from a web server and executes within a 578 | user-agent (e.g., web browser) on the device used by the resource 579 | owner. Protocol data and credentials are easily accessible (and 580 | often visible) to the resource owner. Since such applications 581 | reside within the user-agent, they can make seamless use of the 582 | user-agent capabilities when requesting authorization. 583 | 584 | "native application": 585 | : A native application is a public client installed and executed on 586 | the device used by the resource owner. Protocol data and 587 | credentials are accessible to the resource owner. It is assumed 588 | that any client authentication credentials included in the 589 | application can be extracted. On the other hand, dynamically 590 | issued credentials such as access tokens or refresh tokens can 591 | receive an acceptable level of protection. At a minimum, these 592 | credentials are protected from hostile servers with which the 593 | application may interact. On some platforms, these credentials 594 | might be protected from other applications residing on the same 595 | device. 596 | 597 | ## Client Identifier 598 | 599 | The authorization server issues the registered client a client 600 | identifier -- a unique string representing the registration 601 | information provided by the client. The client identifier is not a 602 | secret; it is exposed to the resource owner and MUST NOT be used 603 | alone for client authentication. The client identifier is unique to 604 | the authorization server. 605 | 606 | The client identifier string size is left undefined by this 607 | specification. The client should avoid making assumptions about the 608 | identifier size. The authorization server SHOULD document the size 609 | of any identifier it issues. 610 | 611 | 612 | ## Client Authentication 613 | 614 | If the client type is confidential, the client and authorization 615 | server establish a client authentication method suitable for the 616 | security requirements of the authorization server. The authorization 617 | server MAY accept any form of client authentication meeting its 618 | security requirements. 619 | 620 | Confidential clients are typically issued (or establish) a set of 621 | client credentials used for authenticating with the authorization 622 | server (e.g., password, public/private key pair). 623 | 624 | The authorization server MAY establish a client authentication method 625 | with public clients. However, the authorization server MUST NOT rely 626 | on public client authentication for the purpose of identifying the 627 | client. 628 | 629 | The client MUST NOT use more than one authentication method in each 630 | request. 631 | 632 | 633 | ### Client Password 634 | 635 | Clients in possession of a client password MAY use the HTTP Basic 636 | authentication scheme as defined in {{RFC2617}} to authenticate with 637 | the authorization server. The client identifier is encoded using the 638 | "application/x-www-form-urlencoded" encoding algorithm per 639 | Appendix B, and the encoded value is used as the username; the client 640 | password is encoded using the same algorithm and used as the 641 | password. The authorization server MUST support the HTTP Basic 642 | authentication scheme for authenticating clients that were issued a 643 | client password. 644 | 645 | For example (with extra line breaks for display purposes only): 646 | 647 | Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 648 | 649 | Alternatively, the authorization server MAY support including the 650 | client credentials in the request-body using the following 651 | parameters: 652 | 653 | "client_id": 654 | : REQUIRED. The client identifier issued to the client during 655 | the registration process described by Section 2.2. 656 | 657 | "client_secret": 658 | : REQUIRED. The client secret. The client MAY omit the 659 | parameter if the client secret is an empty string. 660 | 661 | Including the client credentials in the request-body using the two 662 | parameters is NOT RECOMMENDED and SHOULD be limited to clients unable 663 | to directly utilize the HTTP Basic authentication scheme (or other 664 | password-based HTTP authentication schemes). The parameters can only 665 | be transmitted in the request-body and MUST NOT be included in the 666 | request URI. 667 | 668 | For example, a request to refresh an access token (Section 6) using 669 | the body parameters (with extra line breaks for display purposes 670 | only): 671 | 672 | POST /token HTTP/1.1 673 | Host: server.example.com 674 | Content-Type: application/x-www-form-urlencoded 675 | 676 | grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 677 | &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 678 | 679 | The authorization server MUST require the use of TLS as described in 680 | Section 1.6 when sending requests using password authentication. 681 | 682 | Since this client authentication method involves a password, the 683 | authorization server MUST protect any endpoint utilizing it against 684 | brute force attacks. 685 | 686 | ### Other Authorization Methods 687 | 688 | The authorization server MAY support any suitable HTTP authentication 689 | scheme matching its security requirements. When using other 690 | authentication methods, the authorization server MUST define a 691 | mapping between the client identifier (registration record) and 692 | authentication scheme. 693 | 694 | 695 | ## Unregistered Clients 696 | 697 | This specification does not exclude the use of unregistered clients. 698 | However, the use of such clients is beyond the scope of this 699 | specification and requires additional security analysis and review of 700 | its interoperability impact. 701 | 702 | 703 | # Protocol Endpoints 704 | 705 | The authorization process utilizes two authorization server endpoints 706 | (HTTP resources): 707 | 708 | * Authorization endpoint - used by the client to obtain 709 | authorization from the resource owner via user-agent redirection. 710 | 711 | * Token endpoint - used by the client to exchange an authorization 712 | grant for an access token, typically with client authentication. 713 | 714 | As well as one client endpoint: 715 | 716 | * Redirection endpoint - used by the authorization server to return 717 | responses containing authorization credentials to the client via 718 | the resource owner user-agent. 719 | 720 | Not every authorization grant type utilizes both endpoints. 721 | Extension grant types MAY define additional endpoints as needed. 722 | 723 | 724 | ## Authorization Endpoint 725 | 726 | The authorization endpoint is used to interact with the resource 727 | owner and obtain an authorization grant. The authorization server 728 | MUST first verify the identity of the resource owner. The way in 729 | which the authorization server authenticates the resource owner 730 | (e.g., username and password login, session cookies) is beyond the 731 | scope of this specification. 732 | 733 | The means through which the client obtains the location of the 734 | authorization endpoint are beyond the scope of this specification, 735 | but the location is typically provided in the service documentation. 736 | 737 | The endpoint URI MAY include an "application/x-www-form-urlencoded" 738 | formatted (per Appendix B) query component ({{RFC3986}} Section 3.4), 739 | which MUST be retained when adding additional query parameters. The 740 | endpoint URI MUST NOT include a fragment component. 741 | 742 | Since requests to the authorization endpoint result in user 743 | authentication and the transmission of clear-text credentials (in the 744 | HTTP response), the authorization server MUST require the use of TLS 745 | as described in Section 1.6 when sending requests to the 746 | authorization endpoint. 747 | 748 | The authorization server MUST support the use of the HTTP "GET" 749 | method {{RFC2616}} for the authorization endpoint and MAY support the 750 | use of the "POST" method as well. 751 | 752 | Parameters sent without a value MUST be treated as if they were 753 | omitted from the request. The authorization server MUST ignore 754 | unrecognized request parameters. Request and response parameters 755 | MUST NOT be included more than once. 756 | 757 | ### Response Type 758 | 759 | The authorization endpoint is used by the authorization code grant 760 | type and implicit grant type flows. The client informs the 761 | authorization server of the desired grant type using the following 762 | parameter: 763 | 764 | "response_type": 765 | : REQUIRED. The value MUST be one of "code" for requesting an 766 | authorization code as described by Section 4.1.1, "token" for 767 | requesting an access token (implicit grant) as described by 768 | Section 4.2.1, or a registered extension value as described by 769 | Section 8.4. 770 | 771 | Extension response types MAY contain a space-delimited (%x20) list of 772 | values, where the order of values does not matter (e.g., response 773 | type "a b" is the same as "b a"). The meaning of such composite 774 | response types is defined by their respective specifications. 775 | 776 | If an authorization request is missing the "response_type" parameter, 777 | or if the response type is not understood, the authorization server 778 | MUST return an error response as described in Section 4.1.2.1. 779 | 780 | ### Redirection Endpoint 781 | 782 | After completing its interaction with the resource owner, the 783 | authorization server directs the resource owner's user-agent back to 784 | the client. The authorization server redirects the user-agent to the 785 | client's redirection endpoint previously established with the 786 | authorization server during the client registration process or when 787 | making the authorization request. 788 | 789 | The redirection endpoint URI MUST be an absolute URI as defined by 790 | {{RFC3986}} Section 4.3. The endpoint URI MAY include an 791 | "application/x-www-form-urlencoded" formatted (per Appendix B) query 792 | component ({{RFC3986}} Section 3.4), which MUST be retained when adding 793 | additional query parameters. The endpoint URI MUST NOT include a 794 | fragment component. 795 | 796 | 797 | #### Endpoint Request Confidentiality 798 | 799 | The redirection endpoint SHOULD require the use of TLS as described 800 | in Section 1.6 when the requested response type is "code" or "token", 801 | or when the redirection request will result in the transmission of 802 | sensitive credentials over an open network. This specification does 803 | not mandate the use of TLS because at the time of this writing, 804 | requiring clients to deploy TLS is a significant hurdle for many 805 | client developers. If TLS is not available, the authorization server 806 | SHOULD warn the resource owner about the insecure endpoint prior to 807 | redirection (e.g., display a message during the authorization 808 | request). 809 | 810 | Lack of transport-layer security can have a severe impact on the 811 | security of the client and the protected resources it is authorized 812 | to access. The use of transport-layer security is particularly 813 | critical when the authorization process is used as a form of 814 | delegated end-user authentication by the client (e.g., third-party 815 | sign-in service). 816 | 817 | 818 | #### Registration Requirements 819 | 820 | The authorization server MUST require the following clients to 821 | register their redirection endpoint: 822 | 823 | * Public clients. 824 | * Confidential clients utilizing the implicit grant type. 825 | 826 | The authorization server SHOULD require all clients to register their 827 | redirection endpoint prior to utilizing the authorization endpoint. 828 | 829 | The authorization server SHOULD require the client to provide the 830 | complete redirection URI (the client MAY use the "state" request 831 | parameter to achieve per-request customization). If requiring the 832 | registration of the complete redirection URI is not possible, the 833 | authorization server SHOULD require the registration of the URI 834 | scheme, authority, and path (allowing the client to dynamically vary 835 | only the query component of the redirection URI when requesting 836 | authorization). 837 | 838 | The authorization server MAY allow the client to register multiple 839 | redirection endpoints. 840 | 841 | Lack of a redirection URI registration requirement can enable an 842 | attacker to use the authorization endpoint as an open redirector as 843 | described in Section 10.15. 844 | 845 | 846 | #### Dynamic Configuration 847 | 848 | If multiple redirection URIs have been registered, if only part of 849 | the redirection URI has been registered, or if no redirection URI has 850 | been registered, the client MUST include a redirection URI with the 851 | authorization request using the "redirect_uri" request parameter. 852 | 853 | When a redirection URI is included in an authorization request, the 854 | authorization server MUST compare and match the value received 855 | against at least one of the registered redirection URIs (or URI 856 | components) as defined in {{RFC3986}} Section 6, if any redirection 857 | URIs were registered. If the client registration included the full 858 | redirection URI, the authorization server MUST compare the two URIs 859 | using simple string comparison as defined in {{RFC3986}} Section 6.2.1. 860 | 861 | 862 | #### Invalid Endpoint 863 | 864 | If an authorization request fails validation due to a missing, 865 | invalid, or mismatching redirection URI, the authorization server 866 | SHOULD inform the resource owner of the error and MUST NOT 867 | automatically redirect the user-agent to the invalid redirection URI. 868 | 869 | 870 | #### Endpoint Content 871 | 872 | The redirection request to the client's endpoint typically results in 873 | an HTML document response, processed by the user-agent. If the HTML 874 | response is served directly as the result of the redirection request, 875 | any script included in the HTML document will execute with full 876 | access to the redirection URI and the credentials it contains. 877 | 878 | The client SHOULD NOT include any third-party scripts (e.g., third- 879 | party analytics, social plug-ins, ad networks) in the redirection 880 | endpoint response. Instead, it SHOULD extract the credentials from 881 | the URI and redirect the user-agent again to another endpoint without 882 | exposing the credentials (in the URI or elsewhere). If third-party 883 | scripts are included, the client MUST ensure that its own scripts 884 | (used to extract and remove the credentials from the URI) will 885 | execute first. 886 | 887 | 888 | ## Token Endpoint 889 | 890 | The token endpoint is used by the client to obtain an access token by 891 | presenting its authorization grant or refresh token. The token 892 | endpoint is used with every authorization grant except for the 893 | implicit grant type (since an access token is issued directly). 894 | 895 | The means through which the client obtains the location of the token 896 | endpoint are beyond the scope of this specification, but the location 897 | is typically provided in the service documentation. 898 | 899 | The endpoint URI MAY include an "application/x-www-form-urlencoded" 900 | formatted (per Appendix B) query component ({{RFC3986}} Section 3.4), 901 | which MUST be retained when adding additional query parameters. The 902 | endpoint URI MUST NOT include a fragment component. 903 | 904 | Since requests to the token endpoint result in the transmission of 905 | clear-text credentials (in the HTTP request and response), the 906 | authorization server MUST require the use of TLS as described in 907 | Section 1.6 when sending requests to the token endpoint. 908 | 909 | The client MUST use the HTTP "POST" method when making access token 910 | requests. 911 | 912 | Parameters sent without a value MUST be treated as if they were 913 | omitted from the request. The authorization server MUST ignore 914 | unrecognized request parameters. Request and response parameters 915 | MUST NOT be included more than once. 916 | 917 | 918 | ### Client Authentication 919 | 920 | Confidential clients or other clients issued client credentials MUST 921 | authenticate with the authorization server as described in 922 | Section 2.3 when making requests to the token endpoint. Client 923 | authentication is used for: 924 | 925 | * Enforcing the binding of refresh tokens and authorization codes to 926 | the client they were issued to. Client authentication is critical 927 | when an authorization code is transmitted to the redirection 928 | endpoint over an insecure channel or when the redirection URI has 929 | not been registered in full. 930 | 931 | * Recovering from a compromised client by disabling the client or 932 | changing its credentials, thus preventing an attacker from abusing 933 | stolen refresh tokens. Changing a single set of client 934 | credentials is significantly faster than revoking an entire set of 935 | refresh tokens. 936 | 937 | * Implementing authentication management best practices, which 938 | require periodic credential rotation. Rotation of an entire set 939 | of refresh tokens can be challenging, while rotation of a single 940 | set of client credentials is significantly easier. 941 | 942 | A client MAY use the "client_id" request parameter to identify itself 943 | when sending requests to the token endpoint. In the 944 | "authorization_code" "grant_type" request to the token endpoint, an 945 | unauthenticated client MUST send its "client_id" to prevent itself 946 | from inadvertently accepting a code intended for a client with a 947 | different "client_id". This protects the client from substitution of 948 | the authentication code. (It provides no additional security for the 949 | protected resource.) 950 | 951 | 952 | ## Access Token Scope 953 | 954 | The authorization and token endpoints allow the client to specify the 955 | scope of the access request using the "scope" request parameter. In 956 | turn, the authorization server uses the "scope" response parameter to 957 | inform the client of the scope of the access token issued. 958 | 959 | The value of the scope parameter is expressed as a list of space- 960 | delimited, case-sensitive strings. The strings are defined by the 961 | authorization server. If the value contains multiple space-delimited 962 | strings, their order does not matter, and each string adds an 963 | additional access range to the requested scope. 964 | 965 | ~~~~abnf 966 | scope = scope-token *( SP scope-token ) 967 | scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 968 | ~~~~ 969 | 970 | The authorization server MAY fully or partially ignore the scope 971 | requested by the client, based on the authorization server policy or 972 | the resource owner's instructions. If the issued access token scope 973 | is different from the one requested by the client, the authorization 974 | server MUST include the "scope" response parameter to inform the 975 | client of the actual scope granted. 976 | 977 | If the client omits the scope parameter when requesting 978 | authorization, the authorization server MUST either process the 979 | request using a pre-defined default value or fail the request 980 | indicating an invalid scope. The authorization server SHOULD 981 | document its scope requirements and default value (if defined). 982 | 983 | 984 | # Obtaining Authorization 985 | 986 | To request an access token, the client obtains authorization from the 987 | resource owner. The authorization is expressed in the form of an 988 | authorization grant, which the client uses to request the access 989 | token. OAuth defines four grant types: authorization code, implicit, 990 | resource owner password credentials, and client credentials. It also 991 | provides an extension mechanism for defining additional grant types. 992 | 993 | 994 | ## Authorization Code Grant 995 | 996 | The authorization code grant type is used to obtain both access 997 | tokens and refresh tokens and is optimized for confidential clients. 998 | Since this is a redirection-based flow, the client must be capable of 999 | interacting with the resource owner's user-agent (typically a web 1000 | browser) and capable of receiving incoming requests (via redirection) 1001 | from the authorization server. 1002 | 1003 | ~~~~~~~~~~ 1004 | +----------+ 1005 | | Resource | 1006 | | Owner | 1007 | | | 1008 | +----------+ 1009 | ^ 1010 | | 1011 | (2) 1012 | +----|-----+ Client Identifier +---------------+ 1013 | | -+----(1)-- & Redirection URI ---->| | 1014 | | User- | | Authorization | 1015 | | Agent -+----(2)-- User authenticates --->| Server | 1016 | | | | | 1017 | | -+----(3)-- Authorization Code ---<| | 1018 | +-|----|---+ +---------------+ 1019 | | | ^ v 1020 | (1) (3) | | 1021 | | | | | 1022 | ^ v | | 1023 | +---------+ | | 1024 | | |>---(4)-- Authorization Code ---------' | 1025 | | Client | & Redirection URI | 1026 | | | | 1027 | | |<---(5)----- Access Token -------------------' 1028 | +---------+ (w/ Optional Refresh Token) 1029 | 1030 | Note: The lines illustrating steps (1), (2), and (3) are broken into 1031 | two parts as they pass through the user-agent. 1032 | ~~~~~~~~~~ 1033 | {: #fig-authorization-code-flow title="Authorization Code Flow"} 1034 | 1035 | The flow illustrated in {{fig-authorization-code-flow}} includes the following steps: 1036 | 1037 | (1) The client initiates the flow by directing the resource owner's 1038 | user-agent to the authorization endpoint. The client includes 1039 | its client identifier, requested scope, local state, and a 1040 | redirection URI to which the authorization server will send the 1041 | user-agent back once access is granted (or denied). 1042 | 1043 | (2) The authorization server authenticates the resource owner (via 1044 | the user-agent) and establishes whether the resource owner 1045 | grants or denies the client's access request. 1046 | 1047 | (3) Assuming the resource owner grants access, the authorization 1048 | server redirects the user-agent back to the client using the 1049 | redirection URI provided earlier (in the request or during 1050 | client registration). The redirection URI includes an 1051 | authorization code and any local state provided by the client 1052 | earlier. 1053 | 1054 | (4) The client requests an access token from the authorization 1055 | server's token endpoint by including the authorization code 1056 | received in the previous step. When making the request, the 1057 | client authenticates with the authorization server. The client 1058 | includes the redirection URI used to obtain the authorization 1059 | code for verification. 1060 | 1061 | (5) The authorization server authenticates the client, validates the 1062 | authorization code, and ensures that the redirection URI 1063 | received matches the URI used to redirect the client in 1064 | step (C). If valid, the authorization server responds back with 1065 | an access token and, optionally, a refresh token. 1066 | 1067 | ### Authorization Request 1068 | 1069 | The client constructs the request URI by adding the following 1070 | parameters to the query component of the authorization endpoint URI 1071 | using the "application/x-www-form-urlencoded" format, per Appendix B: 1072 | 1073 | "response_type": 1074 | : REQUIRED. Value MUST be set to "code". 1075 | 1076 | "client_id": 1077 | : REQUIRED. The client identifier as described in Section 2.2. 1078 | 1079 | "redirect_uri": 1080 | : OPTIONAL. As described in Section 3.1.2. 1081 | 1082 | "scope": 1083 | : OPTIONAL. The scope of the access request as described by 1084 | Section 3.3. 1085 | 1086 | "state": 1087 | : RECOMMENDED. An opaque value used by the client to maintain 1088 | state between the request and callback. The authorization 1089 | server includes this value when redirecting the user-agent back 1090 | to the client. The parameter SHOULD be used for preventing 1091 | cross-site request forgery as described in Section 10.12. 1092 | 1093 | The client directs the resource owner to the constructed URI using an 1094 | HTTP redirection response, or by other means available to it via the 1095 | user-agent. 1096 | 1097 | For example, the client directs the user-agent to make the following 1098 | HTTP request using TLS (with extra line breaks for display purposes 1099 | only): 1100 | 1101 | GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1102 | &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1103 | Host: server.example.com 1104 | 1105 | The authorization server validates the request to ensure that all 1106 | required parameters are present and valid. If the request is valid, 1107 | the authorization server authenticates the resource owner and obtains 1108 | an authorization decision (by asking the resource owner or by 1109 | establishing approval via other means). 1110 | 1111 | When a decision is established, the authorization server directs the 1112 | user-agent to the provided client redirection URI using an HTTP 1113 | redirection response, or by other means available to it via the 1114 | user-agent. 1115 | 1116 | 1117 | ### Authorization Response 1118 | 1119 | If the resource owner grants the access request, the authorization 1120 | server issues an authorization code and delivers it to the client by 1121 | adding the following parameters to the query component of the 1122 | redirection URI using the "application/x-www-form-urlencoded" format, 1123 | per Appendix B: 1124 | 1125 | "code": 1126 | : REQUIRED. The authorization code generated by the 1127 | authorization server. The authorization code MUST expire 1128 | shortly after it is issued to mitigate the risk of leaks. A 1129 | maximum authorization code lifetime of 10 minutes is 1130 | RECOMMENDED. The client MUST NOT use the authorization code 1131 | more than once. If an authorization code is used more than 1132 | once, the authorization server MUST deny the request and SHOULD 1133 | revoke (when possible) all tokens previously issued based on 1134 | that authorization code. The authorization code is bound to 1135 | the client identifier and redirection URI. 1136 | 1137 | "state": 1138 | : REQUIRED if the "state" parameter was present in the client 1139 | authorization request. The exact value received from the 1140 | client. 1141 | 1142 | For example, the authorization server redirects the user-agent by 1143 | sending the following HTTP response: 1144 | 1145 | HTTP/1.1 302 Found 1146 | Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1147 | &state=xyz 1148 | 1149 | The client MUST ignore unrecognized response parameters. The 1150 | authorization code string size is left undefined by this 1151 | specification. The client should avoid making assumptions about code 1152 | value sizes. The authorization server SHOULD document the size of 1153 | any value it issues. 1154 | 1155 | 1156 | #### Error Response 1157 | 1158 | If the request fails due to a missing, invalid, or mismatching 1159 | redirection URI, or if the client identifier is missing or invalid, 1160 | the authorization server SHOULD inform the resource owner of the 1161 | error and MUST NOT automatically redirect the user-agent to the 1162 | invalid redirection URI. 1163 | 1164 | If the resource owner denies the access request or if the request 1165 | fails for reasons other than a missing or invalid redirection URI, 1166 | the authorization server informs the client by adding the following 1167 | parameters to the query component of the redirection URI using the 1168 | "application/x-www-form-urlencoded" format, per Appendix B: 1169 | 1170 | "error": 1171 | : REQUIRED. A single ASCII [USASCII] error code from the 1172 | following: 1173 | 1174 | "invalid_request": 1175 | : The request is missing a required parameter, includes an 1176 | invalid parameter value, includes a parameter more than 1177 | once, or is otherwise malformed. 1178 | 1179 | "unauthorized_client": 1180 | : The client is not authorized to request an authorization 1181 | code using this method. 1182 | 1183 | "access_denied": 1184 | : The resource owner or authorization server denied the 1185 | request. 1186 | 1187 | "unsupported_response_type": 1188 | : The authorization server does not support obtaining an 1189 | authorization code using this method. 1190 | 1191 | "invalid_scope": 1192 | : The requested scope is invalid, unknown, or malformed. 1193 | 1194 | "server_error": 1195 | : The authorization server encountered an unexpected 1196 | condition that prevented it from fulfilling the request. 1197 | (This error code is needed because a 500 Internal Server 1198 | Error HTTP status code cannot be returned to the client 1199 | via an HTTP redirect.) 1200 | 1201 | "temporarily_unavailable": 1202 | : The authorization server is currently unable to handle 1203 | the request due to a temporary overloading or maintenance 1204 | of the server. (This error code is needed because a 503 1205 | Service Unavailable HTTP status code cannot be returned 1206 | to the client via an HTTP redirect.) 1207 | 1208 | Values for the "error" parameter MUST NOT include characters 1209 | outside the set %x20-21 / %x23-5B / %x5D-7E. 1210 | 1211 | 1212 | "error_description": 1213 | : OPTIONAL. Human-readable ASCII [USASCII] text providing 1214 | additional information, used to assist the client developer in 1215 | understanding the error that occurred. 1216 | Values for the "error_description" parameter MUST NOT include 1217 | characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1218 | 1219 | "error_uri": 1220 | : OPTIONAL. A URI identifying a human-readable web page with 1221 | information about the error, used to provide the client 1222 | developer with additional information about the error. 1223 | Values for the "error_uri" parameter MUST conform to the 1224 | URI-reference syntax and thus MUST NOT include characters 1225 | outside the set %x21 / %x23-5B / %x5D-7E. 1226 | 1227 | "state": 1228 | : REQUIRED if a "state" parameter was present in the client 1229 | authorization request. The exact value received from the 1230 | client. 1231 | 1232 | For example, the authorization server redirects the user-agent by 1233 | sending the following HTTP response: 1234 | 1235 | HTTP/1.1 302 Found 1236 | Location: https://client.example.com/cb?error=access_denied&state=xyz 1237 | 1238 | 1239 | ### Access Token Request 1240 | 1241 | The client makes a request to the token endpoint by sending the 1242 | following parameters using the "application/x-www-form-urlencoded" 1243 | format per Appendix B with a character encoding of UTF-8 in the HTTP 1244 | request entity-body: 1245 | 1246 | "grant_type": 1247 | : REQUIRED. Value MUST be set to "authorization_code". 1248 | 1249 | "code": 1250 | : REQUIRED. The authorization code received from the 1251 | authorization server. 1252 | 1253 | "redirect_uri": 1254 | : REQUIRED, if the "redirect_uri" parameter was included in the 1255 | authorization request as described in Section 4.1.1, and their 1256 | values MUST be identical. 1257 | 1258 | "client_id": 1259 | : REQUIRED, if the client is not authenticating with the 1260 | authorization server as described in Section 3.2.1. 1261 | 1262 | If the client type is confidential or the client was issued client 1263 | credentials (or assigned other authentication requirements), the 1264 | client MUST authenticate with the authorization server as described 1265 | in Section 3.2.1. 1266 | 1267 | For example, the client makes the following HTTP request using TLS 1268 | (with extra line breaks for display purposes only): 1269 | 1270 | POST /token HTTP/1.1 1271 | Host: server.example.com 1272 | Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1273 | Content-Type: application/x-www-form-urlencoded 1274 | 1275 | grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1276 | &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1277 | 1278 | The authorization server MUST: 1279 | 1280 | * require client authentication for confidential clients or for any 1281 | client that was issued client credentials (or with other 1282 | authentication requirements), 1283 | 1284 | * authenticate the client if client authentication is included, 1285 | 1286 | * ensure that the authorization code was issued to the authenticated 1287 | confidential client, or if the client is public, ensure that the 1288 | code was issued to "client_id" in the request, 1289 | 1290 | * verify that the authorization code is valid, and 1291 | 1292 | * ensure that the "redirect_uri" parameter is present if the 1293 | "redirect_uri" parameter was included in the initial authorization 1294 | request as described in Section 4.1.1, and if included ensure that 1295 | their values are identical. 1296 | 1297 | 1298 | ### Access Token Response 1299 | 1300 | If the access token request is valid and authorized, the 1301 | authorization server issues an access token and optional refresh 1302 | token as described in Section 5.1. If the request client 1303 | authentication failed or is invalid, the authorization server returns 1304 | an error response as described in Section 5.2. 1305 | 1306 | An example successful response: 1307 | 1308 | HTTP/1.1 200 OK 1309 | Content-Type: application/json;charset=UTF-8 1310 | Cache-Control: no-store 1311 | Pragma: no-cache 1312 | 1313 | { 1314 | "access_token":"2YotnFZFEjr1zCsicMWpAA", 1315 | "token_type":"example", 1316 | "expires_in":3600, 1317 | "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1318 | "example_parameter":"example_value" 1319 | } 1320 | 1321 | 1322 | ## Implicit Grant 1323 | 1324 | The implicit grant type is used to obtain access tokens (it does not 1325 | support the issuance of refresh tokens) and is optimized for public 1326 | clients known to operate a particular redirection URI. These clients 1327 | are typically implemented in a browser using a scripting language 1328 | such as JavaScript. 1329 | 1330 | Since this is a redirection-based flow, the client must be capable of 1331 | interacting with the resource owner's user-agent (typically a web 1332 | browser) and capable of receiving incoming requests (via redirection) 1333 | from the authorization server. 1334 | 1335 | Unlike the authorization code grant type, in which the client makes 1336 | separate requests for authorization and for an access token, the 1337 | client receives the access token as the result of the authorization 1338 | request. 1339 | 1340 | The implicit grant type does not include client authentication, and 1341 | relies on the presence of the resource owner and the registration of 1342 | the redirection URI. Because the access token is encoded into the 1343 | redirection URI, it may be exposed to the resource owner and other 1344 | applications residing on the same device. 1345 | 1346 | ~~~~~~~~~~ 1347 | +----------+ 1348 | | Resource | 1349 | | Owner | 1350 | | | 1351 | +----------+ 1352 | ^ 1353 | | 1354 | (2) 1355 | +----|-----+ Client Identifier +---------------+ 1356 | | -+----(1)-- & Redirection URI --->| | 1357 | | User- | | Authorization | 1358 | | Agent -|----(2)-- User authenticates -->| Server | 1359 | | | | | 1360 | | |<---(3)--- Redirection URI ----<| | 1361 | | | with Access Token +---------------+ 1362 | | | in Fragment 1363 | | | +---------------+ 1364 | | |----(4)--- Redirection URI ---->| Web-Hosted | 1365 | | | without Fragment | Client | 1366 | | | | Resource | 1367 | | (6) |<---(5)------- Script ---------<| | 1368 | | | +---------------+ 1369 | +-|--------+ 1370 | | | 1371 | (1) (7) Access Token 1372 | | | 1373 | ^ v 1374 | +---------+ 1375 | | | 1376 | | Client | 1377 | | | 1378 | +---------+ 1379 | 1380 | Note: The lines illustrating steps (A) and (B) are broken into two 1381 | parts as they pass through the user-agent. 1382 | ~~~~~~~~~~ 1383 | {: #fig-implicit-grant-flow title="Implicit Grant Flow"} 1384 | 1385 | 1386 | The flow illustrated in Figure 4 includes the following steps: 1387 | 1388 | 1. The client initiates the flow by directing the resource owner's 1389 | user-agent to the authorization endpoint. The client includes 1390 | its client identifier, requested scope, local state, and a 1391 | redirection URI to which the authorization server will send the 1392 | user-agent back once access is granted (or denied). 1393 | 1394 | 2. The authorization server authenticates the resource owner (via 1395 | the user-agent) and establishes whether the resource owner 1396 | grants or denies the client's access request. 1397 | 1398 | 3. Assuming the resource owner grants access, the authorization 1399 | server redirects the user-agent back to the client using the 1400 | redirection URI provided earlier. The redirection URI includes 1401 | the access token in the URI fragment. 1402 | 1403 | 4. The user-agent follows the redirection instructions by making a 1404 | request to the web-hosted client resource (which does not 1405 | include the fragment per {{RFC2616}}). The user-agent retains the 1406 | fragment information locally. 1407 | 1408 | 5. The web-hosted client resource returns a web page (typically an 1409 | HTML document with an embedded script) capable of accessing the 1410 | full redirection URI including the fragment retained by the 1411 | user-agent, and extracting the access token (and other 1412 | parameters) contained in the fragment. 1413 | 1414 | 6. The user-agent executes the script provided by the web-hosted 1415 | client resource locally, which extracts the access token. 1416 | 1417 | 7. The user-agent passes the access token to the client. 1418 | 1419 | See Sections 1.3.2 and 9 for background on using the implicit grant. 1420 | See Sections 10.3 and 10.16 for important security considerations 1421 | when using the implicit grant. 1422 | 1423 | 1424 | ### Authorization Request 1425 | 1426 | The client constructs the request URI by adding the following 1427 | parameters to the query component of the authorization endpoint URI 1428 | using the "application/x-www-form-urlencoded" format, per Appendix B: 1429 | 1430 | "response_type": 1431 | : REQUIRED. Value MUST be set to "token". 1432 | 1433 | "client_id": 1434 | : REQUIRED. The client identifier as described in Section 2.2. 1435 | 1436 | "redirect_uri": 1437 | : OPTIONAL. As described in Section 3.1.2. 1438 | 1439 | "scope": 1440 | : OPTIONAL. The scope of the access request as described by 1441 | Section 3.3. 1442 | 1443 | "state": 1444 | : RECOMMENDED. An opaque value used by the client to maintain 1445 | state between the request and callback. The authorization 1446 | server includes this value when redirecting the user-agent back 1447 | to the client. The parameter SHOULD be used for preventing 1448 | cross-site request forgery as described in Section 10.12. 1449 | 1450 | The client directs the resource owner to the constructed URI using an 1451 | HTTP redirection response, or by other means available to it via the 1452 | user-agent. 1453 | 1454 | For example, the client directs the user-agent to make the following 1455 | HTTP request using TLS (with extra line breaks for display purposes 1456 | only): 1457 | 1458 | GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1459 | &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1460 | Host: server.example.com 1461 | 1462 | The authorization server validates the request to ensure that all 1463 | required parameters are present and valid. The authorization server 1464 | MUST verify that the redirection URI to which it will redirect the 1465 | access token matches a redirection URI registered by the client as 1466 | described in Section 3.1.2. 1467 | 1468 | If the request is valid, the authorization server authenticates the 1469 | resource owner and obtains an authorization decision (by asking the 1470 | resource owner or by establishing approval via other means). 1471 | 1472 | When a decision is established, the authorization server directs the 1473 | user-agent to the provided client redirection URI using an HTTP 1474 | redirection response, or by other means available to it via the 1475 | user-agent. 1476 | 1477 | 1478 | ### Access Token Response 1479 | 1480 | If the resource owner grants the access request, the authorization 1481 | server issues an access token and delivers it to the client by adding 1482 | the following parameters to the fragment component of the redirection 1483 | URI using the "application/x-www-form-urlencoded" format, per 1484 | Appendix B: 1485 | 1486 | "access_token": 1487 | : REQUIRED. The access token issued by the authorization server. 1488 | 1489 | "token_type": 1490 | : REQUIRED. The type of the token issued as described in 1491 | Section 7.1. Value is case insensitive. 1492 | 1493 | "expires_in": 1494 | : RECOMMENDED. The lifetime in seconds of the access token. For 1495 | example, the value "3600" denotes that the access token will 1496 | expire in one hour from the time the response was generated. 1497 | If omitted, the authorization server SHOULD provide the 1498 | expiration time via other means or document the default value. 1499 | 1500 | "scope": 1501 | : OPTIONAL, if identical to the scope requested by the client; 1502 | otherwise, REQUIRED. The scope of the access token as 1503 | described by Section 3.3. 1504 | 1505 | "state": 1506 | : REQUIRED if the "state" parameter was present in the client 1507 | authorization request. The exact value received from the 1508 | client. 1509 | 1510 | The authorization server MUST NOT issue a refresh token. 1511 | 1512 | For example, the authorization server redirects the user-agent by 1513 | sending the following HTTP response (with extra line breaks for 1514 | display purposes only): 1515 | 1516 | HTTP/1.1 302 Found 1517 | Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA 1518 | &state=xyz&token_type=example&expires_in=3600 1519 | 1520 | Developers should note that some user-agents do not support the 1521 | inclusion of a fragment component in the HTTP "Location" response 1522 | header field. Such clients will require using other methods for 1523 | redirecting the client than a 3xx redirection response -- for 1524 | example, returning an HTML page that includes a 'continue' button 1525 | with an action linked to the redirection URI. 1526 | 1527 | The client MUST ignore unrecognized response parameters. The access 1528 | token string size is left undefined by this specification. The 1529 | client should avoid making assumptions about value sizes. The 1530 | authorization server SHOULD document the size of any value it issues. 1531 | 1532 | 1533 | #### Error Response 1534 | 1535 | If the request fails due to a missing, invalid, or mismatching 1536 | redirection URI, or if the client identifier is missing or invalid, 1537 | the authorization server SHOULD inform the resource owner of the 1538 | error and MUST NOT automatically redirect the user-agent to the 1539 | invalid redirection URI. 1540 | 1541 | If the resource owner denies the access request or if the request 1542 | fails for reasons other than a missing or invalid redirection URI, 1543 | the authorization server informs the client by adding the following 1544 | parameters to the fragment component of the redirection URI using the 1545 | "application/x-www-form-urlencoded" format, per Appendix B: 1546 | 1547 | "error": 1548 | : REQUIRED. A single ASCII [USASCII] error code from the 1549 | following: 1550 | 1551 | "invalid_request": 1552 | : The request is missing a required parameter, includes an 1553 | invalid parameter value, includes a parameter more than 1554 | once, or is otherwise malformed. 1555 | 1556 | "unauthorized_client": 1557 | : The client is not authorized to request an access token 1558 | using this method. 1559 | 1560 | "access_denied": 1561 | : The resource owner or authorization server denied the 1562 | request. 1563 | 1564 | "unsupported_response_type": 1565 | : The authorization server does not support obtaining an 1566 | access token using this method. 1567 | 1568 | "invalid_scope": 1569 | : The requested scope is invalid, unknown, or malformed. 1570 | 1571 | "server_error": 1572 | : The authorization server encountered an unexpected 1573 | condition that prevented it from fulfilling the request. 1574 | (This error code is needed because a 500 Internal Server 1575 | Error HTTP status code cannot be returned to the client 1576 | via an HTTP redirect.) 1577 | 1578 | "temporarily_unavailable": 1579 | : The authorization server is currently unable to handle 1580 | the request due to a temporary overloading or maintenance 1581 | of the server. (This error code is needed because a 503 1582 | Service Unavailable HTTP status code cannot be returned 1583 | to the client via an HTTP redirect.) 1584 | 1585 | Values for the "error" parameter MUST NOT include characters 1586 | outside the set %x20-21 / %x23-5B / %x5D-7E. 1587 | 1588 | "error_description": 1589 | : OPTIONAL. Human-readable ASCII [USASCII] text providing 1590 | additional information, used to assist the client developer in 1591 | understanding the error that occurred. 1592 | Values for the "error_description" parameter MUST NOT include 1593 | characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1594 | 1595 | "error_uri": 1596 | : OPTIONAL. A URI identifying a human-readable web page with 1597 | information about the error, used to provide the client 1598 | developer with additional information about the error. 1599 | Values for the "error_uri" parameter MUST conform to the 1600 | URI-reference syntax and thus MUST NOT include characters 1601 | outside the set %x21 / %x23-5B / %x5D-7E. 1602 | 1603 | "state": 1604 | : REQUIRED if a "state" parameter was present in the client 1605 | authorization request. The exact value received from the 1606 | client. 1607 | 1608 | For example, the authorization server redirects the user-agent by 1609 | sending the following HTTP response: 1610 | 1611 | HTTP/1.1 302 Found 1612 | Location: https://client.example.com/cb#error=access_denied&state=xyz 1613 | 1614 | 1615 | ## Resource Owner Password Credentials Grant 1616 | 1617 | The resource owner password credentials grant type is suitable in 1618 | cases where the resource owner has a trust relationship with the 1619 | client, such as the device operating system or a highly privileged 1620 | application. The authorization server should take special care when 1621 | enabling this grant type and only allow it when other flows are not 1622 | viable. 1623 | 1624 | This grant type is suitable for clients capable of obtaining the 1625 | resource owner's credentials (username and password, typically using 1626 | an interactive form). It is also used to migrate existing clients 1627 | using direct authentication schemes such as HTTP Basic or Digest 1628 | authentication to OAuth by converting the stored credentials to an 1629 | access token. 1630 | 1631 | +----------+ 1632 | | Resource | 1633 | | Owner | 1634 | | | 1635 | +----------+ 1636 | v 1637 | | Resource Owner 1638 | (A) Password Credentials 1639 | | 1640 | v 1641 | +---------+ +---------------+ 1642 | | |>--(B)---- Resource Owner ------->| | 1643 | | | Password Credentials | Authorization | 1644 | | Client | | Server | 1645 | | |<--(C)---- Access Token ---------<| | 1646 | | | (w/ Optional Refresh Token) | | 1647 | +---------+ +---------------+ 1648 | 1649 | Figure 5: Resource Owner Password Credentials Flow 1650 | 1651 | The flow illustrated in Figure 5 includes the following steps: 1652 | 1653 | (A) The resource owner provides the client with its username and 1654 | password. 1655 | 1656 | (B) The client requests an access token from the authorization 1657 | server's token endpoint by including the credentials received 1658 | from the resource owner. When making the request, the client 1659 | authenticates with the authorization server. 1660 | 1661 | (C) The authorization server authenticates the client and validates 1662 | the resource owner credentials, and if valid, issues an access 1663 | token. 1664 | 1665 | 1666 | ### Authorization Request and Response 1667 | 1668 | The method through which the client obtains the resource owner 1669 | credentials is beyond the scope of this specification. The client 1670 | MUST discard the credentials once an access token has been obtained. 1671 | 1672 | 1673 | ### Access Token Request 1674 | 1675 | The client makes a request to the token endpoint by adding the 1676 | following parameters using the "application/x-www-form-urlencoded" 1677 | format per Appendix B with a character encoding of UTF-8 in the HTTP 1678 | request entity-body: 1679 | 1680 | "grant_type": 1681 | : REQUIRED. Value MUST be set to "password". 1682 | 1683 | "username": 1684 | : REQUIRED. The resource owner username. 1685 | 1686 | "password": 1687 | : REQUIRED. The resource owner password. 1688 | 1689 | "scope": 1690 | : OPTIONAL. The scope of the access request as described by 1691 | Section 3.3. 1692 | 1693 | If the client type is confidential or the client was issued client 1694 | credentials (or assigned other authentication requirements), the 1695 | client MUST authenticate with the authorization server as described 1696 | in Section 3.2.1. 1697 | 1698 | For example, the client makes the following HTTP request using 1699 | transport-layer security (with extra line breaks for display purposes 1700 | only): 1701 | 1702 | POST /token HTTP/1.1 1703 | Host: server.example.com 1704 | Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1705 | Content-Type: application/x-www-form-urlencoded 1706 | 1707 | grant_type=password&username=johndoe&password=A3ddj3w 1708 | 1709 | The authorization server MUST: 1710 | 1711 | * require client authentication for confidential clients or for any 1712 | client that was issued client credentials (or with other 1713 | authentication requirements), 1714 | 1715 | * authenticate the client if client authentication is included, and 1716 | 1717 | * validate the resource owner password credentials using its 1718 | existing password validation algorithm. 1719 | 1720 | Since this access token request utilizes the resource owner's 1721 | password, the authorization server MUST protect the endpoint against 1722 | brute force attacks (e.g., using rate-limitation or generating 1723 | alerts). 1724 | 1725 | 1726 | ### Access Token Response 1727 | 1728 | If the access token request is valid and authorized, the 1729 | authorization server issues an access token and optional refresh 1730 | token as described in Section 5.1. If the request failed client 1731 | authentication or is invalid, the authorization server returns an 1732 | error response as described in Section 5.2. 1733 | 1734 | An example successful response: 1735 | 1736 | HTTP/1.1 200 OK 1737 | Content-Type: application/json;charset=UTF-8 1738 | Cache-Control: no-store 1739 | Pragma: no-cache 1740 | 1741 | { 1742 | "access_token":"2YotnFZFEjr1zCsicMWpAA", 1743 | "token_type":"example", 1744 | "expires_in":3600, 1745 | "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1746 | "example_parameter":"example_value" 1747 | } 1748 | 1749 | 1750 | ## Client Credentials Grant 1751 | 1752 | The client can request an access token using only its client 1753 | credentials (or other supported means of authentication) when the 1754 | client is requesting access to the protected resources under its 1755 | control, or those of another resource owner that have been previously 1756 | arranged with the authorization server (the method of which is beyond 1757 | the scope of this specification). 1758 | 1759 | The client credentials grant type MUST only be used by confidential 1760 | clients. 1761 | 1762 | +---------+ +---------------+ 1763 | | | | | 1764 | | |>--(A)- Client Authentication --->| Authorization | 1765 | | Client | | Server | 1766 | | |<--(B)---- Access Token ---------<| | 1767 | | | | | 1768 | +---------+ +---------------+ 1769 | 1770 | Figure 6: Client Credentials Flow 1771 | 1772 | The flow illustrated in Figure 6 includes the following steps: 1773 | 1774 | (A) The client authenticates with the authorization server and 1775 | requests an access token from the token endpoint. 1776 | 1777 | (B) The authorization server authenticates the client, and if valid, 1778 | issues an access token. 1779 | 1780 | 1781 | ### Authorization Request and Response 1782 | 1783 | Since the client authentication is used as the authorization grant, 1784 | no additional authorization request is needed. 1785 | 1786 | 1787 | ### Access Token Request 1788 | 1789 | The client makes a request to the token endpoint by adding the 1790 | following parameters using the "application/x-www-form-urlencoded" 1791 | format per Appendix B with a character encoding of UTF-8 in the HTTP 1792 | request entity-body: 1793 | 1794 | "grant_type": 1795 | : REQUIRED. Value MUST be set to "client_credentials". 1796 | 1797 | "scope": 1798 | : OPTIONAL. The scope of the access request as described by 1799 | Section 3.3. 1800 | 1801 | The client MUST authenticate with the authorization server as 1802 | described in Section 3.2.1. 1803 | 1804 | For example, the client makes the following HTTP request using 1805 | transport-layer security (with extra line breaks for display purposes 1806 | only): 1807 | 1808 | POST /token HTTP/1.1 1809 | Host: server.example.com 1810 | Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1811 | Content-Type: application/x-www-form-urlencoded 1812 | 1813 | grant_type=client_credentials 1814 | 1815 | The authorization server MUST authenticate the client. 1816 | 1817 | 1818 | ### Access Token Response 1819 | 1820 | If the access token request is valid and authorized, the 1821 | authorization server issues an access token as described in 1822 | Section 5.1. A refresh token SHOULD NOT be included. If the request 1823 | failed client authentication or is invalid, the authorization server 1824 | returns an error response as described in Section 5.2. 1825 | 1826 | An example successful response: 1827 | 1828 | HTTP/1.1 200 OK 1829 | Content-Type: application/json;charset=UTF-8 1830 | Cache-Control: no-store 1831 | Pragma: no-cache 1832 | 1833 | { 1834 | "access_token":"2YotnFZFEjr1zCsicMWpAA", 1835 | "token_type":"example", 1836 | "expires_in":3600, 1837 | "example_parameter":"example_value" 1838 | } 1839 | 1840 | 1841 | ## Extension Grants 1842 | 1843 | The client uses an extension grant type by specifying the grant type 1844 | using an absolute URI (defined by the authorization server) as the 1845 | value of the "grant_type" parameter of the token endpoint, and by 1846 | adding any additional parameters necessary. 1847 | 1848 | For example, to request an access token using a Security Assertion 1849 | Markup Language (SAML) 2.0 assertion grant type as defined by 1850 | [RFC7522], the client could make the following HTTP request using 1851 | TLS (with extra line breaks for display purposes only): 1852 | 1853 | POST /token HTTP/1.1 1854 | Host: server.example.com 1855 | Content-Type: application/x-www-form-urlencoded 1856 | 1857 | grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1858 | bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1859 | [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1860 | 1861 | If the access token request is valid and authorized, the 1862 | authorization server issues an access token and optional refresh 1863 | token as described in Section 5.1. If the request failed client 1864 | authentication or is invalid, the authorization server returns an 1865 | error response as described in Section 5.2. 1866 | 1867 | 1868 | # Issuing an Access Token 1869 | 1870 | If the access token request is valid and authorized, the 1871 | authorization server issues an access token and optional refresh 1872 | token as described in Section 5.1. If the request failed client 1873 | authentication or is invalid, the authorization server returns an 1874 | error response as described in Section 5.2. 1875 | 1876 | 1877 | ## Successful Response 1878 | 1879 | The authorization server issues an access token and optional refresh 1880 | token, and constructs the response by adding the following parameters 1881 | to the entity-body of the HTTP response with a 200 (OK) status code: 1882 | 1883 | "access_token": 1884 | : REQUIRED. The access token issued by the authorization server. 1885 | 1886 | "token_type": 1887 | : REQUIRED. The type of the token issued as described in 1888 | Section 7.1. Value is case insensitive. 1889 | 1890 | "expires_in": 1891 | : RECOMMENDED. The lifetime in seconds of the access token. For 1892 | example, the value "3600" denotes that the access token will 1893 | expire in one hour from the time the response was generated. 1894 | If omitted, the authorization server SHOULD provide the 1895 | expiration time via other means or document the default value. 1896 | 1897 | "refresh_token": 1898 | : OPTIONAL. The refresh token, which can be used to obtain new 1899 | access tokens using the same authorization grant as described 1900 | in Section 6. 1901 | 1902 | "scope": 1903 | : OPTIONAL, if identical to the scope requested by the client; 1904 | otherwise, REQUIRED. The scope of the access token as 1905 | described by Section 3.3. 1906 | 1907 | The parameters are included in the entity-body of the HTTP response 1908 | using the "application/json" media type as defined by {{RFC4627}}. The 1909 | parameters are serialized into a JavaScript Object Notation (JSON) 1910 | structure by adding each parameter at the highest structure level. 1911 | Parameter names and string values are included as JSON strings. 1912 | Numerical values are included as JSON numbers. The order of 1913 | parameters does not matter and can vary. 1914 | 1915 | The authorization server MUST include the HTTP "Cache-Control" 1916 | response header field {{RFC2616}} with a value of "no-store" in any 1917 | response containing tokens, credentials, or other sensitive 1918 | information, as well as the "Pragma" response header field {{RFC2616}} 1919 | with a value of "no-cache". 1920 | 1921 | For example: 1922 | 1923 | HTTP/1.1 200 OK 1924 | Content-Type: application/json;charset=UTF-8 1925 | Cache-Control: no-store 1926 | Pragma: no-cache 1927 | 1928 | { 1929 | "access_token":"2YotnFZFEjr1zCsicMWpAA", 1930 | "token_type":"example", 1931 | "expires_in":3600, 1932 | "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1933 | "example_parameter":"example_value" 1934 | } 1935 | 1936 | The client MUST ignore unrecognized value names in the response. The 1937 | sizes of tokens and other values received from the authorization 1938 | server are left undefined. The client should avoid making 1939 | assumptions about value sizes. The authorization server SHOULD 1940 | document the size of any value it issues. 1941 | 1942 | 1943 | ## Error Response 1944 | 1945 | The authorization server responds with an HTTP 400 (Bad Request) 1946 | status code (unless specified otherwise) and includes the following 1947 | parameters with the response: 1948 | 1949 | The authorization server responds with an HTTP 400 (Bad Request) 1950 | status code (unless specified otherwise) and includes the following 1951 | parameters with the response: 1952 | 1953 | "error": 1954 | : REQUIRED. A single ASCII [USASCII] error code from the following: 1955 | 1956 | "invalid_request": 1957 | : The request is missing a required parameter, includes an 1958 | unsupported parameter value (other than grant type), 1959 | repeats a parameter, includes multiple credentials, 1960 | utilizes more than one mechanism for authenticating the 1961 | client, or is otherwise malformed. 1962 | 1963 | "invalid_client": 1964 | : Client authentication failed (e.g., unknown client, no 1965 | client authentication included, or unsupported 1966 | authentication method). The authorization server MAY 1967 | return an HTTP 401 (Unauthorized) status code to indicate 1968 | which HTTP authentication schemes are supported. If the 1969 | client attempted to authenticate via the "Authorization" 1970 | request header field, the authorization server MUST 1971 | respond with an HTTP 401 (Unauthorized) status code and 1972 | include the "WWW-Authenticate" response header field 1973 | matching the authentication scheme used by the client. 1974 | 1975 | "invalid_grant": 1976 | : The provided authorization grant (e.g., authorization 1977 | code, resource owner credentials) or refresh token is 1978 | invalid, expired, revoked, does not match the redirection 1979 | URI used in the authorization request, or was issued to 1980 | another client. 1981 | 1982 | "unauthorized_client": 1983 | : The authenticated client is not authorized to use this 1984 | authorization grant type. 1985 | 1986 | "unsupported_grant_type": 1987 | : The authorization grant type is not supported by the 1988 | authorization server. 1989 | 1990 | "invalid_scope": 1991 | : The requested scope is invalid, unknown, malformed, or 1992 | exceeds the scope granted by the resource owner. 1993 | 1994 | Values for the "error" parameter MUST NOT include characters 1995 | outside the set %x20-21 / %x23-5B / %x5D-7E. 1996 | 1997 | "error_description": 1998 | : OPTIONAL. Human-readable ASCII [USASCII] text providing 1999 | additional information, used to assist the client developer in 2000 | understanding the error that occurred. 2001 | Values for the "error_description" parameter MUST NOT include 2002 | characters outside the set %x20-21 / %x23-5B / %x5D-7E. 2003 | 2004 | "error_uri": 2005 | : OPTIONAL. A URI identifying a human-readable web page with 2006 | information about the error, used to provide the client 2007 | developer with additional information about the error. 2008 | Values for the "error_uri" parameter MUST conform to the 2009 | URI-reference syntax and thus MUST NOT include characters 2010 | outside the set %x21 / %x23-5B / %x5D-7E. 2011 | 2012 | The parameters are included in the entity-body of the HTTP response 2013 | using the "application/json" media type as defined by [RFC4627]. The 2014 | parameters are serialized into a JSON structure by adding each 2015 | parameter at the highest structure level. Parameter names and string 2016 | values are included as JSON strings. Numerical values are included 2017 | as JSON numbers. The order of parameters does not matter and can 2018 | vary. 2019 | 2020 | For example: 2021 | 2022 | HTTP/1.1 400 Bad Request 2023 | Content-Type: application/json;charset=UTF-8 2024 | Cache-Control: no-store 2025 | Pragma: no-cache 2026 | 2027 | { 2028 | "error":"invalid_request" 2029 | } 2030 | 2031 | 2032 | # Refreshing an Access Token 2033 | 2034 | If the authorization server issued a refresh token to the client, the 2035 | client makes a refresh request to the token endpoint by adding the 2036 | following parameters using the "application/x-www-form-urlencoded" 2037 | format per Appendix B with a character encoding of UTF-8 in the HTTP 2038 | request entity-body: 2039 | 2040 | "grant_type": 2041 | : REQUIRED. Value MUST be set to "refresh_token". 2042 | 2043 | "refresh_token": 2044 | : REQUIRED. The refresh token issued to the client. 2045 | 2046 | "scope": 2047 | : OPTIONAL. The scope of the access request as described by 2048 | Section 3.3. The requested scope MUST NOT include any scope 2049 | not originally granted by the resource owner, and if omitted is 2050 | treated as equal to the scope originally granted by the 2051 | resource owner. 2052 | 2053 | Because refresh tokens are typically long-lasting credentials used to 2054 | request additional access tokens, the refresh token is bound to the 2055 | client to which it was issued. If the client type is confidential or 2056 | the client was issued client credentials (or assigned other 2057 | authentication requirements), the client MUST authenticate with the 2058 | authorization server as described in Section 3.2.1. 2059 | 2060 | For example, the client makes the following HTTP request using 2061 | transport-layer security (with extra line breaks for display purposes 2062 | only): 2063 | 2064 | POST /token HTTP/1.1 2065 | Host: server.example.com 2066 | Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 2067 | Content-Type: application/x-www-form-urlencoded 2068 | 2069 | grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 2070 | 2071 | The authorization server MUST: 2072 | 2073 | * require client authentication for confidential clients or for any 2074 | client that was issued client credentials (or with other 2075 | authentication requirements), 2076 | * authenticate the client if client authentication is included and 2077 | ensure that the refresh token was issued to the authenticated 2078 | client, and 2079 | * validate the refresh token. 2080 | 2081 | If valid and authorized, the authorization server issues an access 2082 | token as described in Section 5.1. If the request failed 2083 | verification or is invalid, the authorization server returns an error 2084 | response as described in Section 5.2. 2085 | 2086 | The authorization server MAY issue a new refresh token, in which case 2087 | the client MUST discard the old refresh token and replace it with the 2088 | new refresh token. The authorization server MAY revoke the old 2089 | refresh token after issuing a new refresh token to the client. If a 2090 | new refresh token is issued, the refresh token scope MUST be 2091 | identical to that of the refresh token included by the client in the 2092 | request. 2093 | 2094 | # Accessing Protected Resources 2095 | 2096 | The client accesses protected resources by presenting the access 2097 | token to the resource server. The resource server MUST validate the 2098 | access token and ensure that it has not expired and that its scope 2099 | covers the requested resource. The methods used by the resource 2100 | server to validate the access token (as well as any error responses) 2101 | are beyond the scope of this specification but generally involve an 2102 | interaction or coordination between the resource server and the 2103 | authorization server. 2104 | 2105 | The method in which the client utilizes the access token to 2106 | authenticate with the resource server depends on the type of access 2107 | token issued by the authorization server. Typically, it involves 2108 | using the HTTP "Authorization" request header field [RFC2617] with an 2109 | authentication scheme defined by the specification of the access 2110 | token type used, such as [RFC6750]. 2111 | 2112 | 2113 | ## Access Token Types 2114 | 2115 | The access token type provides the client with the information 2116 | required to successfully utilize the access token to make a protected 2117 | resource request (along with type-specific attributes). The client 2118 | MUST NOT use an access token if it does not understand the token 2119 | type. 2120 | 2121 | For example, the "bearer" token type defined in {{RFC6750}} is utilized 2122 | by simply including the access token string in the request: 2123 | 2124 | GET /resource/1 HTTP/1.1 2125 | Host: example.com 2126 | Authorization: Bearer mF_9.B5f-4.1JqM 2127 | 2128 | while the "mac" token type defined in {{OAuth-HTTP-MAC}} is utilized by 2129 | issuing a Message Authentication Code (MAC) key together with the 2130 | access token that is used to sign certain components of the HTTP 2131 | requests: 2132 | 2133 | GET /resource/1 HTTP/1.1 2134 | Host: example.com 2135 | Authorization: MAC id="h480djs93hd8", 2136 | nonce="274312:dj83hs9s", 2137 | mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 2138 | 2139 | 2140 | The above examples are provided for illustration purposes only. 2141 | Developers are advised to consult the {{RFC6750}} and {{OAuth-HTTP-MAC}} 2142 | specifications before use. 2143 | 2144 | Each access token type definition specifies the additional attributes 2145 | (if any) sent to the client together with the "access_token" response 2146 | parameter. It also defines the HTTP authentication method used to 2147 | include the access token when making a protected resource request. 2148 | 2149 | ## Error Response 2150 | 2151 | If a resource access request fails, the resource server SHOULD inform 2152 | the client of the error. While the specifics of such error responses 2153 | are beyond the scope of this specification, this document establishes 2154 | a common registry in Section 11.4 for error values to be shared among 2155 | OAuth token authentication schemes. 2156 | 2157 | New authentication schemes designed primarily for OAuth token 2158 | authentication SHOULD define a mechanism for providing an error 2159 | status code to the client, in which the error values allowed are 2160 | registered in the error registry established by this specification. 2161 | 2162 | Such schemes MAY limit the set of valid error codes to a subset of 2163 | the registered values. If the error code is returned using a named 2164 | parameter, the parameter name SHOULD be "error". 2165 | 2166 | Other schemes capable of being used for OAuth token authentication, 2167 | but not primarily designed for that purpose, MAY bind their error 2168 | values to the registry in the same manner. 2169 | 2170 | New authentication schemes MAY choose to also specify the use of the 2171 | "error_description" and "error_uri" parameters to return error 2172 | information in a manner parallel to their usage in this 2173 | specification. 2174 | 2175 | 2176 | # Extensibility 2177 | 2178 | ## Defining Access Token Types 2179 | 2180 | Access token types can be defined in one of two ways: registered in 2181 | the Access Token Types registry (following the procedures in 2182 | Section 11.1), or by using a unique absolute URI as its name. 2183 | 2184 | Types utilizing a URI name SHOULD be limited to vendor-specific 2185 | implementations that are not commonly applicable, and are specific to 2186 | the implementation details of the resource server where they are 2187 | used. 2188 | 2189 | All other types MUST be registered. Type names MUST conform to the 2190 | type-name ABNF. If the type definition includes a new HTTP 2191 | authentication scheme, the type name SHOULD be identical to the HTTP 2192 | authentication scheme name (as defined by [RFC2617]). The token type 2193 | "example" is reserved for use in examples. 2194 | 2195 | type-name = 1*name-char 2196 | name-char = "-" / "." / "_" / DIGIT / ALPHA 2197 | 2198 | 2199 | ## Defining New Endpoint Parameters 2200 | 2201 | New request or response parameters for use with the authorization 2202 | endpoint or the token endpoint are defined and registered in the 2203 | OAuth Parameters registry following the procedure in Section 11.2. 2204 | 2205 | Parameter names MUST conform to the param-name ABNF, and parameter 2206 | values syntax MUST be well-defined (e.g., using ABNF, or a reference 2207 | to the syntax of an existing parameter). 2208 | 2209 | param-name = 1*name-char 2210 | name-char = "-" / "." / "_" / DIGIT / ALPHA 2211 | 2212 | Unregistered vendor-specific parameter extensions that are not 2213 | commonly applicable and that are specific to the implementation 2214 | details of the authorization server where they are used SHOULD 2215 | utilize a vendor-specific prefix that is not likely to conflict with 2216 | other registered values (e.g., begin with 'companyname_'). 2217 | 2218 | 2219 | ## Defining New Authorization Grant Types 2220 | 2221 | New authorization grant types can be defined by assigning them a 2222 | unique absolute URI for use with the "grant_type" parameter. If the 2223 | extension grant type requires additional token endpoint parameters, 2224 | they MUST be registered in the OAuth Parameters registry as described 2225 | by Section 11.2. 2226 | 2227 | 2228 | ## Defining New Authorization Endpoint Response Types 2229 | 2230 | New response types for use with the authorization endpoint are 2231 | defined and registered in the Authorization Endpoint Response Types 2232 | registry following the procedure in Section 11.3. Response type 2233 | names MUST conform to the response-type ABNF. 2234 | 2235 | response-type = response-name *( SP response-name ) 2236 | response-name = 1*response-char 2237 | response-char = "_" / DIGIT / ALPHA 2238 | 2239 | If a response type contains one or more space characters (%x20), it 2240 | is compared as a space-delimited list of values in which the order of 2241 | values does not matter. Only one order of values can be registered, 2242 | which covers all other arrangements of the same set of values. 2243 | 2244 | For example, the response type "token code" is left undefined by this 2245 | specification. However, an extension can define and register the 2246 | "token code" response type. Once registered, the same combination 2247 | cannot be registered as "code token", but both values can be used to 2248 | denote the same response type. 2249 | 2250 | 2251 | ## Defining Additional Error Codes 2252 | 2253 | In cases where protocol extensions (i.e., access token types, 2254 | extension parameters, or extension grant types) require additional 2255 | error codes to be used with the authorization code grant error 2256 | response (Section 4.1.2.1), the implicit grant error response 2257 | (Section 4.2.2.1), the token error response (Section 5.2), or the 2258 | resource access error response (Section 7.2), such error codes MAY be 2259 | defined. 2260 | 2261 | Extension error codes MUST be registered (following the procedures in 2262 | Section 11.4) if the extension they are used in conjunction with is a 2263 | registered access token type, a registered endpoint parameter, or an 2264 | extension grant type. Error codes used with unregistered extensions 2265 | MAY be registered. 2266 | 2267 | Error codes MUST conform to the error ABNF and SHOULD be prefixed by 2268 | an identifying name when possible. For example, an error identifying 2269 | an invalid value set to the extension parameter "example" SHOULD be 2270 | named "example_invalid". 2271 | 2272 | error = 1*error-char 2273 | error-char = %x20-21 / %x23-5B / %x5D-7E 2274 | 2275 | 2276 | # Native Applications 2277 | 2278 | Native applications are clients installed and executed on the device 2279 | used by the resource owner (i.e., desktop application, native mobile 2280 | application). Native applications require special consideration 2281 | related to security, platform capabilities, and overall end-user 2282 | experience. 2283 | 2284 | The authorization endpoint requires interaction between the client 2285 | and the resource owner's user-agent. Native applications can invoke 2286 | an external user-agent or embed a user-agent within the application. 2287 | For example: 2288 | 2289 | * External user-agent - the native application can capture the 2290 | response from the authorization server using a redirection URI 2291 | with a scheme registered with the operating system to invoke the 2292 | client as the handler, manual copy-and-paste of the credentials, 2293 | running a local web server, installing a user-agent extension, or 2294 | by providing a redirection URI identifying a server-hosted 2295 | resource under the client's control, which in turn makes the 2296 | response available to the native application. 2297 | * Embedded user-agent - the native application obtains the response 2298 | by directly communicating with the embedded user-agent by 2299 | monitoring state changes emitted during the resource load, or 2300 | accessing the user-agent's cookies storage. 2301 | 2302 | When choosing between an external or embedded user-agent, developers 2303 | should consider the following: 2304 | 2305 | * An external user-agent may improve completion rate, as the 2306 | resource owner may already have an active session with the 2307 | authorization server, removing the need to re-authenticate. It 2308 | provides a familiar end-user experience and functionality. The 2309 | resource owner may also rely on user-agent features or extensions 2310 | to assist with authentication (e.g., password manager, 2-factor 2311 | device reader). 2312 | * An embedded user-agent may offer improved usability, as it removes 2313 | the need to switch context and open new windows. 2314 | * An embedded user-agent poses a security challenge because resource 2315 | owners are authenticating in an unidentified window without access 2316 | to the visual protections found in most external user-agents. An 2317 | embedded user-agent educates end-users to trust unidentified 2318 | requests for authentication (making phishing attacks easier to 2319 | execute). 2320 | 2321 | When choosing between the implicit grant type and the authorization 2322 | code grant type, the following should be considered: 2323 | 2324 | * Native applications that use the authorization code grant type 2325 | SHOULD do so without using client credentials, due to the native 2326 | application's inability to keep client credentials confidential. 2327 | * When using the implicit grant type flow, a refresh token is not 2328 | returned, which requires repeating the authorization process once 2329 | the access token expires. 2330 | 2331 | 2332 | # Security Considerations 2333 | 2334 | As a flexible and extensible framework, OAuth's security 2335 | considerations depend on many factors. The following sections 2336 | provide implementers with security guidelines focused on the three 2337 | client profiles described in Section 2.1: web application, 2338 | user-agent-based application, and native application. 2339 | 2340 | A comprehensive OAuth security model and analysis, as well as 2341 | background for the protocol design, is provided by 2342 | {{RFC6819}}. 2343 | 2344 | 2345 | ## Client Authentication 2346 | 2347 | The authorization server establishes client credentials with web 2348 | application clients for the purpose of client authentication. The 2349 | authorization server is encouraged to consider stronger client 2350 | authentication means than a client password. Web application clients 2351 | MUST ensure confidentiality of client passwords and other client 2352 | credentials. 2353 | 2354 | The authorization server MUST NOT issue client passwords or other 2355 | client credentials to native application or user-agent-based 2356 | application clients for the purpose of client authentication. The 2357 | authorization server MAY issue a client password or other credentials 2358 | for a specific installation of a native application client on a 2359 | specific device. 2360 | 2361 | When client authentication is not possible, the authorization server 2362 | SHOULD employ other means to validate the client's identity -- for 2363 | example, by requiring the registration of the client redirection URI 2364 | or enlisting the resource owner to confirm identity. A valid 2365 | redirection URI is not sufficient to verify the client's identity 2366 | when asking for resource owner authorization but can be used to 2367 | prevent delivering credentials to a counterfeit client after 2368 | obtaining resource owner authorization. 2369 | 2370 | The authorization server must consider the security implications of 2371 | interacting with unauthenticated clients and take measures to limit 2372 | the potential exposure of other credentials (e.g., refresh tokens) 2373 | issued to such clients. 2374 | 2375 | 2376 | ## Client Impersonation 2377 | 2378 | A malicious client can impersonate another client and obtain access 2379 | to protected resources if the impersonated client fails to, or is 2380 | unable to, keep its client credentials confidential. 2381 | 2382 | The authorization server MUST authenticate the client whenever 2383 | possible. If the authorization server cannot authenticate the client 2384 | due to the client's nature, the authorization server MUST require the 2385 | registration of any redirection URI used for receiving authorization 2386 | responses and SHOULD utilize other means to protect resource owners 2387 | from such potentially malicious clients. For example, the 2388 | authorization server can engage the resource owner to assist in 2389 | identifying the client and its origin. 2390 | 2391 | The authorization server SHOULD enforce explicit resource owner 2392 | authentication and provide the resource owner with information about 2393 | the client and the requested authorization scope and lifetime. It is 2394 | up to the resource owner to review the information in the context of 2395 | the current client and to authorize or deny the request. 2396 | 2397 | The authorization server SHOULD NOT process repeated authorization 2398 | requests automatically (without active resource owner interaction) 2399 | without authenticating the client or relying on other measures to 2400 | ensure that the repeated request comes from the original client and 2401 | not an impersonator. 2402 | 2403 | 2404 | ## Access Tokens 2405 | 2406 | Access token credentials (as well as any confidential access token 2407 | attributes) MUST be kept confidential in transit and storage, and 2408 | only shared among the authorization server, the resource servers the 2409 | access token is valid for, and the client to whom the access token is 2410 | issued. Access token credentials MUST only be transmitted using TLS 2411 | as described in Section 1.6 with server authentication as defined by 2412 | [RFC2818]. 2413 | 2414 | When using the implicit grant type, the access token is transmitted 2415 | in the URI fragment, which can expose it to unauthorized parties. 2416 | 2417 | The authorization server MUST ensure that access tokens cannot be 2418 | generated, modified, or guessed to produce valid access tokens by 2419 | unauthorized parties. 2420 | 2421 | The client SHOULD request access tokens with the minimal scope 2422 | necessary. The authorization server SHOULD take the client identity 2423 | into account when choosing how to honor the requested scope and MAY 2424 | issue an access token with less rights than requested. 2425 | 2426 | This specification does not provide any methods for the resource 2427 | server to ensure that an access token presented to it by a given 2428 | client was issued to that client by the authorization server. 2429 | 2430 | 2431 | ## Refresh Tokens 2432 | 2433 | Authorization servers MAY issue refresh tokens to web application 2434 | clients and native application clients. 2435 | 2436 | Refresh tokens MUST be kept confidential in transit and storage, and 2437 | shared only among the authorization server and the client to whom the 2438 | refresh tokens were issued. The authorization server MUST maintain 2439 | the binding between a refresh token and the client to whom it was 2440 | issued. Refresh tokens MUST only be transmitted using TLS as 2441 | described in Section 1.6 with server authentication as defined by 2442 | [RFC2818]. 2443 | 2444 | The authorization server MUST verify the binding between the refresh 2445 | token and client identity whenever the client identity can be 2446 | authenticated. When client authentication is not possible, the 2447 | authorization server SHOULD deploy other means to detect refresh 2448 | token abuse. 2449 | 2450 | For example, the authorization server could employ refresh token 2451 | rotation in which a new refresh token is issued with every access 2452 | token refresh response. The previous refresh token is invalidated 2453 | but retained by the authorization server. If a refresh token is 2454 | compromised and subsequently used by both the attacker and the 2455 | legitimate client, one of them will present an invalidated refresh 2456 | token, which will inform the authorization server of the breach. 2457 | 2458 | The authorization server MUST ensure that refresh tokens cannot be 2459 | generated, modified, or guessed to produce valid refresh tokens by 2460 | unauthorized parties. 2461 | 2462 | 2463 | ## Authorization Codes 2464 | 2465 | The transmission of authorization codes SHOULD be made over a secure 2466 | channel, and the client SHOULD require the use of TLS with its 2467 | redirection URI if the URI identifies a network resource. Since 2468 | authorization codes are transmitted via user-agent redirections, they 2469 | could potentially be disclosed through user-agent history and HTTP 2470 | referrer headers. 2471 | 2472 | Authorization codes operate as plaintext bearer credentials, used to 2473 | verify that the resource owner who granted authorization at the 2474 | authorization server is the same resource owner returning to the 2475 | client to complete the process. Therefore, if the client relies on 2476 | the authorization code for its own resource owner authentication, the 2477 | client redirection endpoint MUST require the use of TLS. 2478 | 2479 | Authorization codes MUST be short lived and single-use. If the 2480 | authorization server observes multiple attempts to exchange an 2481 | authorization code for an access token, the authorization server 2482 | SHOULD attempt to revoke all access tokens already granted based on 2483 | the compromised authorization code. 2484 | 2485 | If the client can be authenticated, the authorization servers MUST 2486 | authenticate the client and ensure that the authorization code was 2487 | issued to the same client. 2488 | 2489 | 2490 | ## Authorization Code Redirection URI Manipulation 2491 | 2492 | When requesting authorization using the authorization code grant 2493 | type, the client can specify a redirection URI via the "redirect_uri" 2494 | parameter. If an attacker can manipulate the value of the 2495 | redirection URI, it can cause the authorization server to redirect 2496 | the resource owner user-agent to a URI under the control of the 2497 | attacker with the authorization code. 2498 | 2499 | An attacker can create an account at a legitimate client and initiate 2500 | the authorization flow. When the attacker's user-agent is sent to 2501 | the authorization server to grant access, the attacker grabs the 2502 | authorization URI provided by the legitimate client and replaces the 2503 | client's redirection URI with a URI under the control of the 2504 | attacker. The attacker then tricks the victim into following the 2505 | manipulated link to authorize access to the legitimate client. 2506 | 2507 | Once at the authorization server, the victim is prompted with a 2508 | normal, valid request on behalf of a legitimate and trusted client, 2509 | and authorizes the request. The victim is then redirected to an 2510 | endpoint under the control of the attacker with the authorization 2511 | code. The attacker completes the authorization flow by sending the 2512 | authorization code to the client using the original redirection URI 2513 | provided by the client. The client exchanges the authorization code 2514 | with an access token and links it to the attacker's client account, 2515 | which can now gain access to the protected resources authorized by 2516 | the victim (via the client). 2517 | 2518 | In order to prevent such an attack, the authorization server MUST 2519 | ensure that the redirection URI used to obtain the authorization code 2520 | is identical to the redirection URI provided when exchanging the 2521 | authorization code for an access token. The authorization server 2522 | MUST require public clients and SHOULD require confidential clients 2523 | to register their redirection URIs. If a redirection URI is provided 2524 | in the request, the authorization server MUST validate it against the 2525 | registered value. 2526 | 2527 | 2528 | ## Resource Owner Password Credentials 2529 | 2530 | The resource owner password credentials grant type is often used for 2531 | legacy or migration reasons. It reduces the overall risk of storing 2532 | usernames and passwords by the client but does not eliminate the need 2533 | to expose highly privileged credentials to the client. 2534 | 2535 | This grant type carries a higher risk than other grant types because 2536 | it maintains the password anti-pattern this protocol seeks to avoid. 2537 | The client could abuse the password, or the password could 2538 | unintentionally be disclosed to an attacker (e.g., via log files or 2539 | other records kept by the client). 2540 | 2541 | Additionally, because the resource owner does not have control over 2542 | the authorization process (the resource owner's involvement ends when 2543 | it hands over its credentials to the client), the client can obtain 2544 | access tokens with a broader scope than desired by the resource 2545 | owner. The authorization server should consider the scope and 2546 | lifetime of access tokens issued via this grant type. 2547 | 2548 | The authorization server and client SHOULD minimize use of this grant 2549 | type and utilize other grant types whenever possible. 2550 | 2551 | 2552 | ## Request Confidentiality 2553 | 2554 | Access tokens, refresh tokens, resource owner passwords, and client 2555 | credentials MUST NOT be transmitted in the clear. Authorization 2556 | codes SHOULD NOT be transmitted in the clear. 2557 | 2558 | The "state" and "scope" parameters SHOULD NOT include sensitive 2559 | client or resource owner information in plain text, as they can be 2560 | transmitted over insecure channels or stored insecurely. 2561 | 2562 | 2563 | ## Ensuring Endpoint Authenticity 2564 | 2565 | In order to prevent man-in-the-middle attacks, the authorization 2566 | server MUST require the use of TLS with server authentication as 2567 | defined by [RFC2818] for any request sent to the authorization and 2568 | token endpoints. The client MUST validate the authorization server's 2569 | TLS certificate as defined by [RFC6125] and in accordance with its 2570 | requirements for server identity authentication. 2571 | 2572 | 2573 | ## Credentials-Guessing Attacks 2574 | 2575 | The authorization server MUST prevent attackers from guessing access 2576 | tokens, authorization codes, refresh tokens, resource owner 2577 | passwords, and client credentials. 2578 | 2579 | The probability of an attacker guessing generated tokens (and other 2580 | credentials not intended for handling by end-users) MUST be less than 2581 | or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2582 | 2583 | The authorization server MUST utilize other means to protect 2584 | credentials intended for end-user usage. 2585 | 2586 | 2587 | ## Phishing Attacks 2588 | 2589 | Wide deployment of this and similar protocols may cause end-users to 2590 | become inured to the practice of being redirected to websites where 2591 | they are asked to enter their passwords. If end-users are not 2592 | careful to verify the authenticity of these websites before entering 2593 | their credentials, it will be possible for attackers to exploit this 2594 | practice to steal resource owners' passwords. 2595 | 2596 | Service providers should attempt to educate end-users about the risks 2597 | phishing attacks pose and should provide mechanisms that make it easy 2598 | for end-users to confirm the authenticity of their sites. Client 2599 | developers should consider the security implications of how they 2600 | interact with the user-agent (e.g., external, embedded), and the 2601 | ability of the end-user to verify the authenticity of the 2602 | authorization server. 2603 | 2604 | To reduce the risk of phishing attacks, the authorization servers 2605 | MUST require the use of TLS on every endpoint used for end-user 2606 | interaction. 2607 | 2608 | 2609 | ## Cross-Site Request Forgery 2610 | 2611 | Cross-site request forgery (CSRF) is an exploit in which an attacker 2612 | causes the user-agent of a victim end-user to follow a malicious URI 2613 | (e.g., provided to the user-agent as a misleading link, image, or 2614 | redirection) to a trusting server (usually established via the 2615 | presence of a valid session cookie). 2616 | 2617 | A CSRF attack against the client's redirection URI allows an attacker 2618 | to inject its own authorization code or access token, which can 2619 | result in the client using an access token associated with the 2620 | attacker's protected resources rather than the victim's (e.g., save 2621 | the victim's bank account information to a protected resource 2622 | controlled by the attacker). 2623 | 2624 | The client MUST implement CSRF protection for its redirection URI. 2625 | This is typically accomplished by requiring any request sent to the 2626 | redirection URI endpoint to include a value that binds the request to 2627 | the user-agent's authenticated state (e.g., a hash of the session 2628 | cookie used to authenticate the user-agent). The client SHOULD 2629 | utilize the "state" request parameter to deliver this value to the 2630 | authorization server when making an authorization request. 2631 | 2632 | Once authorization has been obtained from the end-user, the 2633 | authorization server redirects the end-user's user-agent back to the 2634 | client with the required binding value contained in the "state" 2635 | parameter. The binding value enables the client to verify the 2636 | validity of the request by matching the binding value to the 2637 | user-agent's authenticated state. The binding value used for CSRF 2638 | protection MUST contain a non-guessable value (as described in 2639 | Section 10.10), and the user-agent's authenticated state (e.g., 2640 | session cookie, HTML5 local storage) MUST be kept in a location 2641 | accessible only to the client and the user-agent (i.e., protected by 2642 | same-origin policy). 2643 | 2644 | A CSRF attack against the authorization server's authorization 2645 | endpoint can result in an attacker obtaining end-user authorization 2646 | for a malicious client without involving or alerting the end-user. 2647 | 2648 | The authorization server MUST implement CSRF protection for its 2649 | authorization endpoint and ensure that a malicious client cannot 2650 | obtain authorization without the awareness and explicit consent of 2651 | the resource owner. 2652 | 2653 | 2654 | ## Clickjacking 2655 | 2656 | In a clickjacking attack, an attacker registers a legitimate client 2657 | and then constructs a malicious site in which it loads the 2658 | authorization server's authorization endpoint web page in a 2659 | transparent iframe overlaid on top of a set of dummy buttons, which 2660 | are carefully constructed to be placed directly under important 2661 | buttons on the authorization page. When an end-user clicks a 2662 | misleading visible button, the end-user is actually clicking an 2663 | invisible button on the authorization page (such as an "Authorize" 2664 | button). This allows an attacker to trick a resource owner into 2665 | granting its client access without the end-user's knowledge. 2666 | 2667 | To prevent this form of attack, native applications SHOULD use 2668 | external browsers instead of embedding browsers within the 2669 | application when requesting end-user authorization. For most newer 2670 | browsers, avoidance of iframes can be enforced by the authorization 2671 | server using the (non-standard) "x-frame-options" header. This 2672 | header can have two values, "deny" and "sameorigin", which will block 2673 | any framing, or framing by sites with a different origin, 2674 | respectively. For older browsers, JavaScript frame-busting 2675 | techniques can be used but may not be effective in all browsers. 2676 | 2677 | 2678 | ## Code Injection and Input Validation 2679 | 2680 | A code injection attack occurs when an input or otherwise external 2681 | variable is used by an application unsanitized and causes 2682 | modification to the application logic. This may allow an attacker to 2683 | gain access to the application device or its data, cause denial of 2684 | service, or introduce a wide range of malicious side-effects. 2685 | 2686 | The authorization server and client MUST sanitize (and validate when 2687 | possible) any value received -- in particular, the value of the 2688 | "state" and "redirect_uri" parameters. 2689 | 2690 | 2691 | ## Open Redirectors 2692 | 2693 | The authorization server, authorization endpoint, and client 2694 | redirection endpoint can be improperly configured and operate as open 2695 | redirectors. An open redirector is an endpoint using a parameter to 2696 | automatically redirect a user-agent to the location specified by the 2697 | parameter value without any validation. 2698 | 2699 | Open redirectors can be used in phishing attacks, or by an attacker 2700 | to get end-users to visit malicious sites by using the URI authority 2701 | component of a familiar and trusted destination. In addition, if the 2702 | authorization server allows the client to register only part of the 2703 | redirection URI, an attacker can use an open redirector operated by 2704 | the client to construct a redirection URI that will pass the 2705 | authorization server validation but will send the authorization code 2706 | or access token to an endpoint under the control of the attacker. 2707 | 2708 | 2709 | ## Misuse of Access Token to Impersonate Resource Owner in Implicit Flow 2710 | 2711 | For public clients using implicit flows, this specification does not 2712 | provide any method for the client to determine what client an access 2713 | token was issued to. 2714 | 2715 | A resource owner may willingly delegate access to a resource by 2716 | granting an access token to an attacker's malicious client. This may 2717 | be due to phishing or some other pretext. An attacker may also steal 2718 | a token via some other mechanism. An attacker may then attempt to 2719 | impersonate the resource owner by providing the access token to a 2720 | legitimate public client. 2721 | 2722 | In the implicit flow (response_type=token), the attacker can easily 2723 | switch the token in the response from the authorization server, 2724 | replacing the real access token with the one previously issued to the 2725 | attacker. 2726 | 2727 | Servers communicating with native applications that rely on being 2728 | passed an access token in the back channel to identify the user of 2729 | the client may be similarly compromised by an attacker creating a 2730 | compromised application that can inject arbitrary stolen access 2731 | tokens. 2732 | 2733 | Any public client that makes the assumption that only the resource 2734 | owner can present it with a valid access token for the resource is 2735 | vulnerable to this type of attack. 2736 | 2737 | This type of attack may expose information about the resource owner 2738 | at the legitimate client to the attacker (malicious client). This 2739 | will also allow the attacker to perform operations at the legitimate 2740 | client with the same permissions as the resource owner who originally 2741 | granted the access token or authorization code. 2742 | 2743 | Authenticating resource owners to clients is out of scope for this 2744 | specification. Any specification that uses the authorization process 2745 | as a form of delegated end-user authentication to the client (e.g., 2746 | third-party sign-in service) MUST NOT use the implicit flow without 2747 | additional security mechanisms that would enable the client to 2748 | determine if the access token was issued for its use (e.g., audience- 2749 | restricting the access token). 2750 | 2751 | 2752 | # IANA Considerations 2753 | 2754 | ## OAuth Access Token Types Registry 2755 | 2756 | This specification establishes the OAuth Access Token Types registry. 2757 | 2758 | Access token types are registered with a Specification Required 2759 | ([RFC5226]) after a two-week review period on the 2760 | oauth-ext-review@ietf.org mailing list, on the advice of one or more 2761 | Designated Experts. However, to allow for the allocation of values 2762 | prior to publication, the Designated Expert(s) may approve 2763 | registration once they are satisfied that such a specification will 2764 | be published. 2765 | 2766 | Registration requests must be sent to the oauth-ext-review@ietf.org 2767 | mailing list for review and comment, with an appropriate subject 2768 | (e.g., "Request for access token type: example"). 2769 | 2770 | Within the review period, the Designated Expert(s) will either 2771 | approve or deny the registration request, communicating this decision 2772 | to the review list and IANA. Denials should include an explanation 2773 | and, if applicable, suggestions as to how to make the request 2774 | successful. 2775 | 2776 | IANA must only accept registry updates from the Designated Expert(s) 2777 | and should direct all requests for registration to the review mailing 2778 | list. 2779 | 2780 | ### Registration Template 2781 | 2782 | Type name: 2783 | : The name requested (e.g., "example"). 2784 | 2785 | Additional Token Endpoint Response Parameters: 2786 | : Additional response parameters returned together with the 2787 | "access_token" parameter. New parameters MUST be separately 2788 | registered in the OAuth Parameters registry as described by 2789 | Section 11.2. 2790 | 2791 | HTTP Authentication Scheme(s): 2792 | : The HTTP authentication scheme name(s), if any, used to 2793 | authenticate protected resource requests using access tokens of 2794 | this type. 2795 | 2796 | Change controller: 2797 | : For Standards Track RFCs, state "IETF". For others, give the name 2798 | of the responsible party. Other details (e.g., postal address, 2799 | email address, home page URI) may also be included. 2800 | 2801 | Specification document(s): 2802 | : Reference to the document(s) that specify the parameter, 2803 | preferably including a URI that can be used to retrieve a copy of 2804 | the document(s). An indication of the relevant sections may also 2805 | be included but is not required. 2806 | 2807 | 2808 | ## OAuth Parameters Registry 2809 | 2810 | This specification establishes the OAuth Parameters registry. 2811 | 2812 | Additional parameters for inclusion in the authorization endpoint 2813 | request, the authorization endpoint response, the token endpoint 2814 | request, or the token endpoint response are registered with a 2815 | Specification Required ([RFC5226]) after a two-week review period on 2816 | the oauth-ext-review@ietf.org mailing list, on the advice of one or 2817 | more Designated Experts. However, to allow for the allocation of 2818 | values prior to publication, the Designated Expert(s) may approve 2819 | registration once they are satisfied that such a specification will 2820 | be published. 2821 | 2822 | Registration requests must be sent to the oauth-ext-review@ietf.org 2823 | mailing list for review and comment, with an appropriate subject 2824 | (e.g., "Request for parameter: example"). 2825 | 2826 | Within the review period, the Designated Expert(s) will either 2827 | approve or deny the registration request, communicating this decision 2828 | to the review list and IANA. Denials should include an explanation 2829 | and, if applicable, suggestions as to how to make the request 2830 | successful. 2831 | 2832 | IANA must only accept registry updates from the Designated Expert(s) 2833 | and should direct all requests for registration to the review mailing 2834 | list. 2835 | 2836 | ### Registration Template 2837 | 2838 | Parameter name: 2839 | : The name requested (e.g., "example"). 2840 | 2841 | Parameter usage location: 2842 | : The location(s) where parameter can be used. The possible 2843 | locations are authorization request, authorization response, token 2844 | request, or token response. 2845 | 2846 | Change controller: 2847 | : For Standards Track RFCs, state "IETF". For others, give the name 2848 | of the responsible party. Other details (e.g., postal address, 2849 | email address, home page URI) may also be included. 2850 | 2851 | Specification document(s): 2852 | : Reference to the document(s) that specify the parameter, 2853 | preferably including a URI that can be used to retrieve a copy of 2854 | the document(s). An indication of the relevant sections may also 2855 | be included but is not required. 2856 | 2857 | ### Initial Registry Contents 2858 | 2859 | The OAuth Parameters registry's initial contents are: 2860 | 2861 | * Parameter name: client_id 2862 | * Parameter usage location: authorization request, token request 2863 | * Change controller: IETF 2864 | * Specification document(s): RFC 6749 2865 | 2866 | * Parameter name: client_secret 2867 | * Parameter usage location: token request 2868 | * Change controller: IETF 2869 | * Specification document(s): RFC 6749 2870 | 2871 | * Parameter name: response_type 2872 | * Parameter usage location: authorization request 2873 | * Change controller: IETF 2874 | * Specification document(s): RFC 6749 2875 | 2876 | * Parameter name: redirect_uri 2877 | * Parameter usage location: authorization request, token request 2878 | * Change controller: IETF 2879 | * Specification document(s): RFC 6749 2880 | 2881 | * Parameter name: scope 2882 | * Parameter usage location: authorization request, authorization 2883 | response, token request, token response 2884 | * Change controller: IETF 2885 | * Specification document(s): RFC 6749 2886 | 2887 | * Parameter name: state 2888 | * Parameter usage location: authorization request, authorization 2889 | response 2890 | * Change controller: IETF 2891 | * Specification document(s): RFC 6749 2892 | 2893 | * Parameter name: code 2894 | * Parameter usage location: authorization response, token request 2895 | * Change controller: IETF 2896 | * Specification document(s): RFC 6749 2897 | 2898 | * Parameter name: error_description 2899 | * Parameter usage location: authorization response, token response 2900 | * Change controller: IETF 2901 | * Specification document(s): RFC 6749 2902 | 2903 | * Parameter name: error_uri 2904 | * Parameter usage location: authorization response, token response 2905 | * Change controller: IETF 2906 | * Specification document(s): RFC 6749 2907 | 2908 | * Parameter name: grant_type 2909 | * Parameter usage location: token request 2910 | * Change controller: IETF 2911 | * Specification document(s): RFC 6749 2912 | 2913 | * Parameter name: access_token 2914 | * Parameter usage location: authorization response, token response 2915 | * Change controller: IETF 2916 | * Specification document(s): RFC 6749 2917 | 2918 | * Parameter name: token_type 2919 | * Parameter usage location: authorization response, token response 2920 | * Change controller: IETF 2921 | * Specification document(s): RFC 6749 2922 | 2923 | * Parameter name: expires_in 2924 | * Parameter usage location: authorization response, token response 2925 | * Change controller: IETF 2926 | * Specification document(s): RFC 6749 2927 | 2928 | * Parameter name: username 2929 | * Parameter usage location: token request 2930 | * Change controller: IETF 2931 | * Specification document(s): RFC 6749 2932 | 2933 | * Parameter name: password 2934 | * Parameter usage location: token request 2935 | * Change controller: IETF 2936 | * Specification document(s): RFC 6749 2937 | 2938 | * Parameter name: refresh_token 2939 | * Parameter usage location: token request, token response 2940 | * Change controller: IETF 2941 | * Specification document(s): RFC 6749 2942 | 2943 | 2944 | ## OAuth Authorization Endpoint Response Types Registry 2945 | 2946 | This specification establishes the OAuth Authorization Endpoint 2947 | Response Types registry. 2948 | 2949 | Additional response types for use with the authorization endpoint are 2950 | registered with a Specification Required ([RFC5226]) after a two-week 2951 | review period on the oauth-ext-review@ietf.org mailing list, on the 2952 | advice of one or more Designated Experts. However, to allow for the 2953 | allocation of values prior to publication, the Designated Expert(s) 2954 | may approve registration once they are satisfied that such a 2955 | specification will be published. 2956 | 2957 | Registration requests must be sent to the oauth-ext-review@ietf.org 2958 | mailing list for review and comment, with an appropriate subject 2959 | (e.g., "Request for response type: example"). 2960 | 2961 | Within the review period, the Designated Expert(s) will either 2962 | approve or deny the registration request, communicating this decision 2963 | to the review list and IANA. Denials should include an explanation 2964 | and, if applicable, suggestions as to how to make the request 2965 | successful. 2966 | 2967 | IANA must only accept registry updates from the Designated Expert(s) 2968 | and should direct all requests for registration to the review mailing 2969 | list. 2970 | 2971 | ### Registration Template 2972 | 2973 | Response type name: 2974 | : The name requested (e.g., "example"). 2975 | 2976 | Change controller: 2977 | : For Standards Track RFCs, state "IETF". For others, give the name 2978 | of the responsible party. Other details (e.g., postal address, 2979 | email address, home page URI) may also be included. 2980 | 2981 | Specification document(s): 2982 | : Reference to the document(s) that specify the type, preferably 2983 | including a URI that can be used to retrieve a copy of the 2984 | document(s). An indication of the relevant sections may also be 2985 | included but is not required. 2986 | 2987 | 2988 | ### Initial Registry Contents 2989 | 2990 | The OAuth Authorization Endpoint Response Types registry's initial 2991 | contents are: 2992 | 2993 | * Response type name: code 2994 | * Change controller: IETF 2995 | * Specification document(s): RFC 6749 2996 | 2997 | * Response type name: token 2998 | * Change controller: IETF 2999 | * Specification document(s): RFC 6749 3000 | 3001 | 3002 | ## OAuth Extensions Error Registry 3003 | 3004 | This specification establishes the OAuth Extensions Error registry. 3005 | 3006 | Additional error codes used together with other protocol extensions 3007 | (i.e., extension grant types, access token types, or extension 3008 | parameters) are registered with a Specification Required ([RFC5226]) 3009 | after a two-week review period on the oauth-ext-review@ietf.org 3010 | mailing list, on the advice of one or more Designated Experts. 3011 | However, to allow for the allocation of values prior to publication, 3012 | the Designated Expert(s) may approve registration once they are 3013 | satisfied that such a specification will be published. 3014 | 3015 | Registration requests must be sent to the oauth-ext-review@ietf.org 3016 | mailing list for review and comment, with an appropriate subject 3017 | (e.g., "Request for error code: example"). 3018 | 3019 | Within the review period, the Designated Expert(s) will either 3020 | approve or deny the registration request, communicating this decision 3021 | to the review list and IANA. Denials should include an explanation 3022 | and, if applicable, suggestions as to how to make the request 3023 | successful. 3024 | 3025 | IANA must only accept registry updates from the Designated Expert(s) 3026 | and should direct all requests for registration to the review mailing 3027 | list. 3028 | 3029 | 3030 | ### Registration Template 3031 | 3032 | Error name: 3033 | : The name requested (e.g., "example"). Values for the error name 3034 | MUST NOT include characters outside the set %x20-21 / %x23-5B / 3035 | %x5D-7E. 3036 | 3037 | Error usage location: 3038 | : The location(s) where the error can be used. The possible 3039 | locations are authorization code grant error response 3040 | (Section 4.1.2.1), implicit grant error response 3041 | (Section 4.2.2.1), token error response (Section 5.2), or resource 3042 | access error response (Section 7.2). 3043 | 3044 | Related protocol extension: 3045 | : The name of the extension grant type, access token type, or 3046 | extension parameter that the error code is used in conjunction 3047 | with. 3048 | 3049 | Change controller: 3050 | : For Standards Track RFCs, state "IETF". For others, give the name 3051 | of the responsible party. Other details (e.g., postal address, 3052 | email address, home page URI) may also be included. 3053 | 3054 | Specification document(s): 3055 | : Reference to the document(s) that specify the error code, 3056 | preferably including a URI that can be used to retrieve a copy of 3057 | the document(s). An indication of the relevant sections may also 3058 | be included but is not required. 3059 | 3060 | 3061 | --- back 3062 | 3063 | 3064 | # Augmented Backus-Naur Form (ABNF) Syntax 3065 | 3066 | This section provides Augmented Backus-Naur Form (ABNF) syntax 3067 | descriptions for the elements defined in this specification using the 3068 | notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3069 | code points [W3C.REC-xml-20081126]; these characters are typically 3070 | encoded in UTF-8. Elements are presented in the order first defined. 3071 | 3072 | Some of the definitions that follow use the "URI-reference" 3073 | definition from [RFC3986]. 3074 | 3075 | Some of the definitions that follow use these common definitions: 3076 | 3077 | VSCHAR = %x20-7E 3078 | NQCHAR = %x21 / %x23-5B / %x5D-7E 3079 | NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3080 | UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3081 | %xE000-FFFD / %x10000-10FFFF 3082 | 3083 | (The UNICODECHARNOCRLF definition is based upon the Char definition 3084 | in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3085 | Return and Linefeed characters.) 3086 | 3087 | 3088 | ## "client_id" Syntax 3089 | 3090 | The "client_id" element is defined in Section 2.3.1: 3091 | 3092 | client-id = *VSCHAR 3093 | 3094 | 3095 | ## "client_secret" Syntax 3096 | 3097 | The "client_secret" element is defined in Section 2.3.1: 3098 | 3099 | client-secret = *VSCHAR 3100 | 3101 | 3102 | ## "response_type" Syntax 3103 | 3104 | The "response_type" element is defined in Sections 3.1.1 and 8.4: 3105 | 3106 | response-type = response-name *( SP response-name ) 3107 | response-name = 1*response-char 3108 | response-char = "_" / DIGIT / ALPHA 3109 | 3110 | ## "scope" Syntax 3111 | 3112 | The "scope" element is defined in Section 3.3: 3113 | 3114 | scope = scope-token *( SP scope-token ) 3115 | scope-token = 1*NQCHAR 3116 | 3117 | ## "state" Syntax 3118 | 3119 | The "state" element is defined in Sections 4.1.1, 4.1.2, 4.1.2.1, 3120 | 4.2.1, 4.2.2, and 4.2.2.1: 3121 | 3122 | state = 1*VSCHAR 3123 | 3124 | ## "redirect_uri" Syntax 3125 | 3126 | The "redirect_uri" element is defined in Sections 4.1.1, 4.1.3, 3127 | and 4.2.1: 3128 | 3129 | redirect-uri = URI-reference 3130 | 3131 | ## "error" Syntax 3132 | 3133 | The "error" element is defined in Sections 4.1.2.1, 4.2.2.1, 5.2, 3134 | 7.2, and 8.5: 3135 | 3136 | error = 1*NQSCHAR 3137 | 3138 | ## "error_description" Syntax 3139 | 3140 | The "error_description" element is defined in Sections 4.1.2.1, 3141 | 4.2.2.1, 5.2, and 7.2: 3142 | 3143 | error-description = 1*NQSCHAR 3144 | 3145 | ## "error_uri" Syntax 3146 | 3147 | The "error_uri" element is defined in Sections 4.1.2.1, 4.2.2.1, 5.2, 3148 | and 7.2: 3149 | 3150 | error-uri = URI-reference 3151 | 3152 | ## "grant_type" Syntax 3153 | 3154 | The "grant_type" element is defined in Sections 4.1.3, 4.3.2, 4.4.2, 3155 | 4.5, and 6: 3156 | 3157 | grant-type = grant-name / URI-reference 3158 | grant-name = 1*name-char 3159 | name-char = "-" / "." / "_" / DIGIT / ALPHA 3160 | 3161 | ## "code" Syntax 3162 | 3163 | The "code" element is defined in Section 4.1.3: 3164 | 3165 | code = 1*VSCHAR 3166 | 3167 | ## "access_token" Syntax 3168 | 3169 | The "access_token" element is defined in Sections 4.2.2 and 5.1: 3170 | 3171 | access-token = 1*VSCHAR 3172 | 3173 | ## "token_type" Syntax 3174 | 3175 | The "token_type" element is defined in Sections 4.2.2, 5.1, and 8.1: 3176 | 3177 | token-type = type-name / URI-reference 3178 | type-name = 1*name-char 3179 | name-char = "-" / "." / "_" / DIGIT / ALPHA 3180 | 3181 | ## "expires_in" Syntax 3182 | 3183 | The "expires_in" element is defined in Sections 4.2.2 and 5.1: 3184 | 3185 | expires-in = 1*DIGIT 3186 | 3187 | ## "username" Syntax 3188 | 3189 | The "username" element is defined in Section 4.3.2: 3190 | 3191 | username = *UNICODECHARNOCRLF 3192 | 3193 | ## "password" Syntax 3194 | 3195 | The "password" element is defined in Section 4.3.2: 3196 | 3197 | password = *UNICODECHARNOCRLF 3198 | 3199 | ## "refresh_token" Syntax 3200 | 3201 | The "refresh_token" element is defined in Sections 5.1 and 6: 3202 | 3203 | refresh-token = 1*VSCHAR 3204 | 3205 | ## Endpoint Parameter Syntax 3206 | 3207 | The syntax for new endpoint parameters is defined in Section 8.2: 3208 | 3209 | param-name = 1*name-char 3210 | name-char = "-" / "." / "_" / DIGIT / ALPHA 3211 | 3212 | 3213 | 3214 | # Use of application/x-www-form-urlencoded Media Type 3215 | 3216 | At the time of publication of this specification, the 3217 | "application/x-www-form-urlencoded" media type was defined in 3218 | Section 17.13.4 of [W3C.REC-html401-19991224] but not registered in 3219 | the IANA MIME Media Types registry 3220 | (). Furthermore, that 3221 | definition is incomplete, as it does not consider non-US-ASCII 3222 | characters. 3223 | 3224 | To address this shortcoming when generating payloads using this media 3225 | type, names and values MUST be encoded using the UTF-8 character 3226 | encoding scheme [RFC3629] first; the resulting octet sequence then 3227 | needs to be further encoded using the escaping rules defined in 3228 | [W3C.REC-html401-19991224]. 3229 | 3230 | When parsing data from a payload using this media type, the names and 3231 | values resulting from reversing the name/value encoding consequently 3232 | need to be treated as octet sequences, to be decoded using the UTF-8 3233 | character encoding scheme. 3234 | 3235 | For example, the value consisting of the six Unicode code points 3236 | (1) U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), 3237 | (3) U+0026 (AMPERSAND), (4) U+002B (PLUS SIGN), 3238 | (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO SIGN) would be encoded 3239 | into the octet sequence below (using hexadecimal notation): 3240 | 3241 | 20 25 26 2B C2 A3 E2 82 AC 3242 | 3243 | and then represented in the payload as: 3244 | 3245 | +%25%26%2B%C2%A3%E2%82%AC 3246 | 3247 | 3248 | # Acknowledgements 3249 | 3250 | The initial OAuth 2.0 protocol specification was edited by David 3251 | Recordon, based on two previous publications: the OAuth 1.0 community 3252 | specification [RFC5849], and OAuth WRAP (OAuth Web Resource 3253 | Authorization Profiles). Eran Hammer then edited many 3254 | of the intermediate drafts that evolved into this RFC. The Security 3255 | Considerations section was drafted by Torsten Lodderstedt, Mark 3256 | McGloin, Phil Hunt, Anthony Nadalin, and John Bradley. The section 3257 | on use of the "application/x-www-form-urlencoded" media type was 3258 | drafted by Julian Reschke. The ABNF section was drafted by Michael 3259 | B. Jones. 3260 | 3261 | The OAuth 1.0 community specification was edited by Eran Hammer and 3262 | authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 3263 | Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 3264 | Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris 3265 | Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, 3266 | Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. 3267 | 3268 | The OAuth WRAP specification was edited by Dick Hardt and authored by 3269 | Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom. 3270 | 3271 | This specification is the work of the OAuth Working Group, which 3272 | includes dozens of active and dedicated participants. In particular, 3273 | the following individuals contributed ideas, feedback, and wording 3274 | that shaped and formed the final specification: 3275 | 3276 | Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden 3277 | Bell, John Bradley, Marcos Caceres, Brian Campbell, Scott Cantor, 3278 | Blaine Cook, Roger Crew, Leah Culver, Bill de hOra, Andre DeMarre, 3279 | Brian Eaton, Wesley Eddy, Wolter Eldering, Brian Ellin, Igor 3280 | Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan Gilbert, 3281 | Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Eran Hammer, 3282 | Dick Hardt, Justin Hart, Craig Heath, Phil Hunt, Michael B. Jones, 3283 | Terry Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le Hara, 3284 | Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, Paul 3285 | Madsen, Alastair Mair, Eve Maler, James Manger, Mark McGloin, 3286 | Laurence Miao, William Mills, Chuck Mortimore, Anthony Nadalin, 3287 | Julian Reschke, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob 3288 | Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, 3289 | Justin Smith, Haibin Song, Niv Steingarten, Christian Stuebner, 3290 | Jeremy Suriel, Paul Tarjan, Christopher Thomas, Henry S. Thompson, 3291 | Allen Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar 3292 | Woodward. 3293 | 3294 | 3295 | 3296 | 3297 | --- fluff 3298 | --------------------------------------------------------------------------------