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:
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.
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.
There may be one password
provider.
There may be one ‘totp’ provider. TOTP enables a two-factor authentication for password-based logins. It does not work without the Password provider.
There may be one provider each for facebook
, github
, google
, linkedin
, slack
, and yahoo
.
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
.
Field | Value | Req/Default | Notes |
---|---|---|---|
id |
id | Auto-generated | Provider’s ID. Always starts with “ap_”. Example: |
provider_type |
string | Required | |
realm_id |
realm_id | Required | ID of Realm this Provider belongs to. |
state |
active ,inactive |
active |
Except |
request |
hash | Hash of request attributes to add to Event. See notes. |
|
|
|||
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 |
require ,ask ,none |
none |
Are |
org_name_field |
require ,ask ,none |
none |
Is |
org_permissions |
string | Optional | One, or an Array of, permission(s). |
password_field |
confirm ,require |
confirm |
On signup, is the password |
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? |
|
|||
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 Social Provider |
client_secret |
string | Required | Client Secret, provided by the Social Provider |
scopes |
string | Optional | One, or an array of, extra scopes to request (in addition to basic profile with email). |
|
|||
name |
string | Required | Name of this provider. |
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). |
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. |
name_field |
string | Optional | Field name for the full name. |
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
).
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
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
.
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.
Method | Permissions |
---|---|
List, Get | read |
Create, Update, Delete | admin_realm |
List all auth providers in the current realm.
Param | Value | Default | |
---|---|---|---|
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 |
GET /v1/auth_providers
$res = $client->authProviders()->all();
AuthRocket::AuthProvider.all realm_id: 'rl_0v76O8itSEiwfhA64ZFvKj'
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
}
]
Retrieve a specific auth provider within the current realm.
GET /v1/auth_providers/:provider_id
$res = $client->authProviders()->find('ap_0v9XwmNDu1eHFAnDgYxHgb');
AuthRocket::AuthProvider.find 'ap_0v9XwmNDu1eHFAnDgYxHgb'
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 a new auth provider.
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"
)
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"]
Triggers an auth_provider.created
event.
Update an auth provider’s attributes. Only provided attributes are changed.
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'
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"]
Triggers an auth_provider.updated
event.
Deletes an auth provider.
Deleting a third-party auth provider will irreversibly delete all associated user credentials.
DELETE /v1/auth_providers/:provider_id
$res = $client->authProviders()->delete('ap_0v9XwmNDu1eHFAnDgYxHgb');
provider=AuthRocket::AuthProvider.find 'ap_0v9XwmNDu1eHFAnDgYxHgb'
provider.delete
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.
Triggers an auth_provider.deleted
event.
Questions? Find a Typo? Get in touch.