Module: Auth0::Api::AuthenticationEndpoints

Includes:
ClientAssertion
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
GRANT_TYPE_PASSWORDLESS_OPT = 
'http://auth0.com/oauth/grant-type/passwordless/otp'.freeze

Constants included from ClientAssertion

ClientAssertion::CLIENT_ASSERTION_TYPE

Instance Method Summary collapse

Methods included from ClientAssertion

#populate_client_assertion_or_secret

Instance Method Details

#api_token(client_id: @client_id, client_secret: @client_secret, organization: @organization, audience: nil) ⇒ json

Request an API access token using a Client Credentials grant

Parameters:

  • (defaults to: @client_id)

    Client ID for the application

  • (defaults to: @client_secret)

    Client secret for the application. Ignored if using Client Assertion

  • (defaults to: nil)

    API audience to use

  • (defaults to: @organization)

    Organization ID

Returns:

  • Returns the API token

See Also:



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 25

def api_token(
  client_id: @client_id,
  client_secret: @client_secret,
  organization: @organization,
  audience: nil
)
  request_params = {
    grant_type: 'client_credentials',
    client_id: client_id,
    audience: audience,
    organization: organization
  }

  populate_client_assertion_or_secret(request_params, client_id: client_id, client_secret: client_secret)

  response = request_with_retry(:post, '/oauth/token', request_params)
  ::Auth0::ApiToken.new(response['access_token'], response['scope'], response['expires_in'])
end

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

Return an authorization URL.

Parameters:

  • URL to redirect after authorization

  • (defaults to: {})

    Can contain response_type, connection, state, organization, invitation, and additional_parameters.

Returns:

  • Authorization URL.

Raises:

See Also:



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 355

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),
    organization: options.fetch(:organization, @organization),
    invitation: options.fetch(:invitation, 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

Deprecated.

Use #reset_password instead.

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

Parameters:

  • User's current email

  • User's new password. This is only available on legacy tenants with change password v1 flow enabled

  • (defaults to: UP_AUTH)

    Database connection name

Raises:

See Also:



257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 257

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
  }

  request_with_retry(:post, '/dbconnections/change_password', request_params)
end

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

Get access and ID tokens using an Authorization Code.

Parameters:

  • The authentication code obtained from /authorize

  • (defaults to: nil)

    URL to redirect to after authorization.

  • (defaults to: @client_id)

    Client ID for the application

  • (defaults to: @client_secret)

    Client secret for the application. Ignored if using Client Assertion Required only if it was set at the GET /authorize endpoint

  • (defaults to: nil)

    Cryptographically random key used to generate the code_challenge passed to GET /authorize. Required for the Authorization Code Flow with PKCE.

Returns:

  • Returns the access_token and id_token

Raises:

See Also:



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

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

  request_params = {
    grant_type: 'authorization_code',
    client_id: client_id,
    code: code,
    redirect_uri: redirect_uri,
    code_verifier: code_verifier
  }

  populate_client_assertion_or_secret(request_params, client_id: client_id, client_secret: client_secret)

  ::Auth0::AccessToken.from_response request_with_retry(:post, '/oauth/token', request_params)
end

#exchange_device_code_for_tokens(device_code, client_id: @client_id) ⇒ Auth0::AccessToken

Get access and ID tokens using a device code.

Device flow runs as a public client: no client_secret or client assertion is sent, and Auth0 rejects the request with unauthorized_client if one is.

Parameters:

  • The device code returned by start_device_flow.

  • (defaults to: @client_id)

    Client ID for the application

Returns:

  • Returns the access_token and id_token

Raises:

See Also:



105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 105

def exchange_device_code_for_tokens(device_code, client_id: @client_id)
  raise Auth0::InvalidParameter, 'Must provide a device code' if device_code.to_s.empty?

  request_params = {
    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
    client_id: client_id,
    device_code: device_code
  }

  ::Auth0::AccessToken.from_response request_with_retry(:post, '/oauth/token', request_params)
end

#exchange_email_otp_for_tokens(email_address, otp, audience: nil, scope: nil) ⇒ Object

Exchange an OTP recieved through email for ID and access tokens

Parameters:

  • The user's email address used to receive the OTP

  • The OTP contained in the email

  • (defaults to: nil)

    The audience for the access token (defaults to nil)

  • (defaults to: nil)

    The scope (defaults to 'openid profile email')



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 170

def exchange_email_otp_for_tokens(email_address, otp, audience: nil, scope: nil)
  request_params = {
    grant_type: GRANT_TYPE_PASSWORDLESS_OPT,
    client_id: @client_id,
    username: email_address,
    otp: otp,
    realm: 'email',
    audience: audience,
    scope: scope || 'openid profile email'
  }

  populate_client_assertion_or_secret(request_params)

  ::Auth0::AccessToken.from_response request_with_retry(:post, '/oauth/token', request_params)
