Federation (OAuth2 / OIDC)

Definition and Default Configuration

Federation as an authentication factor allows users to authenticate via social identity providers (IdPs) such as Google, Facebook, Apple, LinkedIn, Github, and any other OIDC-compliant identity provider (IdP).

An account can enroll multiple federation factors, even of the same type (i.e. multiple Google accounts assigned to the same Quasr account).

The default maximum failed attempts before the factor gets temporarily disabled is 5. The factor will auto-unlock after 300 seconds (5 minutes). The default maximum pending attempts (so the start of the flow) before the factor get temporarily disabled is 5. Both counters reset to 0 on each successful login. After auto-unlock only the pending counter gets reset to 3.

The following IdPs are supported out-of-the-box:

• Google

• Facebook

• Apple

• Github

• LinkedIn

• Slack

as well as an option for any generic

• OpenID Connect provider

Quasr uses the federated identity providers only for authentication purposes and is only interested in the "sub" (user id on federation side) of the ID token or the user profile returned from the userinfo endpoint via IdP access token. Profile information such as name, email (in case it cannot be oppressed by already minimized scopes in the first place) is being discarded by Quasr.

Quasr now offers the option to capture all identity claims during signup by setting the capture_claims flag to true. This will cause a DATA event to be created with signup which gives access to all ID claims returned from the identity provider.

User Interface (UI) Example

Below is a sample screenshot to give an idea of a potential login / registration page offering Federation options. On a login or registration page, the federated IdP is often represented by an icon.

Federated login options on the Hosted Login Page (Quasr)

Factor Enrollment

This step is done by the end-users, usually at initial signup to a web service or to add an additional authentication method (factor) to their existing one as additional option.

To enroll an OAuth2/OIDC Federation factor, optionally a label (label parameter) is provided.

Enrolling an OAuth2/OIDC Federation factor (Step 1)

POST https://{tenant_id}.api.quasr.io/factors/signup

Request Body

Name	Type	Description
label	String	Label
id*	String	Factor ID

200: OK Successful signup initiation

{
  "result": "PENDING",
  "feedback": {
    "cause": "ENROLLMENT_PENDING",
    "enrollment_id": "<pending enrollment id>",
    "authorization_url": "<authorization url of external idp>",
    "authorization_state": "<authorization state id>",
    "expires_at": "ISO timestamp",
    "regex": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
  }
}

When following the authorization_url at the end of the IDP flow you'll be redirected back to the origin of the API caller. The final callback will look as follows: <origin>?id=<enrollment_id>&input=<authorization_state_id> when successful; in case of a error it looks as follows: <origin>?error=<error>&error_id=<error_id> (the error ID is optional and only returned with an INTERNAL_ERROR).

Enrolling an OAuth2/OIDC Federation factor (Step 2)

POST https://{tenant_id}.api.quasr.io/factors/signup

Request Body

Name	Type	Description
id*	String	Enrollment ID (feedback.id value from response in Step 1)
input*	String	Authorization state ID (feedback.authorization_state from response in Step 1; also returned as query param in the callback)

200: OK Successful signup

{
    "result": "SUCCESS",
    "feedback": {
      "cause": "",
      "enrollment_id": "<enrollment id>",
    },
    "account_id": "<account_id>",
    "session_token": "<session_token>",
    "session_score": "<session_score>",
    "session_exp": "<session_exp>" // epoch in seconds (not ms)
}

Factor Validation

This step is done by the end-users, in order to authenticate themselves (login).

To login with a OAuth2/OIDC Federation factor.

Validating an OAuth2/OIDC Federation factor

POST https://{tenant_id}.api.quasr.io/factors/login

Request Body

Name	Type	Description
id*	String	Factor or Enrollment ID

200: OK Successful login

{
  "result": "PENDING",
  "feedback": {
    "cause": "ENROLLMENT_PENDING",
    "enrollment_id": "<pending enrollment id>",
    "authorization_url": "<authorization url of external idp>",
    "authorization_state": "<authorization state id>",
    "expires_at": "ISO timestamp",
    "regex": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
  }
}

Factor Create & Configuration

