You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Resource Owner Password Credentials Grant](https://www.rfc-editor.org/rfc/rfc6749#section-1.3.3); however, read the [security concerns](docs/ropc.md) before using this flow
Copy file name to clipboardExpand all lines: docs/index.md
+21-16Lines changed: 21 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -15,18 +15,25 @@ with you use to use the library:
15
15
The remainder of this document will primarily focus on the
16
16
[UserManager](classes/UserManager.html).
17
17
18
-
## UserManager
19
18
20
-
### Configuration
19
+
# Principle of function
20
+
To understand how to use this library see here:
21
+
-[Authorization Code Grant with Proof Key for Code Exchange (PKCE)](https://github.com/authts/oidc-client-ts/blob/main/docs/protocols/authorization-code-grant-with-pkce.md)
The [User](classes/User.html) type is returned from the [UserManager](classes/UserManager.html)'s [getUser](classes/UserManager.html#getUser) API.
76
81
77
82
78
-
##Logging
83
+
# Logging
79
84
The oidc-client-ts library supports logging. You can set a logger by assigning `Oidc.Log.logger` to anything that supports a `info`, `warn`, and `error` methods that accept a params array. By default, no logger is configured.
80
85
81
86
The `console` object in the browser supports these, so a common way to easily
@@ -89,7 +94,7 @@ Also, logging has levels so you can control the verbosity by calling
89
94
`Oidc.Log.setLevel()` with one of `Oidc.Log.NONE`, `Oidc.Log.ERROR`,
90
95
`Oidc.Log.WARN`, or `Oidc.Log.INFO`. The default is `Oidc.Log.INFO`.
91
96
92
-
##Provider specific settings
97
+
# Provider specific settings
93
98
Additional provider specific settings may be needed for a flawless operation:
94
99
95
100
**Amazon Cognito**
@@ -104,7 +109,7 @@ const mgr = new UserManager({
104
109
```
105
110
106
111
107
-
##Custom state in user object
112
+
# Custom state in user object
108
113
In case you would like to add additional data into the [User](classes/User.html) object, you can do so during the initial sign-in request.
109
114
110
115
```javascript
@@ -117,7 +122,7 @@ After successful sign-in the custom state is part of the [User](classes/User.htm
117
122
118
123
This custom state should not be confused with the URL state parameter. The latter is internally used to match against the authentication state object to finish the authentication process.
119
124
120
-
##Custom state in request url
125
+
# Custom state in request url
121
126
If you would like to encode a custom state string in the sign in request url, you can do so with the `url_state` parameter. You may want to do this in order to pass user state to the authentication server and/or a proxy and return that state as part of the response.
The `url_state` will be appended to the opaque, unique value created by the library when sending the request. It should survive the round trip to your authentication server and will be part of the [User](classes/User.html#url_state) object as `url_state`.
The API is largely backwards-compatible. The merge claims behavior has been improved.
3
+
The API is largely backwards-compatible.
4
+
5
+
The "crypto-js" software library has been removed; the native crypto/crypto.subtle module built into the browser is instead used. All modern browser are expected to support it. If need to support older browsers stay with v2.4!
# Authorization Code Grant with Proof Key for Code Exchange (PKCE)
2
+
3
+
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).
4
+
5
+
6
+
## Principle of function
7
+
```mermaid
8
+
---
9
+
title: Authorization Code Grant with Proof Key for Code Exchange (PKCE)
10
+
---
11
+
sequenceDiagram
12
+
actor User
13
+
User->>App: Click sign-in link (1)
14
+
15
+
activate App
16
+
Note left of App: Generate code_verifier and<br/>code_challenge
Note right of Identity Provider: Validate authorization code &<br/>code_verifier
27
+
Identity Provider->>App: Access token and ID token (4)
28
+
deactivate App
29
+
30
+
App->>Your API: Request protected data with access token (5)
31
+
```
32
+
33
+
1. The user clicks sign-in within the application.
34
+
2.`signinRedirect()` or `signinPopup()` must be used to start the flow.
35
+
3. The identity provider authenticates the user and stores the code_challenge and redirects the user back to the application with an authorization code.
36
+
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.
37
+
5. The access token is now accessible via `getUser()?.access_token` and inserted into the requests to your protected API.
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.
4
+
5
+
**NOTE**<br/>
6
+
It implies some security risks, so you should only use it after a security assessment.
7
+
8
+
9
+
## Security concerns
10
+
This flow can only be used for applications, which can protected the client secret:
11
+
-**Native app**: Can not securely store the client secret, as its possible to decompile the application.
12
+
-**Single-page app**: Can not securely store the client secret, as the full code is exposed in the users browser
13
+
14
+
In that scenarios [Authorization Code Grant with Proof Key for Code Exchange (PKCE)](authorization-code-flow-with-pkce.md) must be used.
Note right of Identity Provider: Validate authorization code &<br/>client secret
36
+
Identity Provider->>App: Access token and ID token (4)
37
+
deactivate App
38
+
39
+
App->>Your API: Request protected data with access token (5)
40
+
```
41
+
42
+
1. The user clicks sign-in within the application.
43
+
2.`signinRedirect()` or `signinPopup()` must be used to start the flow.
44
+
3. The identity provider authenticates the user and stores the code_challenge and redirects the user back to the application with an authorization code.
45
+
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.
46
+
5. The access token is now accessible via `getUser()?.access_token` and inserted into the requests to your protected API.
## Security concerns on Resource Owner Password Credentials flow
1
+
#Resource Owner Password Credentials (ROPC) Grant
2
2
3
-
This OAuth 2.0 flow implies some security risks, so you should only use it after a security assesment.
3
+
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)).
4
4
5
-
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:
5
+
**NOTE**<br/>
6
+
It implies some security risks, so you should only use it after a security assessment.
7
+
8
+
9
+
## Security concerns
10
+
11
+
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:
6
12
7
13
* 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.
8
14
9
-
* 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.
15
+
* 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.
10
16
11
17
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.
12
18
13
-
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.
19
+
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.
20
+
21
+
22
+
## Principle of function
23
+
```mermaid
24
+
---
25
+
title: Resource Owner Password Credentials (ROPC) Grant
26
+
---
27
+
sequenceDiagram
28
+
actor User
29
+
User->>App: Click sign-in link (1)
30
+
31
+
activate App
32
+
App->>Identity Provider: Authenticate with username and password (2)
33
+
Note right of Identity Provider: Validate username &<br/>password
34
+
Identity Provider->>App: Access token and ID token (2)
35
+
deactivate App
36
+
37
+
App->>Your API: Request protected data with access token (3)
38
+
```
39
+
40
+
1. The user clicks sign-in within the application.
41
+
2.`signinResourceOwnerCredentials()` must be used to start the flow.
42
+
3. The access token is now accessible via `getUser()?.access_token` and inserted into the requests to your protected API.
0 commit comments