Auth Providers

The Auth Providers resource is split into two parts:

This document covers the Extended API funtionality (everything except authentication). For authentication, see Social Login via Auth Providers or Users.


There are 3 broad approaches to managing authentication with AuthRocket:

  1. Hosted logins and signups
  2. authrocket.js
  3. API only

When using full hosted logins, AuthRocket serves as your login and signup page. This is the fastest way to get up and running.

If you want some of the benefits of hosted logins (such as letting us handle everything password-related), but still want a login form on your own page, look at authrocket.js.

Lastly, it’s possible to handle logins and signups completely within your app, using our API directly for all functions. This last approach does not require a LoginRocket Auth Provider (or any Connected Apps).

The first two approaches are configured using the LoginRocket Auth Provider. All approaches will additionally add at least one regular (non-LoginRocket) Auth Provider.

Auth Providers

Standard providers

  • LoginRocket - Hosted logins/signups and/or authrocket.js
  • Password - Authentication using passwords stored in AuthRocket
  • TOTP - Two-factor auth using TOTP

Third-party providers

  • Facebook - Social authentication via Facebook
  • GitHub - Social authentication via GitHub
  • Google - Social authentication via Google+
  • LinkedIn - Social authentication via LinkedIn
  • Slack - Social authentication via Slack
  • Yahoo - Social authentication via Yahoo
  • OAuth2 - Custom or generic OAuth2 provider

LoginRocket

There may be one login_rocket provider. LoginRocket is a special case of Auth Provider as it’s used to enable and configure hosted logins, signups, and verifications, and authrocket.js. It does not provide any new authentication method itself. One or more of the other Auth Providers is required.

The API for the login_rocket provider may be changed in the near future. Any existing configuration will be migrated, but the API may break.

Password

There may be one password provider.

TOTP

There may be one ‘totp’ provider. TOTP enables a two-factor authentication for password-based logins. It does not work without the Password provider.

Social Auth

There may be one provider each for facebook, github, google, linkedin, slack, and yahoo.

Custom OAuth2

There may be multiple oauth2 providers.

Profile field names are the field or key names inside the profile. For example, if a profile returns

{ "user_id" : "123456", "contact" : { "email" : "sam@example.com" } }

then id_field would be "user_id". For nested data structures, use a period. In this example, email_field would be "contact.email".

Use first_name_field and last_name_field if available. If only a full name is available, then use name_field.

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Provider’s ID. Always starts with “ap_”. Example: ap_USkZSudITtpKPqQcyxU84

provider_type string Required
realm_id realm_id Required ID of Realm this Provider belongs to.
request hash

Hash of request attributes to add to Event. See notes.

login_rocket provider:

email_verification none,
request,
require
none See notes below.
enhanced_sso active,
inactive
inactive Seamless SSO. Maintain sessions in LR, enabling seamless re-auths across apps.
login active,
inactive
active Are logins enabled?
name_field string Optional Field name for the full name.
org_name_field require,
ask,
none
none

Is org_name required for signups?

org_permissions string Optional One, or an Array of, permission(s).
password_field confirm,
require
confirm

On signup, is the password required just once or must it be confirmed?

signup active,
inactive
inactive Are signups enabled?
signup_mode user,
user_org,
user_token
user See notes below.
verify active,
inactive
active Is email verification processing enabled?

password provider:

state active,
inactive
active
min_complexity float 2 Minimum password complexity, from 0 (disabled) to 4 (high). See below.
min_length integer 8 Minimum password length.
required_chars lower,
upper,
digit,
special
[] Array of required character types that will be required in a password.

Social providers:

client_id string Required Client ID, provided by the External Provider
client_secret string Required Client Secret, provided by the External Provider
scopes string Optional One, or an array of, scopes to request (must include user's email).

oauth2 provider:

name string Required Name of this provider.
authorization_url url Required First URL, at the external provider, of the process to request authorization to login.
token_url url Required URL where an auth code will be exchanged for an access token.
profile_url url Required URL to retrieve profile info (user id, email, name) about the user.
id_field string Required Field name for the user id inside the profile.
email_field string Required Field name for the email address.
email_verified_field string Optional Field name for the email verified state. Must be in: 1, true, yes.
first_name_field string Optional Field name for the first name.
last_name_field string Optional Field name for the last name.

email_verification

none - Will not initiate email verification for new signups. However, if verification is separately initiated for a user, will act like request.
request - On new signups, will automatically initiate email verification. Logins will be allowed without verification.
require - Same as request, but intercepts logins and asks user to complete verification first. Allows logins for users where email verification has not been initiated (User.email_verification = none).

min_complexity

Uses the zxcvbn algorithm to measure and enforce password complexity. Values are:
4 - High (crackable in years)
3 - Medium (crackable in days)
2 - Low (crackable in hours)
1 - Insecure (crackable in minutes)
0 - Disabled

LoginRocket will automatically display a “Password is…” message if min_complexity is enabled. A value of 1 or 2 will enable displaying these messages to the user while doing minimal enforcement of password quality.

required_chars

required_chars is an array of required character sets. Allowed sets are: lower, upper, digit, and special. By default, this is unset and no special requirements are enforced. Available on Enterprise plans only.

Examples
['lower','upper','digit'] - Passwords must include at least one lowercase, one uppercase, and one numeric character.
['lower','special'] - Passwords must include at least one lowercase and one special character.

While character set requirements are quite common, they are only mildly effective at ensuring users use good passwords. We instead recommend increasing min_length and using a value of 3 or higher for min_complexity.

signup_mode

When LoginRocket is processing a new user signup/registration, it can be configured to respond in several ways:

user - Create a User for each new signup

user_token - Create a Signup Token for each potential new user. The token can later be converted to a User using Create a User

user_org - Create a User, Org, and Membership connecting the two. If org_permissions is present, permissions will be added to the new Membership.

If org_name_field is none or ask (and then isn’t provided), the Org’s name will default to the User’s name. (For new signups via social, ask is equivalent to none.) When it is required, the user will always be prompted for an organization name.

Permissions

MethodPermissions
List, Get read
Create, Update, Delete admin_realm

List auth providers

List all auth providers in the current realm.

Parameters

ParamValueDefault
after provider_id ID of the last auth provider you've seen
max_results integer 100 Range: 1-100
sort id id
direction asc,
desc
asc

Request

Example
GET /v1/auth_providers
$res = $client->authProviders()->all();
AuthRocket::AuthProvider.all realm_id: 'rl_0v76O8itSEiwfhA64ZFvKj'

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "ap_0v9XwmNDu1eHFAnDgYxHgb",
      "provider_type" : "login_rocket",
      "realm_id" : "rl_0v76O8itSEiwfhA64ZFvKj",
      "object" : "auth_provider",
      "login" : "active",
      "name_field" : "none",
      "password_field" : "confirm",
      "signup" : "active",
      "signup_mode" : "user"
    }
  ]
}
var_dump($res->results);
  array(1) {
    [0]=>
    array(9) {
      ["id"]=> string(25) "ap_0v9XwmNDu1eHFAnDgYxHgb"
      ["provider_type"]=> string(8) "login_rocket"
      ["realm_id"]=> string(25) "rl_0v76O8itSEiwfhA64ZFvKj"
      ["object"]=> string(13) "auth_provider"
      ["login"]=> string(6) "active"
      ["name_field"]=> string(4) "none"
      ["password_field"]=> string(7) "confirm"
      ["signup"]=> string(6) "active"
      ["signup_mode"]=> string(4) "user"
    }
  }
[#<AuthRocket::AuthProvider:0x3fc21aab662c>
  id: "ap_0v9XwmNDu1eHFAnDgYxHgb",
  attribs: {
    "provider_type"=>"login_rocket",
    "realm_id"=>"rl_0v76O8itSEiwfhA64ZFvKj",
    "object"=>"auth_provider",
    "login"=>"active",
    "name_field"=>"none",
    "password_field"=>"confirm",
    "signup"=>"active",
    "signup_mode"=>"user"
  },
  metadata: {
    "more_results"=>false
  }
]

Get an auth provider

Retrieve a specific auth provider within the current realm.

Request

Example
GET /v1/auth_providers/:provider_id
$res = $client->authProviders()->find('ap_0v9XwmNDu1eHFAnDgYxHgb');
AuthRocket::AuthProvider.find 'ap_0v9XwmNDu1eHFAnDgYxHgb'

