Module: Auth0::Api::AuthenticationEndpoints

Defined in:
lib/auth0/api/authentication_endpoints.rb

Overview

https://auth0.com/docs/api/authentication Methods to use the Authentication API

Constant Summary collapse

UP_AUTH = 
'Username-Password-Authentication'.freeze
JWT_BEARER = 
'urn:ietf:params:oauth:grant-type:jwt-bearer'.freeze

Instance Method Summary collapse

Instance Method Details

#authorization_url(redirect_uri, options = {}) ⇒ url

Return an authorization URL.

Parameters:

  • redirect_uri (string) —

    URL to redirect after authorization

  • options (hash) (defaults to: {}) —

    Can contain response_type, connection, state and additional_parameters.

Returns:

  • (url) —

    Authorization URL.

Raises:

See Also:



167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 167

def authorization_url(redirect_uri, options = {})
  raise Auth0::InvalidParameter, 'Must supply a valid redirect_uri' if redirect_uri.to_s.empty?
  request_params = {
    client_id: @client_id,
    response_type: options.fetch(:response_type, 'code'),
    connection: options.fetch(:connection, nil),
    redirect_uri: redirect_uri,
    state: options.fetch(:state, nil),
    scope: options.fetch(:scope, nil)
  }.merge(options.fetch(:additional_parameters, {}))

  URI::HTTPS.build(host: @domain, path: '/authorize', query: to_query(request_params))
end

#change_password(email, password, connection_name = UP_AUTH) ⇒ Object

Change a user’s password or trigger a password reset email.

Parameters:

  • email (string) —

    User’s current email

  • password (string) —

    User’s new password; empty to trigger a password reset email

  • connection_name (string) (defaults to: UP_AUTH) —

    Database connection name

Raises:

See Also:



98
99
100
101
102
103
104
105
106
107
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 98

def change_password(email, password, connection_name = UP_AUTH)
  raise Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
  request_params = {
    email:      email,
    password:   password,
    connection: connection_name,
    client_id:  @client_id
  }
  post('/dbconnections/change_password', request_params)
end

#delegation(id_token, target, scope = 'openid', api_type = 'app', extra_parameters = {}) ⇒ json

Deprecated.

4.5.0 - Feature is disabled, no replacement currently; see auth0.com/docs/api-auth/tutorials/adoption/delegation

Retrieve a delegation token.

Parameters:

  • id_token (string) —

    Token’s id.

  • target (string) —

    Target to sign the new token.

  • scope (string) (defaults to: 'openid') —

    Defaults to openid. Can be ‘openid name email’.

  • api_type (string) (defaults to: 'app') —

    Defaults to app. Can be aws, azure_sb, azure_blob, firebase, layer, salesforce_api, salesforce_sandbox_api, sap_api or wams

  • extra_parameters (hash) (defaults to: {}) —

    Extra parameters.

Returns:

  • (json) —

    Returns the refreshed delegation token

Raises:

See Also:



303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 303

def delegation(id_token, target, scope = 'openid', api_type = 'app', extra_parameters = {})
  raise Auth0::InvalidParameter, 'Must supply a valid id_token' if id_token.to_s.empty?
  request_params = {
    client_id:  @client_id,
    grant_type: JWT_BEARER,
    id_token:   id_token,
    target:     target,
    api_type:   api_type,
    scope:      scope
  }.merge(extra_parameters)
  post('/delegation', request_params)
end

#impersonate(user_id, app_client_id, impersonator_id, options) ⇒ string

Deprecated.

4.5.0 - Feature is disabled.

Retrieve an impersonation URL to login as another user. rubocop:disable Metrics/MethodLength, Metrics/AbcSize

Parameters:

  • user_id (string) —

    Impersonate user id

  • app_client_id (string) —

    Application client id

  • impersonator_id (string) —

    Impersonator user id id.

  • options (string) —

    Additional Parameters

Returns:

  • (string) —

    Impersonation URL

Raises:

See Also:



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 325

