OAuth 2.0 Client Login Flow

Concepts

OAuth 2.0 is the industry-standard protocol for authorization. Saga supports OAuth2.0s provider to login into web application that require Saga user authorization such as the Saga admin. The OAuth settings have to be contained in a global property called oauth_providers. Each provider has to have a unique name and the standard setting as below.

{
  "provider1": {
    "clientId": "the client id",
    "clientSecret": "the client id",
    "authorizationUri": "https://authorization url",
    "accessTokenUri": "https://authorization token_uri",
    "scopes": [
      "provider specific scope name for email",
      "provider specific scope name for full name"
    ]
  },
  "provider2": {
    "clientId": "the client id",
    "clientSecret": "the client id",
    "authorizationUri": "https://authorization url",
    "accessTokenUri": "https://authorization token_uri",
    "scopes": [
      "provider specific scope name for email",
      "provider specific scope name for full name"
    ]
  }
}

At the provider level you need to specify the absolute saga authorization redirect URI that is being called by the OAuth service provider once the authorization flow is finished. The path is /users/oauth/:name/add_user, the full URL needs to contain protocol and saga host name.

HTTP API

It requires the anonymous role to contain {path: "/users/oauth", action: "*", allow: true} for the oauth flow.

GET /users/oauth/

Returns an array providing the names of the OAuth providers set in the global property oauth_providers.

Example:

[
  "provider1",
  "provider2"
]

GET /users/oauth/:name

Start the OAuth flow. Requires the following query parameters:

• saga_host the saga api hostname with the protocol like https://application.hexagram.saga.hexagram.io, the saga API itself is not aware of it's own public hostname
• client_url the client url to call in the target app to after the flow is finished, the url needs to be absolute and end with a slash. The user payload will be appended as URI encoded JSON path element after slash in the following structure.

Successful Authorization Payload:

{
  "status_code": 200,
  "body": {
    "email": "foo@bar.com",
    "username": "username",
    "accessToken": "eyJ562eXAiOiJKV1QJhbGciOiJIUzI1NiJ9eyJ1c2VybmFtZSI6InRheWxvcmhlbGxhbSIsImVGlyZXMiOiIyMDE1LTA5LTA4VDIwOjM0LjIzMloifQ.LeC0U0w2nAc_Ld0d3j_5wVBsq",
    "refreshToken": "eyJ0eXAiOiweweJKV1QiLCJhbGciOiJIUzI1NiJ9eyJ0eXBlIjoicmVmcmVzaCIsIl9pZCI6IjVjYmUyZY1YmMwMjdhMDdjOTg2MTUxYSIsInVzZXJuYW1lIjoiZm9vYmFyIiwiZGF0ZSI6IjIwMTktMDQtMjJUjE6MDg6NTMuMDU3WiJ9.xoH59FuOL4WmtVeHxuPunoerlNVai9mmhVnaRJyByYY"  
  }
}

Unsuccessful Authorization Payload:

{
  "status_code": 404,
  "body": "User with foo@bar.com not known"
}

POST /users/oauth/:name/add_user

This is OAuth2.0 redirect URL that is called by the OAuth provider, a Saga app will never have to use that. The resource calls the client_url given in the GET /users/oauth/:name call described above with payload append as URI path segmented as described above.