External Authentication

The following APIs facilitate authentication against any external OAuth2 provider, including all Social Login providers.

See also: Authentication using a password.

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Provider’s ID. Starts with “ap_”. Example: ap_0v1zUpWdE4IiFc2w5ynShf
provider_type string

Provider type.
realm_id realm_id ID of Realm this Provider belongs to.
request hash

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

Required permissions

MethodPermissions
List URLs, Get URL read
Authenticate, Authenticate Token write

List authorization URLs

List authorization URLs for all active social and third-party auth providers in the current realm.

Use the returned URLs to build links or buttons when building your own login page. Returned URLs are valid for 30 minutes.

Not needed when using hosted logins (LoginRocket).

Parameters

ParamValueDefault
redirect_uri url URL in your app that will receive the incoming OAuth token (and send it back to AuthRocket).
nonce string Optional, but encouraged. A random string stored in the user's session in your app. Basically a CRSF check.

Request

Example
GET /v2/auth_providers/authorize?redirect_uri=https%3A%2F%2Fyour.app%2Foauth

var resp = await authrocket.authProviders.authorizeUrls({
  redirect_uri: "https://your.app/oauth"
})
$res = $authrocket->authProviders->authorizeUrls([
  "redirect_uri" => "https://your.app/oauth"
]);
AuthRocket::AuthProvider.authorize_urls(redirect_uri: "https://your.app/oauth",
  realm_id: "rl_sample123456")

Response

Example

Status: 200

{
  "collection": [
    {
      "auth_url": "https://www.facebook.com/v...clFSZz09",
      "id": "ap_sample123456",
      "provider_type": "facebook"
    }
  ],
  "more_results": false
}

// console.log(resp.results)
[
  {
    auth_url: "https://www.facebook.com/v...clFSZz09",
    id: "ap_sample123456",
    provider_type: "facebook"
  }
]
// var_dump($res->results);
array(1) {
  [0]=> 
    array(3) {
      ["auth_url"]=> string(37) "https://www.facebook.com/v...clFSZz09"
      ["id"]=> string(15) "ap_sample123456"
      ["provider_type"]=> string(8) "facebook"
    }
}
[AuthRocket::GenericObject(
  auth_url: "https://www.facebook.com/v...clFSZz09",
  id: "ap_sample123456",
  provider_type: "facebook"
 )
]

Get a provider's authorization URL

Retrieve the authorization URL for one active social or third-party auth provider in the current realm.

Use the returned URL to build a link or button when building your own login page. Returned URL is valid for 30 minutes.

Not needed when using hosted logins (LoginRocket).

Parameters

ParamValueDefault
redirect_uri url URL in your app that will receive the incoming OAuth token (and send it back to AuthRocket).
nonce string Optional, but encouraged. A random string stored in the user's session in your app. Basically a CRSF check.

Request

Example

The auth provider may be identified with its id or provider_type.

GET /v2/auth_providers/ap_sample123456/authorize?redirect_uri=https%3A%2F%2Fyour.app%2Foauth
GET /v2/auth_providers/facebook/authorize?redirect_uri=https%3A%2F%2Fyour.app%2Foauth

Due to ambiguity, provider_type cannot be oauth2. Use the ID in this case.

var resp = await authrocket.authProviders.authorizeUrl("ap_sample123456", {
  redirect_uri: "https://your.app/oauth"
})
var resp = await authrocket.authProviders.authorizeUrl("facebook", {
  redirect_uri: "https://your.app/oauth"
})
$res = $authrocket->authProviders->authorizeUrl("ap_sample123456", [
  "redirect_uri" => "https://your.app/oauth"
]);
$res = $authrocket->authProviders->authorizeUrl("facebook", [
  "redirect_uri" => "https://your.app/oauth"
]);
AuthRocket::AuthProvider.authorize_url("ap_sample123456",
  redirect_uri: "https://your.app/oauth")
AuthRocket::AuthProvider.authorize_url("facebook", redirect_uri: "https://your.app/oauth",
  realm_id: "rl_sample123456")

provider = AuthRocket::AuthProvider.find "ap_sample123456"
provider.authorize_url redirect_uri: "https://your.app/oauth"