def impersonate(user_id, app_client_id, impersonator_id, options)
  raise Auth0::InvalidParameter, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid app_client_id' if app_client_id.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid impersonator_id' if impersonator_id.to_s.empty?
  raise Auth0::MissingParameter, 'Must supply client_secret' if @client_secret.nil?
  authorization_header obtain_access_token
  request_params = {
    protocol:         options.fetch(:protocol, 'oauth2'),
    impersonator_id:  impersonator_id,
    client_id:        app_client_id,
    additionalParameters: {
      response_type:  options.fetch(:response_type, 'code'),
      state:          options.fetch(:state, ''),
      scope:          options.fetch(:scope, 'openid'),
      callback_url:   options.fetch(:callback_url, '')
    }
  }
  result = post("/users/#{user_id}/impersonate", request_params)
  authorization_header @token
  result
end

#login(username, password, id_token = nil, connection_name = UP_AUTH, options = {}) ⇒ json

Get access and ID tokens using Resource Owner Password.

Parameters:

  • username (string) —

    Username or email

  • password (string) —

    Password

  • id_token (string) (defaults to: nil) —

    Token’s id

  • connection_name (string) (defaults to: UP_AUTH) —

    Connection name; use a database or passwordless connection, Active Directory/LDAP, Windows Azure or ADF

  • options (hash) (defaults to: {}) —

    Additional options - :scope, :grant_type, :device

Returns:

  • (json) —

    Returns the access_token and id_token

Raises:

See Also:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 56

def (username, password, id_token = nil, connection_name = UP_AUTH, options = {})
  raise Auth0::InvalidParameter, 'Must supply a valid username' if username.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid password' if password.to_s.empty?
  request_params = {
    client_id:     @client_id,
    client_secret: @client_secret,
    username:      username,
    password:      password,
    scope:         options.fetch(:scope, 'openid'),
    connection:    connection_name,
    grant_type:    options.fetch(:grant_type, 'password'),
    id_token:      id_token,
    device:        options.fetch(:device, nil)
  }
  post('/oauth/token', request_params)
end

#logout_url(return_to, include_client: false, federated: false) ⇒ url

Returns an Auth0 logout URL with a return URL.

Parameters:

  • return_to (string) —

    URL to redirect after logout.

  • include_client (bool) (defaults to: false) —

    Include the client_id in the logout URL.

  • federated (boolean) (defaults to: false) —

    Perform a federated logout.

Returns:

  • (url) —

    Logout URI

See Also:



188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 188

def logout_url(return_to, include_client: false, federated: false)
  request_params = {
    returnTo: return_to,
    client_id: include_client ? @client_id : nil,
    federated: federated ? '1' : nil
  }

  URI::HTTPS.build(
    host: @domain,
    path: '/v2/logout',
    query: to_query(request_params)
  )
end

#obtain_access_token(access_token = nil, connection = 'facebook', scope = 'openid') ⇒ json

Retrieve an access token.

Parameters:

  • access_token (string) (defaults to: nil) —

    Social provider’s access_token

  • connection (string) (defaults to: 'facebook') —

    Currently, this endpoint only works for Facebook, Google, Twitter and Weibo

Returns:

  • (json) —

    Returns the access token

See Also:



15
16
17
18
19
20
21
22
23
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 15

def obtain_access_token(access_token = nil, connection = 'facebook', scope = 'openid')
  if access_token
    request_params = { client_id: @client_id, access_token: access_token, connection: connection, scope: scope }
    post('/oauth/access_token', request_params)['access_token']
  else
    request_params = { client_id: @client_id, client_secret: @client_secret, grant_type: 'client_credentials' }
    post('/oauth/token', request_params)['access_token']
  end
end

#obtain_user_tokens(code, redirect_uri, connection = 'facebook', scope = 'openid') ⇒ json

Get access and ID tokens using an Authorization Code.

Parameters:

  • code (string) —

    The access code obtained through passive authentication

  • redirect_uri (string) —

    Url to redirect after authorization

  • connection (string) (defaults to: 'facebook') —

    Currently, this endpoint only works for Facebook, Google, Twitter and Weibo

  • scope (string) (defaults to: 'openid') —

    Defaults to openid. Can be ‘openid name email’, ‘openid offline_access’

