npm package: @prescrire/auth
Description: Authentication unit
Author: Alexander Nedosekin
Latest version: 6.0.3

# How to use it

# Authorization code flow

1. PKCE must be enabled on the auth server implementing authorization code flow.
2. `offline_access` must present in `scope` in order to get `refresh_token`
3. If the server uses basic authorization for token exchange, do not forget to use `client_authentication:"client_secret_basic"` in conjunction with `client_secret:YOUR_CLIENT_SECRET` 

# Reference

## Implicit flow

## Code flow

Remember to add `offline_access` to scope, `response_type` to `"code"`, `client_authentication` to `"client_secret_basic"`,
`client_secret` to appropriate value

# Brief description of different flows

[Source](https://stackoverflow.com/a/33443593)

First, I'll answer the question at the risk of stating the obvious: The ID token cannot be trusted and its content must be ignored if the current time is greater than the expired time. The questioner's answer states that the after the initial authentication of the user, the ID Token isn't used again. However, since the ID Token is signed by the identity provider, it certainly could be useful at any time to give a way of reliably determining who the user is to other services that an app might be using. Using a simple user ID or email address isn't reliable because it can be easily spoofed (anyone can send an email address or user ID), but since an OIDC ID Token is signed by the Authorization server (which also usually has the benefit of being a third party) it cannot be spoofed and is a much more reliable authentication mechanism.

For example, a mobile app may want to be able to tell a backend service who the user is that is using the app and it may need to do so after the brief period following the initial authentication, at which time the ID Token is expired, and thus, cannot be used to reliably authenticate the user.

Therefore, just like the access token (used for authorization - specifying what permissions the user has) can be refreshed, can you refresh the ID Token (used for authentication - specifying who the user is)? According to the OIDC specification, the answer isn't obvious. In OIDC/OAuth there are three "flows" for getting tokens, The Authorization Code flow, the Implicit flow, and the Hybrid flow (which I'll skip below because it's a variant of the other two).

For the [implicit flow in OIDC/OAuth](http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthRequest) you request the ID Token at the authorization endpoint by redirecting the user in the browser to the Authorization endpoint and including id_token as the value of the response_type request parameter. An [Implicit Flow Successful Authentication Response](http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthResponse) is REQUIRED to include the id_token.

For the [Authentication Code flow](http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth), the client specifies code as the value of the response_type request parameter when redirecting the user to the authorization endpoint. A successful response includes an authorization code. The client client makes a request to the token endpoint with the authorization code and, according to [OIDC Core Section 3.1.3.3 Successful Token Response](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) the response MUST include an ID Token.

So for either flow, that's how you initially get the ID Token, but how do you refresh it? [OIDC Section 12: Using Refresh Tokens](http://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens) has the following statement about the Refresh Token Response:
```
Upon successful validation of the Refresh Token, the response body is the Token Response of Section 3.1.3.3 except that it might not contain an id_token.
```

It might not contain an ID Token and since there is no way specified to force it to include the ID token, you must assume that the response will not contain the ID Token. So technically there is no specified way to "refresh" an ID Token using a refresh token. Therefore, the only way to get a new ID Token is to re-authorize/authenticate the user by redirecting the user to the authorization endpoint and starting the implicit flow or authentication code flow as described above. The OIDC specification does add a prompt request parameter to the [authorization request](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) so the client can request that the authorization server not prompt the user with any UI, but the the redirect still has to happen.

# Special addition to Authentication code: PKCE (proof key for code exchange)

[Source](https://brockallen.com/2019/01/03/the-state-of-the-implicit-flow-in-oauth2/)

# Future 

Look at [AppAuth-JS](https://github.com/openid/AppAuth-JS)