Response

Example

Status: 200

{
  "auth_url": "https://www.facebook.com/v...clFSZz09",
  "id": "ap_sample123456",
  "provider_type": "facebook"
}

// console.log(resp.results)
{
  auth_url: "https://www.facebook.com/v...clFSZz09",
  id: "ap_sample123456",
  provider_type: "facebook"
}
// var_dump($res->fields);
array(3) {
  ["auth_url"]=> string(37) "https://www.facebook.com/v...clFSZz09"
  ["id"]=> string(15) "ap_sample123456"
  ["provider_type"]=> string(8) "facebook"
}
AuthRocket::GenericObject(
 auth_url: "https://www.facebook.com/v...clFSZz09",
 id: "ap_sample123456",
 provider_type: "facebook"
)

Authenticate using a provider's token

Accepts a provider’s token (authorization code), verifies it, and completes a login for the user.

Does for social and third-party authentication what Authenticate a User does for password logins, including creating login events and sessions.

Will auto-associate a social or third-party profile with an existing user, based on email address. If one is not found, creates a new User.

Existing users must be active.

If you are starting with an access token (instead of an authorization code), most likely from an iOS or Android SDK, use Authenticate using an access token instead.

Parameters

ParamValueDefault
code string

code parameter sent to your app (at your redirect_uri) by the external provider. Required (unless error is provided).
error string

If the external provider sends you error instead of code, you may handle that or pass it on to us, where we’ll turn it into our standard error format.
nonce string If provided to /authorize above, must send the same value here. You do not need to verify them; we will do it.
state string

state parameter sent to your app by the external provider. Required.

Request

Example
POST /v2/auth_providers/authorize

{
  "code": "ACQ51...KnJAS",
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "state": "ZWhCF...J3dmc"
}

var resp = await authrocket.authProviders.authorize({
  code: "ACQ51...KnJAS",
  state: "ZWhCF...J3dmc"
})
$res = $authrocket->authProviders->authorize([
  "code" => "ACQ51...KnJAS",
  "state" => "ZWhCF...J3dmc"
]);
session = AuthRocket::AuthProvider.authorize(code: params['code'],
  error: params['error'], state: params['state'])

Response

Example

On success, status 201 with the new Session.