Returns:

  • (json) —

    Returns the access_token and id_token

Raises:

See Also:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 32

def obtain_user_tokens(code, redirect_uri, connection = 'facebook', scope = 'openid')
  raise Auth0::InvalidParameter, 'Must supply a valid code' if code.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid redirect_uri' if redirect_uri.to_s.empty?
  request_params = {
    client_id:     @client_id,
    client_secret: @client_secret,
    connection:    connection,
    grant_type:    'authorization_code',
    code:          code,
    scope:         scope,
    redirect_uri:  redirect_uri
  }
  post('/oauth/token', request_params)
end

#phone_login(phone_number, code, scope = 'openid') ⇒ json

Deprecated.

4.5.0 - Legacy authentication pipeline; use a Password Grant instead - auth0.com/docs/api-auth/tutorials/password-grant

Login using phone number + verification code.

Parameters:

  • phone_number (string) —

    User’s phone number.

  • code (string) —

    Verification code.

Returns:

  • (json) —

    Returns the access token and id token

Raises:

See Also:



243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 243

def (phone_number, code, scope = 'openid')
  raise Auth0::InvalidParameter, 'Must supply a valid phone number' if phone_number.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid code' if code.to_s.empty?
  request_params = {
    client_id:  @client_id,
    username:   phone_number,
    password:   code,
    scope:      scope,
    connection: 'sms',
    grant_type: 'password'
  }
  post('/oauth/ro', request_params)
end

#refresh_delegation(refresh_token, target, scope = 'openid', api_type = 'app', extra_parameters = {}) ⇒ json

Deprecated.

4.5.0 - Feature is disabled, no replacement currently; see auth0.com/docs/api-auth/tutorials/adoption/delegation

Refresh a delegation token.

Parameters:

  • refresh_token (string) —

    Token to refresh

  • target (string) —

    Target to sign the new token.

  • scope (string) (defaults to: 'openid') —

    Defaults to openid. Can be ‘openid name email’.

  • api_type (string) (defaults to: 'app') —

    Defaults to app. Can be aws, azure_sb, azure_blob, firebase, layer, salesforce_api, salesforce_sandbox_api, sap_api or wams

  • extra_parameters (hash) (defaults to: {}) —

    Extra parameters.

Returns:

  • (json) —

    Returns the refreshed delegation token

Raises:

See Also:



279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 279

def refresh_delegation(refresh_token, target, scope = 'openid', api_type = 'app', extra_parameters = {})
  raise Auth0::InvalidParameter, 'Must supply a valid token to refresh' if refresh_token.to_s.empty?
  request_params = {
    client_id:      @client_id,
    grant_type:     JWT_BEARER,
    refresh_token:  refresh_token,
    target:         target,
    api_type:       api_type,
    scope:          scope
  }.merge(extra_parameters)
  post('/delegation', request_params)
end

#saml_metadata ⇒ xml

Retrive SAML 2.0 metadata XML for an Application.

Returns:

  • (xml) —

    SAML 2.0 metadata

See Also:



144
145
146
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 144

def saml_metadata
  get("/samlp/metadata/#{@client_id}")
end

#samlp_url(connection = UP_AUTH) ⇒ url

Return a SAMLP URL. The SAML Request AssertionConsumerServiceURL will be used to POST back the assertion and it must match with the application callback URL.

Parameters:

  • connection (string) (defaults to: UP_AUTH) —

    Connection to use; empty to show all

Returns:

  • (url) —

    SAMLP URL

See Also:



208
209
210
211
212
213
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 208

def samlp_url(connection = UP_AUTH)
  request_params = {
    connection: connection
  }
  URI::HTTPS.build(host: @domain, path: "/samlp/#{@client_id}", query: to_query(request_params))
end

#signup(email, password, connection_name = UP_AUTH) ⇒ json

Sign up with a database connection using a username and password.

Parameters:

  • email (string) —

    New user’s email

  • password (string) —

    New user’s password

  • connection_name (string) (defaults to: UP_AUTH) —

    Database connection name

Returns:

  • (json) —

    Returns the created user

Raises:

See Also:



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 79

def (email, password, connection_name = UP_AUTH)
  raise Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid password' if password.to_s.empty?
  request_params = {
    email:      email,
    password:   password,
    connection: connection_name,
    client_id:  @client_id
  }
  post('/dbconnections/signup', request_params)
end

#start_passwordless_email_flow(email, send = 'link', auth_params = {}) ⇒ Object

Start Passwordless email login flow.

Parameters:

  • email (string) —

    Email to send a link or code

  • send (string) (defaults to: 'link') —

    Pass ‘link’ to send a magic link, ‘code’ to send a code

  • auth_params (hash) (defaults to: {}) —

    Append or override the magic link parameters

Raises:

See Also:



115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 115

def start_passwordless_email_flow(email, send = 'link', auth_params = {})
  raise Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
  request_params = {
    email:       email,
    send:        send,
    authParams:  auth_params,
    connection:  'email',
    client_id:   @client_id
  }
  post('/passwordless/start', request_params)
end

#start_passwordless_sms_flow(phone_number) ⇒ Object

Start Passwordless SMS login flow.

Parameters:

  • phone_number (string) —

    User’s phone number.

Raises:

See Also:



131
132
133
134
135
136
137
138
139
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 131

def start_passwordless_sms_flow(phone_number)
  raise Auth0::InvalidParameter, 'Must supply a valid phone number' if phone_number.to_s.empty?
  request_params = {
    phone_number: phone_number,
    connection:   'sms',
    client_id:    @client_id
  }
  post('/passwordless/start', request_params)
end

#token_info(id_token) ⇒ Object

Deprecated.

4.5.0 - Legacy endpoint, use /userinfo instead.

Validate a JSON Web Token (signature and expiration).

Parameters:

  • id_token (string) —

    ID Token to use

Returns:

  • User information associated with the user id (sub property) of the token.

Raises:

See Also:



262
263
264
265
266
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 262

def token_info(id_token)
  raise Auth0::InvalidParameter, 'Must supply a valid id_token' if id_token.to_s.empty?
  request_params = { id_token: id_token }
  post('/tokeninfo', request_params)
end

#unlink_user(access_token, user_id) ⇒ Object

Deprecated.

4.5.0 - Endpoint is disabled in favor of the Management API; see auth0.com/docs/migrations/guides/account-linking

Unlink a user’s account from the identity provider.

Parameters:

  • access_token (string) —

    Logged-in user access token

  • user_id (string) —

    User Id

Raises:

See Also:



354
355
356
357
358
359
360
361
362
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 354

def unlink_user(access_token, user_id)
  raise Auth0::InvalidParameter, 'Must supply a valid access_token' if access_token.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid user_id' if user_id.to_s.empty?
  request_params = {
    access_token:  access_token,
    user_id: user_id
  }
  post('/unlink', request_params)
end

#user_info ⇒ json

Return the user information based on the Auth0 access token.

Returns:

  • (json) —

    User information based on the Auth0 access token

See Also:



158
159
160
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 158

def 
  get('/userinfo')
end

#wsfed_metadata ⇒ xml

Retrieve WS-Federation metadata XML for a tenant.

Returns:

  • (xml) —

    WS-Federation metadata

See Also:



151
152
153
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 151

def wsfed_metadata
  get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml')
end

#wsfed_url(connection = UP_AUTH, options = {}) ⇒ url

Return a WS-Federation URL.

Parameters:

  • connection (string) (defaults to: UP_AUTH) —

    Connection to use; empty to show all

  • options (hash) (defaults to: {}) —

    Extra options; supports wtrealm, wctx, wreply

Returns:

  • (url) —

    WS-Federation URL

See Also:



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 220

def wsfed_url(connection = UP_AUTH, options = {})
  request_params = {
    whr: connection,
    wtrealm: options[:wtrealm],
    wctx: options[:wctx],
    wreply: options[:wreply]
  }

  url_client_id = @client_id if !request_params[:wtrealm]
  URI::HTTPS.build(
    host: @domain,
    path: "/wsfed/#{url_client_id}",
    query: to_query(request_params)
  )
end