end

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

Get access and ID tokens using a refresh token.

Parameters:

  • Refresh token to use. Request this with the offline_access scope when logging in.

  • (defaults to: @client_id)

    Client ID for the application

  • (defaults to: @client_secret)

    Client secret for the application. Ignored if using Client Assertion Required when the Application's Token Endpoint Authentication Method is Post or Basic.

Returns:

  • Returns tokens allowed in the refresh_token

Raises:

See Also:



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

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,
    refresh_token: refresh_token
  }

  populate_client_assertion_or_secret(request_params, client_id: client_id, client_secret: client_secret)

  ::Auth0::AccessToken.from_response request_with_retry(:post, '/oauth/token', request_params)
end

#exchange_sms_otp_for_tokens(phone_number, otp, audience: nil, scope: nil) ⇒ Object

Exchange an OTP recieved through SMS for ID and access tokens

Parameters:

  • The user's phone number used to receive the OTP

  • The OTP contained in the SMS

  • (defaults to: nil)

    The audience for the access token (defaults to nil)

  • (defaults to: nil)

    The scope (defaults to 'openid profile email')



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 149

def exchange_sms_otp_for_tokens(phone_number, otp, audience: nil, scope: nil)
  request_params = {
    grant_type: GRANT_TYPE_PASSWORDLESS_OPT,
    client_id: @client_id,
    username: phone_number,
    otp: otp,
    realm: 'sms',
    audience: audience,
    scope: scope || 'openid profile email'
  }

  populate_client_assertion_or_secret(request_params)

  ::Auth0::AccessToken.from_response request_with_retry(: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.

Parameters:

  • Email or username for the connection

  • Password

  • (defaults to: @client_id)

    Client ID for the application

  • (defaults to: @client_secret)

    Client secret for the application. Ignored if using Client Assertion

  • (defaults to: nil)

    Specific realm to authenticate against

  • (defaults to: nil)

    API audience

  • (defaults to: 'openid')

    Scope(s) requested

    • Include an audience (above) for API access scopes
    • Use the default "openid" for userinfo calls

Returns:

  • Returns the access_token and id_token

Raises:

See Also:



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 200

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,
    realm: realm,
    scope: scope,
    audience: audience,
    grant_type: realm ? 'http://auth0.com/oauth/grant-type/password-realm' : 'password'
  }

  populate_client_assertion_or_secret(request_params, client_id: client_id, client_secret: client_secret)

  ::Auth0::AccessToken.from_response request_with_retry(: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:

  • URL to redirect after logout.

  • (defaults to: false)

    Include the client_id in the logout URL.

  • (defaults to: false)

    Perform a federated logout.

Returns:

  • Logout URI

See Also:



394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 394

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

#par_authorization_url(request_uri) ⇒ Object

Return an authorization URL for PAR requests

Parameters:

  • The request_uri as obtained by calling pushed_authorization_request

  • Any additional parameters to send

Raises:

See Also:



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

def par_authorization_url(request_uri)
  raise Auth0::InvalidParameter, 'Must supply a valid request_uri' if request_uri.to_s.empty?

  request_params = {
    client_id: @client_id,
    request_uri: request_uri,
  }

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

#pushed_authorization_request(parameters = {}) ⇒ url

Make a request to the PAR endpoint and receive a request_uri to send to the '/authorize' endpoint.

Parameters:

  • URL to redirect after authorization

  • Can contain response_type, connection, state, organization, invitation, and additional_parameters.

Returns:

  • Authorization URL.

See Also:



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

def pushed_authorization_request(parameters = {})
  request_params = {
    client_id: @client_id,
    response_type: parameters.fetch(:response_type, 'code'),
    connection: parameters.fetch(:connection, nil),
    redirect_uri: parameters.fetch(:redirect_uri, nil),
    state: parameters.fetch(:state, nil),
    scope: parameters.fetch(:scope, nil),
    organization: parameters.fetch(:organization, nil),
    invitation: parameters.fetch(:invitation, nil)
  }.merge(parameters.fetch(:additional_parameters, {}))

  populate_client_assertion_or_secret(request_params)

  request_with_retry(:post_form, '/oauth/par', request_params, {})
end

#reset_password(email, connection_name = UP_AUTH, client_id = @client_id) ⇒ Object

Trigger a password reset email.

Parameters:

  • User's current email

  • (defaults to: UP_AUTH)

    Database connection name

  • (defaults to: @client_id)

    Client ID override (to allow forwarding to a different application's login URI on password reset success page)

Raises:

See Also:



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

def reset_password(email, connection_name = UP_AUTH, client_id = @client_id)
  raise Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?

  request_params = {
    email: email,
    connection: connection_name,
    client_id: client_id
  }

  request_with_retry(:post, '/dbconnections/change_password', request_params)
end

#saml_metadata ⇒ xml

Retrive SAML 2.0 metadata XML for an Application.

Returns:

  • SAML 2.0 metadata

See Also:



332
333
334
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 332

def saml_metadata
  request_with_retry(: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:

  • (defaults to: UP_AUTH)

    Connection to use; empty to show all

Returns:

  • SAMLP URL

See Also:



436
437
438
439
440
441
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 436

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:

  • New user's email

  • New user's password

  • (defaults to: UP_AUTH)

    Database connection name

Returns:

  • Returns the created user

Raises:

See Also:



235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 235

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
  }

  request_with_retry(:post, '/dbconnections/signup', request_params)
end

#start_device_flow(scope: nil, audience: nil, client_id: @client_id) ⇒ json

Start a Device Authorization flow.

Device flow runs as a public client: no client_secret or client assertion is sent, and Auth0 rejects the request with unauthorized_client if one is.

Parameters:

  • (defaults to: nil)

    Space-separated list of requested scopes.

  • (defaults to: nil)

    Unique identifier of the target API.

  • (defaults to: @client_id)

    Client ID for the application

Returns:

  • Returns device_code, user_code, verification_uri, verification_uri_complete, expires_in and interval.

See Also:



87
88
89
90
91
92
93
94
95
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 87

def start_device_flow(scope: nil, audience: nil, client_id: @client_id)
  request_params = {
    client_id: client_id,
    scope: scope,
    audience: audience
  }

  request_with_retry(:post, '/oauth/device/code', request_params)
end

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

Start Passwordless email login flow.

Parameters:

  • Email to send a link or code

  • (defaults to: 'link')

    Pass 'link' to send a magic link, 'code' to send a code

  • (defaults to: {})

    Append or override the magic link parameters

Raises:

See Also:



295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 295

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,
  }

  populate_client_assertion_or_secret(request_params)

  request_with_retry(:post, '/passwordless/start', request_params)
end

#start_passwordless_sms_flow(phone_number) ⇒ Object

Start Passwordless SMS login flow.

Parameters:

  • User's phone number.

Raises:

See Also:



315
316
317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 315

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,
  }

  populate_client_assertion_or_secret(request_params)

  request_with_retry(:post, '/passwordless/start', request_params)
