---
# System prepended metadata

title: OAuth2

---

# OAuth2

- ## General Description
    - A user has access to a resource and wants a third-party to have the same access
    - Flow
        - is the protocol by which parties communicate. There are four of them
    - At the end of the flow client obtains access and refresh tokens
- ## Parties:
    - ### Resource Owner
        - The user who is typically a real person.
    - ### Resource Server
        - The resource, that would usually be an API
    - ### Client
        - The third party could be a mobile app, a website or another system that needs to access the resource
    - ### Authorization Server
        - OAuth 2 server
- ## Authorization Code Flow
    - Examples are Google login, Facebook login
    - The most secure and the longest of the four flows
    - The Authorization Code is one time password to request access and refresh tokens
    - ## Setup:
        - Register new `client_id` with the "Authorization Server"
            - It is optionally possible to register second `client_id` to use be back-end specifically during "Getting the access token (and optionally a refresh token)"
        - Register `redirect_uri` that will be used. Can be single value or a list of values
        - Register `client_secret` used as an additional security measure to ensure that we don't issue tokens to anyone who knows authorization code, but only to the client who know the code and the secret.
    - ## Flow Steps:
        1. ### Requesting authorization code
            1. The browser makes a GET request to "Authorization Server"
                1. `https://oauthserver/authorize?client_id=my-client-id&response_type=code&scope=rs-specific-scope&redirect_uri=https://my-application.com/callback`
                    1. `client_id`
                        1. The ID registered with the "Authorization Server" when the client was set up
                    2. `response_type=code`
                        1. Signals the "Authorization Server" which protocol/flow we want to use
                    3. `scope=rs-specific-scope`
                        1. defines what set of data from the "Resource Server" we want
                        2. Scope names are specific to the "Resource Server"
                    4. `redirect_uri`
                        1. Where the browser should be redirected after the authorization code is granted.
                        2. It is usually a server endpoint that knows additional requests access and refresh tokens and redirects back to its own UI.
                        3. Starting point of "Getting the grant code the browser"
        2. ### Authenticating the user
            1. Up to the implementation of the service to decide which method to use to authenticate the user.
        3. ### Getting the grant code the browser
            1. The authorization code is transmitted as a GET parameter with the name `code` in a GET request to specified `redirect_uri`
        4. ### Getting the access token (and optionally a refresh token)
            1. Back-end routine triggered by request to `redirect_uri` make a HTTP Request to "Authorization Server"
            2. `https://oauthserver/token?client_id=my-backend-client-id&client_secret=123&grant_type=authorization_code&code=<the authorization code>`
                1. `client_id`
                    1. Can be the same used during initial step
                    2. It is possible to configure to use different client_id during this step for additional security
                2. `client_secret`
                    1. A secret known only by the client and the "Authorization Server"
- ## Using tokens
    - Access token is part of each request to the "Resource Server" and placed as header `Authorization: Bearer <access-token>`
    - When the "Resource Server" receives the token it needs to be validated, this is done by the introspection process.
    - Introspection is basically the "Resource Server" asks the "Authorization Server" whether the token is valid or not.
    - OAuth2 does not require the token to be JWT, so in classic version, in order to get info about the user introspection needs to be done
    - Refresh token can be used to retrieve new pair of access and refresh tokens by making request to the "Authorization Server" at `/token`
    - It is possible to revoke the token by making revoke request to the "Authorization Server"
- ## OpenID Connect
    - OpenID JWT tokens are enabled by requesting access to the scope `openid`
    - Introspect is not required when using JWT and OpenID Connect
    - Each OpenID Connect server must answer on the endpoint `/.well-known/openid-configuration`
        - Example https://accounts.google.com/.well-known/openid-configuration
