-
Notifications
You must be signed in to change notification settings - Fork 219
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1250 from authts/improve-doc
improve documentation
- Loading branch information
Showing
15 changed files
with
322 additions
and
61 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| # Authorization Code Grant with Proof Key for Code Exchange (PKCE) | ||
|
|
||
| The authorization code protocol is part of OAuth 2.0 (defined in [OAuth 2.0 RFC 7636](https://tools.ietf.org/html/rfc7636)). It involves the exchange of an authorization code for a token. This is the recommend authorization code flow in the [OAuth 2.1 draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-10). | ||
|
|
||
|
|
||
| ## Principle of function | ||
| ```mermaid | ||
| --- | ||
| title: Authorization Code Grant with Proof Key for Code Exchange (PKCE) | ||
| --- | ||
| sequenceDiagram | ||
| actor User | ||
| User->>App: Click sign-in link (1) | ||
| activate App | ||
| Note left of App: Generate code_verifier and<br/>code_challenge | ||
| App->>Identity Provider: Authorization code request & code_challenge (2) | ||
| deactivate App | ||
| Identity Provider-->>User: Redirect to login/authorization prompt (3) | ||
| User-->>Identity Provider: Authenticate (3) | ||
| Identity Provider->>App: Authorization code (3) | ||
| activate App | ||
| App->>Identity Provider: Authorization code & code verifier (4) | ||
| Note right of Identity Provider: Validate authorization code &<br/>code_verifier | ||
| Identity Provider->>App: Access token and ID token (4) | ||
| deactivate App | ||
| App->>Your API: Request protected data with access token (5) | ||
| ``` | ||
|
|
||
| 1. The user clicks sign-in within the application. | ||
| 2. `signinRedirect()` or `signinPopup()` must be used to start the flow. | ||
| 3. The identity provider authenticates the user and stores the code_challenge and redirects the user back to the application with an authorization code. | ||
| 4. `signinCallback()` handles this callback by sending this authorization code and code_verifier to the identity provider and receiving in return the access token and ID token. | ||
| 5. The access token is now accessible via `getUser()?.access_token` and inserted into the requests to your protected API. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # Authorization Code Grant | ||
|
|
||
| The authorization code protocol is part of OAuth 2.0 defined in ([OAuth 2.0 RFC 6749, section 4.1](https://tools.ietf.org/html/rfc6749#section-4.1)). It involves the exchange of an authorization code for a token. | ||
|
|
||
| **NOTE**<br/> | ||
| It implies some security risks, so you should only use it after a security assessment. | ||
|
|
||
|
|
||
| ## Security concerns | ||
| This flow can only be used for applications, which can protected the client secret: | ||
| - **Native app**: Can not securely store the client secret, as its possible to decompile the application. | ||
| - **Single-page app**: Can not securely store the client secret, as the full code is exposed in the users browser | ||
|
|
||
| In that scenarios [Authorization Code Grant with Proof Key for Code Exchange (PKCE)](authorization-code-flow-with-pkce.md) must be used. | ||
|
|
||
|
|
||
| ## Principle of function | ||
| ```mermaid | ||
| --- | ||
| title: Authorization Code Grant | ||
| --- | ||
| sequenceDiagram | ||
| actor User | ||
| User->>App: Click sign-in link (1) | ||
| activate App | ||
| App->>Identity Provider: Authorization code request (2) | ||
| deactivate App | ||
| Identity Provider-->>User: Redirect to login/authorization prompt (3) | ||
| User-->>Identity Provider: Authenticate (3) | ||
| Identity Provider->>App: Authorization code (3) | ||
| activate App | ||
| App->>Identity Provider: Authorization code & client secret (4) | ||
| Note right of Identity Provider: Validate authorization code &<br/>client secret | ||
| Identity Provider->>App: Access token and ID token (4) | ||
| deactivate App | ||
| App->>Your API: Request protected data with access token (5) | ||
| ``` | ||
|
|
||
| 1. The user clicks sign-in within the application. | ||
| 2. `signinRedirect()` or `signinPopup()` must be used to start the flow. | ||
| 3. The identity provider authenticates the user and stores the code_challenge and redirects the user back to the application with an authorization code. | ||
| 4. `signinCallback()` handles this callback by sending this authorization code and client secret to the identity provider and receiving in return the access token and ID token. | ||
| 5. The access token is now accessible via `getUser()?.access_token` and inserted into the requests to your protected API. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| # Refresh Token Grant | ||
|
|
||
| This protocol is part of OAuth 2.0 (defined in [OAuth 2.0 RFC 6749, section 1.5](https://tools.ietf.org/html/rfc6749#section-1.5)). | ||
| The refresh token grant is used by clients to exchange a refresh token for an access token when the access token has expired. | ||
|
|
||
|
|
||
| ## Principle of function | ||
| ```mermaid | ||
| --- | ||
| title: Refresh Token Grant | ||
| --- | ||
| sequenceDiagram | ||
| App->>Identity Provider: Request new access token with refresh token (1) | ||
| activate App | ||
| Note right of Identity Provider: Validate refresh token | ||
| Identity Provider->>App: Access token and optional refresh token (1) | ||
| deactivate App | ||
| App->>Your API: Request protected data with refreshed access token (2) | ||
| ``` | ||
|
|
||
| 1. `signinSilent()` must be used to start the flow. | ||
| 2. The refreshed access token is now accessible via `getUser()?.access_token` and inserted into the requests to your protected API. |
39 changes: 34 additions & 5 deletions
39
docs/ropc.md → ...ource-owner-password-credentials-grant.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,42 @@ | ||
| ## Security concerns on Resource Owner Password Credentials flow | ||
| # Resource Owner Password Credentials (ROPC) Grant | ||
|
|
||
| This OAuth 2.0 flow implies some security risks, so you should only use it after a security assesment. | ||
| This protocol is part of OAuth 2.0 (defined in [OAuth 2.0 RFC 6749, section 4.3](https://www.rfc-editor.org/rfc/rfc6749#section-4.3)). | ||
|
|
||
| To start with, this flow is not part of the [Open ID Connect standard](https://openid.net/specs/openid-connect-core-1_0.html). Furthermore, although it is part of [OAuth 2.0](https://www.rfc-editor.org/rfc/rfc6749#section-4.3), it has been removed in the [OAuth 2.1 draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-10), and there are good reasons for this: | ||
| **NOTE**<br/> | ||
| It implies some security risks, so you should only use it after a security assessment. | ||
|
|
||
|
|
||
| ## Security concerns | ||
|
|
||
| To start with, this flow is not part of the [Open ID Connect standard](https://openid.net/specs/openid-connect-core-1_0.html). Furthermore, although it is part of OAuth 2.0, it has been removed in the [OAuth 2.1 draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-10), and there are good reasons for this: | ||
|
|
||
| * When using this flow, the credentials of the user are exposed to the client application. The RFC mandates that ["the client application MUST discard the credentials once the access token has been obtained"](https://www.rfc-editor.org/rfc/rfc6749#section-4.3.1), but there is no technical way for the Identity Provider / Authorization Server to enforce this point. This flow MUST NOT be allowed unless the Client can be enforced to fulfill this requirement through other means (probably because both are under the same security domain, probably the same organization or similar constraints). This point is covered [several](https://www.rfc-editor.org/rfc/rfc6749#section-1.3.3) [times](https://www.rfc-editor.org/rfc/rfc6749#section-4.3) during the RFC and by some IdP implementations, such as [Auth0](https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) or [Keycloak](https://www.keycloak.org/docs/latest/securing_apps/#_resource_owner_password_credentials_flow), but it is sometimes quickly ignored by some developers. | ||
|
|
||
| * Even if the previous point is covered, this flow is increasing the attack surface of the system. For example, if the Client Application is compromised (maybe through an XSS attack, for example), the credentials of the user are exposed, so the attacker have access to other applications accessible by the user. In comparison, for example, in the Authorization Code Flow if the Client Application is equaly compromised only the access token is exposed, usually meaning that only the given application has been compromised. A different way to see this is: usually the IdP/Authorization Server are strongly protected, and the Client Applications are allowed lower levels of security auditing... but when using this flow, if any of them is exposed, the user credentials are exposed; so both of them should be equaly treated regarding security. | ||
| * Even if the previous point is covered, this flow is increasing the attack surface of the system. For example, if the Client Application is compromised (maybe through an XSS attack, for example), the credentials of the user are exposed, so the attacker have access to other applications accessible by the user. In comparison, for example, in the Authorization Code Flow if the Client Application is equally compromised only the access token is exposed, usually meaning that only the given application has been compromised. A different way to see this is: usually the IdP/Authorization Server are strongly protected, and the Client Applications are allowed lower levels of security auditing... but when using this flow, if any of them is exposed, the user credentials are exposed; so both of them should be equally treated regarding security. | ||
|
|
||
| Therefor, this flow MUST NOT be used as a replacement for the Authorization Code flow. This flow can only be seen as a replacement of classic form-based user/password authentication directly in the application. | ||
|
|
||
| Then, why are we adding this support in `oidc-client-ts`? Well... form-based user/password authentication is actually widely used in the industry, and using a standard IdP as authenticator for this architecture has some benefits (other things, such as password expiration, user management backoffice, etc are provided for free by the IdP). So this flow can be an easy help in this scenario. But you MUST NOT use this flow believing that you are having all the security benefits of OpenId Connect or OAuth; you are not. | ||
| Then, why are we adding this support in `oidc-client-ts`? Well... form-based user/password authentication is actually widely used in the industry, and using a standard IdP as authenticator for this architecture has some benefits (other things, such as password expiration, user management back-office, etc are provided for free by the IdP). So this flow can be an easy help in this scenario. But you MUST NOT use this flow believing that you are having all the security benefits of OpenId Connect or OAuth; you are not. | ||
|
|
||
|
|
||
| ## Principle of function | ||
| ```mermaid | ||
| --- | ||
| title: Resource Owner Password Credentials (ROPC) Grant | ||
| --- | ||
| sequenceDiagram | ||
| actor User | ||
| User->>App: Click sign-in link (1) | ||
| activate App | ||
| App->>Identity Provider: Authenticate with username and password (2) | ||
| Note right of Identity Provider: Validate username &<br/>password | ||
| Identity Provider->>App: Access token and ID token (2) | ||
| deactivate App | ||
| App->>Your API: Request protected data with access token (3) | ||
| ``` | ||
|
|
||
| 1. The user clicks sign-in within the application. | ||
| 2. `signinResourceOwnerCredentials()` must be used to start the flow. | ||
| 3. The access token is now accessible via `getUser()?.access_token` and inserted into the requests to your protected API. |
Oops, something went wrong.