This step is done by the Quasr customer's Tenant Administrator, to provide this factor as an authentication option to their end-users.

An OAuth2/OIDC Factor can be created via Tenant Administration UI or Admin API.

If you choose a pre-configured social IdP (as listed above), only a few fields require configuration, the rest is already defaulting to a fixed template per IdP that Quasr provides. If you need maximum flexibility, you can always configure a "Generic OIDC" factor with the options shown in the second table.

The pre-configured social IdPs (Google, Facebook, etc.) allows for the following parameters and config options:

Parameter	Value Options	Default	Required
subtype	"oauth2:google" | "oauth2:facebook" | "oauth2:apple" | "oauth2:linkedin" | "oauth2:github" | "oauth2:slack" | "oauth2:quasr"
label	<string>	"Google" | "Facebook" | "Apple" | "LinkedIn" | "GitHub" | "Slack" | "Quasr"
status	"ENABLED" | "DISABLED"	"DISABLED"
score	<positive int>	1
config.unique	true | false	true
config.client_id	<string>
config.client_secret	<string>
config.capture_claims	true | false	false
config.capture_tokens	true | false	false

The OAuth2/OIDC Factor allows for the following parameters and config options:

Parameter	Value Options	Default	Required
subtype	"oauth2:oidc"
label	<string>	"OpenID Connect"
status	"ENABLED" | "DISABLED"	"DISABLED"
score	<positive int>	1
config. unique	true | false	true
config.case_sensitive	true | false	true
config. authorization_endpoint	<url>
config.userinfo_endpoint	<url>
config. client_id	<string>
config. client_secret	<string>
config. content_type	"application/json" | "application/x-www-form-urlencoded"	"application/json"
config.issuer	<url>
config.jwks_uri	<url>
config. response_mode	"query" | "form_post" | "NONE"	"NONE"
config. response_type	"code" | "id_token" | "code id_token" | "id_token code" | "NONE"	"NONE"
config.scope	<string>	"openid"
config.nonce	true | false	true
config.code_challenge_method	"S256" | "plain" | "NONE"	"NONE"
config. token_endpoint	<url>
config. client_authentication	"NONE" | "CLIENT_SECRET" | "PRIVATE_KEY_JWT"	"NONE"
config.signed_request	true | false	false
config.signed_request_issuer	"CLIENT_ID" | "DEFAULT"	"DEFAULT"
config.client_assertion_issuer	"CLIENT_ID" | "DEFAULT"	"DEFAULT"
config.capture_claims	true | false	false
config.capture_tokens	true | false	false

The capture_tokens feature is currently still experimental so please refrain from using for production setups. It allows you to capture all of the tokens returned from the Identity Provider such as ID token, access token and refresh token. Currently in the flow not all of the tokens are requested and scope can not be set for standard IDPs.

The following example creates an Google OAuth2 factor labelled "MySocial" with a score of 5.

The Quasr Access Token used in the Authorization header in the examples below must contain the scope https://api.quasr.io/scopes/admin in order to be authorized. See API Authorization

GraphQL Example

// GraphQL Query (Sample)
mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}

// GraphQL Variables (Sample)
{
  "input": {
    "subtype": "oauth2:google",
    "label": "MySocial",
    "status": "ENABLED",
    "config": {
        "client_id": "GoogleOAuthClientId",
        "client_secret": "GoogleOAuthClientSecret"
    },
    "score": 5
  }
}

// Response (Sample)
{
    "data": {
        "createFactor": {
            "id": "678c0054-d57e-4e09-9e54-ef8deb4ddd72"
        }
    }
}

Node.js Example

var axios = require('axios');
var data = JSON.stringify({
  query: `mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}`,
  variables: {
    "input": {
      "subtype": "oauth2:oidc",
      "label": "MySocial",
      "status": "ENABLED",
      "config": {
        "client_id": "GoogleOAuthClientId",
        "client_secret": "GoogleOAuthClientSecret"
      },      
      "score": 5
    }
  }
});

var config = {
  method: 'post',
  url: `https://{tenant_id}.api.quasr.io/graphql`,
  headers: { 
    'Authorization': 'Bearer {access_token}', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});