OAuth API

The OAuth API is an extension of the server-side Users module. The following methods allow you to manage OAuth providers for a custom user. See the server-side Users module for more information on managing custom users.

The main use cases for the OAuth API are Facebook Login, Google Sign-In, and Devices as Users.

Client-Side OAuth Users

Working with client-side OAuth API is the recommended way to work with OAuth users.

getWithProvider

Get a user record based on an auth provider and immutable client ID.

core.users.getWithProvider(scope, provider, client_id)

Parameters

Name	Description	Type	Required
scope	The application scope the user belongs to.	String	Y
provider	The OAuth provider constant (see OAuth Constants).	Const	Y
client_id	The immutable identifier returned by the auth provider.	String	Y

Important

String values are automatically run through mysql.escape. Do not double-escape values.

Returns

A user record as a table, or nil, error, and error code. The record will also include the provider information in the users oauth key.

The oauth table contains the following keys

• client_id (string)
• access_token (string)
• access_token_expiry (number)
• access_token_expired (boolean)
• provider (string)

Example

local api = core.api()

function api.getUser(input, scope)

  local user, err, code = core.users.getWithProvider(
    scope, 
    core.FACEBOOK, 
    "fb-id_1234")

  ...
end

return api

Token Expiration

If an access token and expiration has been added to the record, the token expiration state will be determined internally. You can check for expiration with the boolean access_token_expired key. See also the accessTokenExpired method.

Example

local api = core.api()

function api.getUser(input, scope)

  local user, err, code = core.users.getWithProvider(
    scope, 
    core.FACEBOOK, 
    "fb-id_1234")

  --check access token expiration
  if user.oauth.access_token_expired then
    --token has expired
  else
    --token is valid
  end

  ...

end

return api

addAuthProvider

Link OAuth provider information to a custom user.

core.users.addAuthProvider(user_id, provider, info_tbl)

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
provider	The OAuth provider constant (see OAuth Constants).	Const	Y
info_tbl	Table of the provider information in key/value format (see below).	Table	Y

Info Table Keys

Name	Description	Type	Required
client_id	The immutable ID provided by the OAuth provider.	String	Y
access_token	OAuth provider access token, if any.	String	N
access_token_expiry	The lifetime of the access token as a UNIX timestamp, if any.	Number	N

Important

String values are automatically run through mysql.escape. Do not double-escape values.

Returns

The added provider information as a table, or nil, error, and error code.

The returned table contains the following keys:

• client_id (string)
• access_token (string)
• access_token_expiry (number)
• access_token_expired (boolean)
• provider (string)

Example

local res, err, code = core.users.addAuthProvider("aad3eba3...", core.FACEBOOK, {
  client_id = "fb-id-1234",
  access_token = "1234abcd",
  access_token_expiry = 1516647155
})

getAuthProvider

Get OAuth provider information for a custom user.

core.users.getAuthProvider(user_id, provider)

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
provider	The OAuth provider constant (see OAuth Constants).	Const	Y

Returns

The provider information as a table, or nil, error, and error code.

The returned table contains the following keys

• client_id (string)
• access_token (string)
• access_token_expiry (number)
• access_token_expired (boolean)
• provider (string)

Example

local res, err, code = core.users.getAuthProvider("aad3eba3...", core.FACEBOOK)

getAuthProviders

Get all OAuth providers information for a custom user.

core.users.getAuthProviders(user_id)

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y

Returns

The provider information as a keyed table by provider, with each providers information table, or nil, error, and error code.

The table returned has a structure like so:

{
  facebook = {
    client_id = "fb-id-1234",
    access_token = "1234abcd",
    access_token_expiry = 1516647155,
    access_token_expired = false
  },
  google = {
    client_id = "google-id-1234",
    access_token = "1234abcd",
    access_token_expiry = 1516640011,
    access_token_expired = true    
  },
  ...
}

Example

local res, err, code = core.users.getAuthProviders("aad3eba3...")

updateAuthProvider

Update OAuth provider information for a custom user.

core.users.updateAuthProvider(user_id, provider, params)

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
provider	The OAuth provider constant (see OAuth Constants).	Const	Y
params	A table of key/value pairs of provider information.	Table	Y

Important

String values are automatically run through mysql.escape. Do not double-escape values.

The following keys are updatable:

• client_id (string)
• access_token (string)
• access_token_expiry (number)

Returns

The updated provider information as a table (see getAuthProvider), or nil, error, and error code.

Example

local res, err, code = core.users.updateAuthProvider("aad3eba3...", core.FACEBOOK, 
{
  access_token = "1234efgh",
  access_token_expiry = 1516663152
})

removeAuthProvider

Remove an OAuth provider from a custom user.

core.users.removeAuthProvider(user_id, provider)

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
provider	The OAuth provider constant (see OAuth Constants).	Const	Y

Returns

The user_id as a string, or nil, error, and error code.

Example

local res, err, code = core.users.removeAuthProvider("aad3eba3...", core.FACEBOOK)

removeAuthProviders

Remove all OAuth providers from a custom user.

core.users.removeAuthProviders(user_id)

Warning

This method clears all of the providers for the given user ID.

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y

Returns

The user_id as a string, or nil, error, and error code.

Example

local res, err, code = core.users.removeAuthProviders("aad3eba3...")

accessTokenExpired

Conditionally check if a users access token has expired for the specified provider.

core.users.accessTokenExpired(user_id, provider)

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
provider	The OAuth provider constant (see OAuth Constants).	Const	Y

Returns

A boolean value based on whether the access token has expired. Will be true is the token has expired, or false if the access token is still valid.

Note

If the user does not have the specified provider linked to their account, the result will always be true.

Example

if core.users.accessTokenExpired("aad3eba3...", core.FACEBOOK) then
  --token has expired
else
  --token is still valid
end

updateTokenExpiry

Update the provider token expiration time. This is a convenience method, see also updateAuthProvider.

core.users.updateTokenExpiry(user_id, provider, expiry[, token])

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
provider	The OAuth provider constant (see OAuth Constants).	Const	Y
expiry	The new access token expiration time as a UNIX timestamp.	Number	Y
token	Optionally update the access token string as well.	String	N

Returns

The updated provider information as a table (see getAuthProvider), or nil, error, and error code.

Example

local res, err, code = core.users.updateTokenExpiry(
  "aad3eba3...", 
  core.FACEBOOK, 
  1516663152)

OAuth Constants

Used for the provider parameter in OAuth methods.

Constant	Description	See Also
core.FACEBOOK	Marks a provider as Facebook.	Facebook Login
core.GOOGLE	Marks a provider as Google.	Google Sign-In
core.OPENUDID	Marks a provider as OpenUDID	Devices As Users