end

#userinfo(access_token) ⇒ json

Return the user information based on the Auth0 access token.

Returns:

  • User information based on the Auth0 access token

See Also:



346
347
348
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 346

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

#validate_id_token(id_token, algorithm: nil, leeway: 60, nonce: nil, max_age: nil, issuer: nil, audience: nil, organization: @organization) ⇒ Object

rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/ParameterLists

Parameters:

  • (defaults to: 60)

    The clock skew to accept when verifying date related claims in seconds. Must be a non-negative value. Defaults to 60 seconds.

  • (defaults to: nil)

    The nonce value sent during authentication.

  • (defaults to: nil)

    The max_age value sent during authentication. Must be a non-negative value.

  • (defaults to: nil)

    The expected issuer claim value. Defaults to https://YOUR_AUTH0_DOMAIN/.

  • (defaults to: nil)

    The expected audience claim value. Defaults to your Auth0 Client ID.

  • (defaults to: @organization)

    Organization ID Defaults to your Auth0 Organization ID.



481
482
483
484
485
486
487
488
489
490
491
492
493
494
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 481

def validate_id_token(id_token, algorithm: nil, leeway: 60, nonce: nil, max_age: nil, issuer: nil, audience: nil, organization: @organization)
  context = {
    issuer: issuer || "https://#{@domain}/",
    audience: audience || @client_id,
    algorithm: algorithm || Auth0::Algorithm::RS256.jwks_url("https://#{@domain}/.well-known/jwks.json"),
    leeway: leeway
  }

  context[:nonce] = nonce unless nonce.nil?
  context[:max_age] = max_age unless max_age.nil?
  context[:organization] = organization unless !organization

  Auth0::Mixins::Validation::IdTokenValidator.new(context).validate(id_token)
end

#wsfed_metadata ⇒ xml

Retrieve WS-Federation metadata XML for a tenant.

Returns:

  • WS-Federation metadata

See Also:



339
340
341
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 339

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

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

Return a WS-Federation URL.

Parameters:

  • (defaults to: UP_AUTH)

    Connection to use; empty to show all

  • (defaults to: {})

    Extra options; supports wtrealm, wctx, wreply

Returns:

  • WS-Federation URL

See Also:



448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 448

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