@jmondi/oauth2-server

Typescript OAuth2 Server

:construction_worker: This project is under development :construction:

Installing

npm install @jmondi/oauth2-server

@TODO

• fix: failure responses
• tests: better (some) unit tests
• feat: token introspection
• feat: refresh grant
• chore: documentation

Grants

• client_credentials - when applications request an access token to access their own resources, not on behalf of a user.
• authorization_code - a temporary code that the client will exchange for an access token. The user authorizes the application, they are redirected back to the application with a temporary code in the URL. The application exchanges that code for the access token.
• refresh_token

Which Grant?

Deciding which grant to use depends on the type of client the end user will be using.

+-------+
| Start |
+-------+
    V
    |
    |
+---------------------+                +--------------------------+
| Access token owner? |>---Machine---->| Client Credentials Grant |
+---------------------+                +--------------------------+
    V
    |
    |
   User
    |
    |                                 +---------------------------+
    |>-----------Server App---------->| Auth Code Grant with PKCE |
    |                                 +---------------------------+
    |
    |                                 +---------------------------+
    |>-------Browser Based App------->| Auth Code Grant with PKCE |
    |                                 +---------------------------+
    |
    |                                 +---------------------------+
    |>-------Native Mobile App------->| Auth Code Grant with PKCE |
                                      +---------------------------+

Client Credentials Grant

For machine to machine communications

POST /token HTTP/1.1
Host: example.com
 
grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx 

Token Response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
 
{
  "access_token":"f",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
  "scope":"create"
}

Authorization Code Grant with PKCE

read this

• response_type=code – indicates that your server expects to receive an authorization code
• client_id= – The client ID you received when you first created the application
• redirect_uri= – Indicates the URL to return the user to after authorization is complete, such as org.example.app://redirect
• state=1234zyx – A random string generated by your application, which you’ll verify later
• code_challenge=XXXXXXXXX – The code challenge generated as previously described
• code_challenge_method=S256 – Either plain or S256, depending on whether the challenge is the plain verifier string or the SHA256 hash of the string. If this parameter is omitted, the server will assume plain.

const code_verifier = base64urlencode(crypto.randomBytes(40));
const code_challenge = base64urlencode(crypto.createHash("sha256").update(codeVerifier).digest("hex"));

A complete authorization request will include the following parameters

GET /authorize HTTP/1.1
Host: example.com
 
id=123
&response_type=code
&client_id=xxxxxxx
&redirect_uri=http://localhost
&scope=xxxx
&state=xxxx
&code_challenge=xxxx
&code_challenge_method=s256

A complete access token request will include the following parameters:

POST /token HTTP/1.1
Host: example.com
 
grant_type=authorization_code
&code=xxxxxxxxx
&redirect_uri=xxxxxxxxxx
&client_id=xxxxxxxxxx
&code_verifier=xxxxxxxxxx

Refresh Token Grant

A complete refresh token request will include the following parameters:

POST /token HTTP/1.1
Host: example.com
Authorization: Basic Y4NmE4MzFhZGFkNzU2YWRhN
 
grant_type=refresh_token
&refresh_token=xxxxxxxxx
&client_id=xxxxxxxxx
&client_secret=only-required-if-client-has-secret
&scope=xxxxxxxxxx

Token Introspection Endpoint

Request

POST /token_info HTTP/1.1
Host: example.com
Authorization: Basic Y4NmE4MzFhZGFkNzU2YWRhN
 
token=MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3

Response

HTTP/1.1 200 OK
Host: example.com
Content-Type: application/json; charset=utf-8
 
{
  "active": true,
  "scope": "read write email",
  "client_id": "J8NFmU4tJVgDxKaJFmXTWvaHO",
  "username": "aaronpk",
  "exp": 1437275311
}

Sources

https://tools.ietf.org/html/rfc6749#section-4.4

https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/

https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/

https://tools.ietf.org/html/rfc6749#section-4.1

https://tools.ietf.org/html/rfc7636

https://www.oauth.com/oauth2-servers/pkce/

https://www.oauth.com/oauth2-servers/pkce/authorization-request/