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

#api_token(client_id: @client_id, client_secret: @client_secret, audience: "https://#{@domain}/api/v2/") ⇒ json

Request an API access token using a Client Credentials grant


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

def api_token(
  client_id: @client_id,
  client_secret: @client_secret,
  audience: "https://#{@domain}/api/v2/"
)
  request_params = {
    grant_type: 'client_credentials',
    client_id: client_id,
    client_secret: client_secret,
    audience: audience
  }
  response = post('/oauth/token', request_params)
  ApiToken.new(response['access_token'], response['scope'], response['expires_in'])
end

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

Return an authorization URL.


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

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.


147
148
149
150
151
152
153
154
155
156
157
# File 'lib/auth0/api/authentication_endpoints.rb', line 147

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.


439
440
441
442
443
444
445
446
447
448
449
450
451
# File 'lib/auth0/api/authentication_endpoints.rb', line 439

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

#exchange_auth_code_for_tokens(code, redirect_uri: nil, client_id: @client_id, client_secret: @client_secret) ⇒ AccessToken

Get access and ID tokens using an Authorization Code.


37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# File 'lib/auth0/api/authentication_endpoints.rb', line 37

def exchange_auth_code_for_tokens(
  code,
  redirect_uri: nil,
  client_id: @client_id,
  client_secret: @client_secret
)
  raise Auth0::InvalidParameter, 'Must provide an authorization code' if code.to_s.empty?

  request_params = {
    grant_type: 'authorization_code',
    client_id: client_id,
    client_secret: client_secret,
    code: code,
    redirect_uri: redirect_uri
  }
  AccessToken.from_response post('/oauth/token', request_params)
end

#exchange_refresh_token(refresh_token, client_id: @client_id, client_secret: @client_secret) ⇒ AccessToken

Get access and ID tokens using a refresh token.


64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
# File 'lib/auth0/api/authentication_endpoints.rb', line 64

def exchange_refresh_token(
  refresh_token,
  client_id: @client_id,
  client_secret: @client_secret
)
  raise Auth0::InvalidParameter, 'Must provide a refresh token' if refresh_token.to_s.empty?

  request_params = {
    grant_type: 'refresh_token',
    client_id: client_id,
    client_secret: client_secret,
    refresh_token: refresh_token
  }
  AccessToken.from_response post('/oauth/token', 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


462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
# File 'lib/auth0/api/authentication_endpoints.rb', line 462

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

Deprecated.

4.6.0 - Use the login_with_resource_owner method instead.

Get access and ID tokens using Resource Owner Password.


343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
# File 'lib/auth0/api/authentication_endpoints.rb', line 343

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

#login_with_resource_owner(login_name, password, client_id: @client_id, client_secret: @client_secret, realm: nil, audience: nil, scope: 'openid') ⇒ json

rubocop:disable Metrics/ParameterLists Get access and ID tokens using Resource Owner Password. Requires that your tenant has a Default Audience or Default Directory.


94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
# File 'lib/auth0/api/authentication_endpoints.rb', line 94

def (
  ,
  password,
  client_id: @client_id,
  client_secret: @client_secret,
  realm: nil,
  audience: nil,
  scope: 'openid'
)

  raise Auth0::InvalidParameter, 'Must supply a valid login_name' if .empty?
  raise Auth0::InvalidParameter, 'Must supply a valid password' if password.empty?

  request_params = {
    username: ,
    password: password,
    client_id: client_id,
    client_secret: client_secret,
    realm: realm,
    scope: scope,
    audience: audience,
    grant_type: realm ? 'http://auth0.com/oauth/grant-type/password-realm' : 'password'
  }
  AccessToken.from_response 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.


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

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

Deprecated.

4.6.0 - Use the api_token method instead.

Retrieve an access token.


299
300
301
302
303
304
305
306
307
# File 'lib/auth0/api/authentication_endpoints.rb', line 299

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

Deprecated.

4.6.0 - Use the exchange_auth_code_for_tokens method instead.

Get access and ID tokens using an Authorization Code.


317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
# File 'lib/auth0/api/authentication_endpoints.rb', line 317

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.


376
377
378
379
380
381
382
383
384
385
386
387
388
389
# File 'lib/auth0/api/authentication_endpoints.rb', line 376

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.


414
415
416
417
418
419
420
421
422
423
424
425
426
# File 'lib/auth0/api/authentication_endpoints.rb', line 414

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_metadataxml

Retrive SAML 2.0 metadata XML for an Application.


196
197
198
# File 'lib/auth0/api/authentication_endpoints.rb', line 196

def 
  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.


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

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.


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

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.


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

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.


182
183
184
185
186
187
188
189
190
191
# File 'lib/auth0/api/authentication_endpoints.rb', line 182

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).


396
397
398
399
400
401
# File 'lib/auth0/api/authentication_endpoints.rb', line 396

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
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.


492
493
494
495
496
497
498
499
500
501
# File 'lib/auth0/api/authentication_endpoints.rb', line 492

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_infojson

Deprecated.

4.6.0 - Use the userinfo method instead.

Return the user information based on the Auth0 access token.


365
366
367
# File 'lib/auth0/api/authentication_endpoints.rb', line 365

def 
  get('/userinfo')
end

#userinfo(access_token) ⇒ json

Return the user information based on the Auth0 access token.


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

def userinfo(access_token)
  get('/userinfo', {}, 'Authorization' => "Bearer #{access_token}")
end

#wsfed_metadataxml

Retrieve WS-Federation metadata XML for a tenant.


203
204
205
# File 'lib/auth0/api/authentication_endpoints.rb', line 203

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

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

Return a WS-Federation URL.


273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
# File 'lib/auth0/api/authentication_endpoints.rb', line 273

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 unless request_params[:wtrealm]
  URI::HTTPS.build(
    host: @domain,
    path: "/wsfed/#{url_client_id}",
    query: to_query(request_params)
  )
end