Response

Example

Status: 200

{ "id" : "ap_0v9XwmNDu1eHFAnDgYxHgb",
  "provider_type" : "login_rocket",
  "realm_id" : "rl_0v76O8itSEiwfhA64ZFvKj",
  "object" : "auth_provider",
  "login" : "active",
  "name_field" : "none",
  "password_field" : "confirm",
  "signup" : "active",
  "signup_mode" : "user"
}
var_dump($res->fields);
  array(9) {
    ["id"]=> string(25) "ap_0v9XwmNDu1eHFAnDgYxHgb"
    ["provider_type"]=> string(8) "login_rocket"
    ["realm_id"]=> string(25) "rl_0v76O8itSEiwfhA64ZFvKj"
    ["object"]=> string(13) "auth_provider"
    ["login"]=> string(6) "active"
    ["name_field"]=> string(4) "none"
    ["password_field"]=> string(7) "confirm"
    ["signup"]=> string(6) "active"
    ["signup_mode"]=> string(4) "user"
  }
#<AuthRocket::AuthProvider:0x3fc21aab662c>
  id: "ap_0v9XwmNDu1eHFAnDgYxHgb",
  attribs: {
    "provider_type"=>"login_rocket",
    "realm_id"=>"rl_0v76O8itSEiwfhA64ZFvKj",
    "object"=>"auth_provider",
    "login"=>"active",
    "name_field"=>"none",
    "password_field"=>"confirm",
    "signup"=>"active",
    "signup_mode"=>"user"
  }

Create an auth provider

Create a new auth provider.

Request

Example
POST /v1/auth_providers
{ "auth_provider" :
  { "provider_type" : "login_rocket",
    "realm_id" : "rl_0v76O8itSEiwfhA64ZFvKj",
    "login" : "active",
    "signup" : "inactive"
  }
}
$res = $client->authProviders()->create([
  "provider_type" => "login_rocket",
  "login" => "active",
  "signup" => "inactive"
]);
provider = AuthRocket::AuthProvider.create(
  provider_type: "login_rocket",
  realm_id: "rl_0v76O8itSEiwfhA64ZFvKj",
  login: "active",
  signup: "inactive"
)

Response

Example

Status: 201, with same body as Get an Auth Provider.

On success, returns same object as Get an Auth Provider.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(28) "Provider type not recognized"
  }

On success, returns same object as Get an Auth Provider.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::AuthProvider:0x3fde5fa18df8> id: nil, ...
provider.errors?
# => true
provider.valid?
# => false
provider.errors
# => ["Provider type not recognized"]

Events

Triggers an auth_provider.created event.

Update an auth provider

Update an auth provider’s attributes. Only provided attributes are changed.

Request

Example
PUT /v1/auth_providers/:provider_id
{ "auth_provider" :
  { "signup" : "active"
  }
}
$res = $client->authProviders()->update('ap_0v9XwmNDu1eHFAnDgYxHgb', [
  "signup" => "active"
]);
provider=AuthRocket::AuthProvider.find 'ap_0v9XwmNDu1eHFAnDgYxHgb'
provider.save signup: 'active'

Response

Example

Status: 200, with same body as Get an Auth Provider.

On success, returns same object as Get an Auth Provider.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(25) "Name field not recognized"
  }

On success, returns same object as Get an Auth Provider.

On failure, returns false:

# => false
provider.errors
# => ["Name field not recognized"]

Events

Triggers an auth_provider.updated event.

Delete an auth provider

Deletes an auth provider.

Deleting a third-party auth provider will irreversibly delete all associated user credentials.

Request

Example
DELETE /v1/auth_providers/:provider_id
$res = $client->authProviders()->delete('ap_0v9XwmNDu1eHFAnDgYxHgb');
provider=AuthRocket::AuthProvider.find 'ap_0v9XwmNDu1eHFAnDgYxHgb'
provider.delete

Response

Example

Status: 204

On success, returns an object with no errors.

On failure, returns an object with errors.

$res->hasErrors();
// => true or false

On success, returns original object.

On failure, returns false.

Events

Triggers an auth_provider.deleted event.

Questions? Find a Typo? Get in touch.