Field | Value | Req/Default | Notes |
---|---|---|---|
id |
id | Auto-generated | Realm's ID. Always starts with "rl_". Example: rl_USik0KJuMtajar2VwTJyQ |
name |
string | Required | Name/title of the realm. |
state |
active ,inactive |
active |
|
reference |
string | Optional | Field to map to your app's own ID. |
custom |
hash | Optional | Hash of custom attributes. |
username_validation_human |
standard ,email |
standard |
Determines how User.username is validated for human type users. |
require_unique_emails |
boolean | true |
Check User.email for uniqueness. |
api_key_prefix |
string | Optional | Default string prepended to auto-generated api_keys for Users. |
api_key_policy |
encrypt ,hash |
hash |
See below. |
jwt_algo |
hs256 ,rs256 |
hs256 |
Algorithm to use for signing JWTs. |
jwt_fields |
array | [] |
Extra fields to embed in login tokens. Valid values: custom, memberships, orgs. |
jwt_key |
string | Auto-generated | Secret key (hs256) or public key (rs256) for verifying login tokens. |
jwt_secret |
string | Deprecated; use jwt_key. | |
session_type |
managed ,unmanaged |
managed |
See Session Concepts. |
session_minutes |
integer | 360 |
Validity time of login tokens, in minutes. |
api_key_minutes |
integer | 0 |
Validity time of tokens generated for api_keys, in minutes. |
resource_links |
array | See below. | |
request |
hash | Hash of request attributes to add to Event. See notes. |
By default, accounts allow up to 100 realms. Contact support to request an increase.
api_key_policy
affects how Credential.api_key is stored. This only applies to users where user_type = 'api'
.
The hash
policy means that API keys are stored as one-way hashes, similar to passwords. They cannot be read again afterwards. This is the higher security option. On the other hand, many services that offer an API to their customers desire to show that API key to the end user on-demand. This is not possible if they’ve been hashed. If we generate the API key and it’s hashed, it will be returned to you once, when created. Afterward, it’s flushed from memory and cannot be retrieved again.
The encrypt
policy addresses this by storing all API keys using two-way encryption instead. (We handle the encryption transparently any time you retrieve the API user and read the API key, so it’s no further work on your part.)
We generally recommend the encrypt
policy as it’s more versatile. The hash
policy is intended for services with particularly high security needs–high enough to offset the reduced versatility.
Login (JWT) tokens embed a fair bit of user data, reducing the need for your app to query our servers. User profile data is included by default. Adding memberships
includes Membership data. Adding orgs
adds Org data (requires memberships
to also be present). Adding custom
adds custom attributes for the User, and if also included, the Membership and Org.
Tokens have the potential to get quite large when adding extra data, especially if there are many custom attributes or if the User has several Memberships. If your Users have only a handful of attributes or 1-3 Memberships, you should be fine. If they have more, be sure to verify that your entire app-server stack is prepared to handle the long tokens (typically 1-10KB). If storing tokens inside cookies, cookies have a total limit of 4K. Some webservers or proxies have difficulty with URLs or headers > 1K, which can affect query parameters, cookies, or other headers.
memberships
- Adds Membership permissions and Org IDs.orgs
- Adds Org names.custom
- Adds custom attributes for User, and optionally the Membership and Org.Hint: Tokens are cryptographically signed, but not encrypted. Tokens should generally be transmitted over https, but even then don’t use custom
or other extensions if it’s unsafe for your user to read their own data.
Used when calculating the expiration time of a login token generated during a normal login.
When session_type
is unmanaged
, valid values are 1 minute to 2 years (1052640 minutes). 0 is also valid and causes no expiration time to be set at all.
When session_type
is managed
, valid values are 1 minute to 1 year (527040 minutes).
Used when calculating the expiration time of a login token generated when authenticating with an api_key.
Valid values are 1 minute to 2 years (1052640 minutes). 0 is also valid and means no limit at all.
Resource links describes links/buttons to be automatically added to the AuthRocket UI. It is an array of hashes/dictionaries:
[{"resource" : "org",
"title" : "Manage account",
"url" : "https://yourapp.com/admin/org/{{reference}}"
}]
resource
must be one of: org
, user
.
url
will automatically parse select variables: {{id}}
, {{reference}}
, {{realm_id}}
See Custom attributes under Users for details.
Method | Permissions |
---|---|
List, Get | read |
Update, Reset | admin_realm |
Create, Delete | admin_all_realms |
List all realms on the current account.
Param | Value | Default | |
---|---|---|---|
reference |
reference | Filter by reference; must be an exact match | |
state |
state | Filter by state | |
after |
realm_id | ID of the last realm you've seen | |
max_results |
integer | 100 |
Range: 1-1000 |
sort |
id ,name |
name |
|
direction |
asc ,desc |
asc |
|
expand |
custom |
Include |
Status: 200
{ "more_results" : false,
"collection" : [
{ "id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
"name" : "AcmeApp SSO",
"reference" : null,
"state" : "active",
"object" : "realm"
}
]
}
var_dump($res->results);
array(1) {
[0]=>
array(5) {
["id"]=> string(25) "rl_0v2FcFc5IN79xazvkgLhnX"
["name"]=> string(23) "Acme App+"
["reference"]=> NULL
["state"]=> string(6) "active"
["object"]=> string(5) "realm"
}
}
[#<AuthRocket::Realm:0x3fde5d71d448>
id: "rl_0v2FcFc5IN79xazvkgLhnX",
attribs: {
"name"=>"Acme App+",
"reference"=>nil,
"state"=>"active",
"object"=>"realm"
},
metadata: {
"more_results"=>false
}
]
Retrieve a specific realm.
GET /v1/realms/:realm_id
$res = $client->realms()->find('rl_0v2FcFc5IN79xazvkgLhnX');
AuthRocket::Realm.find 'rl_0v2FcFc5IN79xazvkgLhnX'
Status: 200
{ "id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
"name" : "AcmeApp SSO",
"reference" : null,
"custom" : {},
"state" : "active",
"object" : "realm",
"api_key_policy" : "hash",
"api_key_prefix" : "pk-",
"username_validation_human" : "standard",
"require_unique_emails" : true,
"jwt_algo" : "hs256",
"jwt_fields" : [],
"jwt_key" : "jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
"session_type": "managed",
"session_minutes" : 360,
"api_key_minutes" : 0
}
var_dump($res->fields);
array(16) {
["id"]=> string(25) "rl_0v2FcFc5IN79xazvkgLhnX"
["name"]=> string(23) "Acme App+"
["reference"]=> NULL
["custom"]=> array(0) {}
["state"]=> string(6) "active"
["object"]=> string(5) "realm"
["api_key_policy"]=> string(4) "hash"
["api_key_prefix"]=> NULL
["username_validation_human"]=> string(8) "standard"
["require_unique_emails"]=> bool(true)
["jwt_algo"]=> string(5) "hs256"
["jwt_fields"]=> array(0) {}
["jwt_key"]=> string(47) "jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk"
["session_type"]=> string(7) "managed"
["session_minutes"]=> int(360)
["api_key_minutes"]=> int(0)
}
#<AuthRocket::Realm:0x3fde5d71d448>
id: "rl_0v2FcFc5IN79xazvkgLhnX",
attribs: {
"name"=>"Acme App+",
"reference"=>nil,
"custom"=>{},
"state"=>"active",
"object"=>"realm",
"api_key_policy"=>"hash",
"api_key_prefix"=>nil,
"username_validation_human"=>"standard",
"require_unique_emails"=>true,
"jwt_algo"=>"hs256",
"jwt_fields"=>[],
"jwt_key"=>"jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
"session_type"=>"managed",
"session_minutes"=>360,
"api_key_minutes"=>0
}
Create a new realm.
POST /v1/realms
{ "realm" :
{ "name" : "AcmeApp SSO",
"require_unique_emails" : true
}
}
$res = $client->realms()->create([
"name" => "AcmeApp SSO",
"require_unique_emails" => true
]);
realm = AuthRocket::Realm.create(
name: 'AcmeApp SSO',
require_unique_emails: true
)
Status: 201, with same body as Get a Realm.
On success, returns same object as Get a Realm.
On failure, returns an object with errors:
$res->hasErrors();
// => true
var_dump($res->errors);
array(1) {
[0]=> string(31) "Name can't be blank"
}
On success, returns same object as Get a Realm.
On failure, returns an object without an id, but with errors:
# => #<AuthRocket::Realm:0x3fde5d77e0f4> id: nil, ...
realm.errors?
# => true
realm.valid?
# => false
realm.errors
# => ["Name can't be blank"]
Triggers realm.created
and auth_provider.created
events.
Update a realm’s attributes. Only provided attributes are changed.
PUT /v1/realms/:realm_id
{ "realm" :
{ "name" : "Acme App SSO"
}
}
$res = $client->realms()->update('rl_0v6IVFUFLEM55OtsHWAOHQ', [
"name" => "Acme App SSO"
]);
realm=AuthRocket::Realm.find 'rl_0v6IVFUFLEM55OtsHWAOHQ'
realm.save reference: '123456'
Status: 200, with same body as Get a Realm.
On success, returns same object as Get a Realm.
On failure, returns an object with errors:
$res->hasErrors();
// => true
var_dump($res->errors);
array(1) {
[0]=> string(31) "Name can't be blank"
}
On success, returns same object as Get a Realm.
On failure, returns false:
# => false
realm.errors
# => ["Name can't be blank"]
Triggers a realm.updated
event.
Deletes a realm and everything it contains.
DELETE /v1/realms/:realm_id
$res = $client->realms()->delete('rl_0v6IVFUFLEM55OtsHWAOHQ');
realm=AuthRocket::Realm.find 'rl_0v6IVFUFLEM55OtsHWAOHQ'
realm.delete
Status: 202
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 a realm.deleted
event. Does not trigger events for associated Users, Orgs, etc.
Resets a realm by clearing most/all of what it contains. By default deletes all users and orgs, but keeps app hooks, auth providers, and login policies (connected apps).
Events associated with deleted objects are also removed.
Deleted data is not recoverable–use with caution. Useful for development and running tests.
Note: this runs asynchronously. Any records added to the realm while the reset is still running have the potential to be deleted.
POST /v1/realms/:realm_id/reset
{ "app_hooks" : false,
"auth_providers" : false,
"login_policies" : false,
"orgs" : true,
"users" : true
}
$res = $client->realms()->reset('rl_0v6IVFUFLEM55OtsHWAOHQ', [
"app_hooks" => false,
"auth_providers" => false,
"login_policies" => false,
"orgs" => true,
"users" => true
]);
realm=AuthRocket::Realm.find 'rl_0v6IVFUFLEM55OtsHWAOHQ'
realm.reset! orgs: true, users: true
Status: 202, with same response as Get a Realm.
On success, returns same object as Get a Realm.
On failure, returns an object with errors.
$res->hasErrors();
// => true
On success, returns same object as Get a Realm.
On failure, raises an exception.
Does not trigger any events.
Questions? Find a Typo? Get in touch.