{
  "client_app_id": null,
  "created_at": 1704067200.0,
  "expires_at": 1704153600,
  "id": "kss_sample123456",
  "object": "session",
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "token": "eyJ...",
  "user": {
    "...": "...",
    "object": "user"
  },
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response. When possible, includes a retry URL and other information with the error:

{ ... ,
  "provider_id" : "ap_sample123456",
  "retry_url" : "https://www.facebook.com/v...clFSZz09",
  "user_email" : "john@example.com"
}

The retry URL is the same as from Get an Authorization URL above, with the addition of anything required by the provider to indicate this is a retry.

On success, returns an object with the new Session.

// console.log(resp.results)
{
  client_app_id: null,
  created_at: 1704067200.0,
  expires_at: 1704153600,
  id: "kss_sample123456",
  object: "session",
  request: {
    client: "user's User-Agent header",
    ip: "10.0.0.1"
  },
  token: "eyJ...",
  user: {
    "...": "...",
    object: "user"
  },
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response.
When possible, also adds a retry URL, which is the same as from Get an Authorization URL above, with the addition of anything required by the provider to indicate this is a retry.

resp.metadata.retry_url
// => "https://www.facebook.com/v...clFSZz09"

On success, returns an object with the new Session.

// var_dump($res->fields);
array(9) {
  ["client_app_id"]=> NULL
  ["created_at"]=> float(1704067200.0)
  ["expires_at"]=> int(1704153600)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["request"]=> 
    array(2) {
      ["client"]=> string(24) "user's User-Agent header"
      ["ip"]=> string(8) "10.0.0.1"
    }
  ["token"]=> string(6) "eyJ..."
  ["user"]=> 
    array(2) {
      ["..."]=> string(3) "..."
      ["object"]=> string(4) "user"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response.
When possible, also adds a retry URL, which is the same as from Get an Authorization URL above, with the addition of anything required by the provider to indicate this is a retry.

$res->metadata["retry_url"];
// => "https://www.facebook.com/v...clFSZz09"

On success, returns an object with the new Session.

AuthRocket::Session(
 client_app_id: nil,
 created_at: 2024-01-01 00:00:00 UTC,
 expires_at: 2024-01-02 00:00:00 UTC,
 id: "kss_sample123456",
 request: {"client"=>"user's User-Agent header", "ip"=>"10.0.0.1"},
 token: "eyJ...",
 user: AuthRocket::User(...: "..."),
 user_id: "usr_sample123456"
)

On failure, returns an object with a standard error response.
When possible, also adds a retry URL, which is the same as from Get an Authorization URL above, with the addition of anything required by the provider to indicate this is a retry.

session.metadata[:retry_url]
# => "https://www.facebook.com/v...clFSZz09"

Events

On success, triggers a user.login.succeeded event.

If a new Credential was added to an existing user (it was their first login with this provider), triggers a user.updated event.

If a new user was created, triggers a user.created event.

Authenticate using an access token

Accepts a provider’s access token (already converted from an auth code) and completes a login for the user.

This is used when implementing authorization in native apps (typically iOS or Android), with a social vendor’s SDK that automatically converts authorization codes into access tokens for you. If you are starting with an authorization code, use Authenticate using a provider’s token instead.

Performs authentications, auto-association with users, and creates events like Authenticate using a provider’s token above.

If the token is expired or otherwise unusable, does not return a retry_url (in contrast to Authenticate using a provider’s token).

Parameters

ParamValueDefault
access_token string

Valid access_token for the external provider. Required.

Request

Example
POST /v2/auth_providers/:id/authorize

{
  "access_token": "JD7fD...jd8Nb2",
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  }
}

var resp = await authrocket.authProviders.authorizeToken("ap_sample123456", {
  access_token: "JD7fD...jd8Nb2"
})
$res = $authrocket->authProviders->authorizeToken("ap_sample123456", [
  "access_token" => "JD7fD...jd8Nb2"
]);
provider = AuthRocket::AuthProvider.find "ap_sample123456"
session = provider.authorize_token(access_token: params['access_token'])

Response

Example

On success, status 201 with the new Session.

{
  "client_app_id": null,
  "created_at": 1704067200.0,
  "expires_at": 1704153600,
  "id": "kss_sample123456",
  "object": "session",
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "token": "eyJ...",
  "user": {
    "...": "...",
    "object": "user"
  },
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with the new Session.

// console.log(resp.results)
{
  client_app_id: null,
  created_at: 1704067200.0,
  expires_at: 1704153600,
  id: "kss_sample123456",
  object: "session",
  request: {
    client: "user's User-Agent header",
    ip: "10.0.0.1"
  },
  token: "eyJ...",
  user: {
    "...": "...",
    object: "user"
  },
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success, returns an object with the new Session.

// var_dump($res->fields);
array(9) {
  ["client_app_id"]=> NULL
  ["created_at"]=> float(1704067200.0)
  ["expires_at"]=> int(1704153600)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["request"]=> 
    array(2) {
      ["client"]=> string(24) "user's User-Agent header"
      ["ip"]=> string(8) "10.0.0.1"
    }
  ["token"]=> string(6) "eyJ..."
  ["user"]=> 
    array(2) {
      ["..."]=> string(3) "..."
      ["object"]=> string(4) "user"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success, returns an object with the new Session.

AuthRocket::Session(
 client_app_id: nil,
 created_at: 2024-01-01 00:00:00 UTC,
 expires_at: 2024-01-02 00:00:00 UTC,
 id: "kss_sample123456",
 request: {"client"=>"user's User-Agent header", "ip"=>"10.0.0.1"},
 token: "eyJ...",
 user: AuthRocket::User(...: "..."),
 user_id: "usr_sample123456"
)

On failure, returns an object with a standard error response.

Events

On success, triggers same events as Authenticate using a provider’s token.

Contents
Fields Required permissions List authorization URLs Get a provider's authorization URL Authenticate using a provider's token Authenticate using an access token