Module: Auth0::Api::AuthenticationEndpoints

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

Overview

https://auth0.com/docs/auth-api Methods to use the authentication endpoints

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

Returns an authorization URL, triggers a redirect.

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:



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

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

Asks to change a password for a given user. Send an email to the user.

Parameters:

  • email (string) —

    User email

  • password (string) —

    User’s new password

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

    Connection name. Works for database connections.

Raises:

See Also:



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

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

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

Retrives 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:



211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 211

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

Retrives 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:



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 232

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

Logins using username/password Active Directory/LDAP, Windows Azure AD and ADF

Parameters:

  • username (string) —

    Username

  • password (string) —

    User’s password

  • scope (string) —

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

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

    Token’s id

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

    Connection name. Works for database connections, passwordless connections,

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
 
# 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,
    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/ro', request_params)
end

#logout_url(return_to) ⇒ url

Returns an logout URL, triggers the logout flow.

Parameters:

  • return_to (string) —

    Url to redirect after authorization

Returns:

  • (url) —

    Logout URL.

See Also:



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

def logout_url(return_to)
  request_params = {
    returnTo: return_to
  }

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

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

Retrives 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

Gets the user tokens using the code obtained through passive authentication in the specified connection

Parameters:

  • 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’

  • redirect_uri (string) —

    Url to redirect after authorization

  • redirect_uri (string) —

    The access code obtained through passive authentication

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

Logins 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:



142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 142

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

Refreshes 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:



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

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

Retrives the SAML 2.0 metadata

Returns:

  • (xml) —

    SAML 2.0 metadata

See Also:



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

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

#samlp_url(connection = UP_AUTH) ⇒ url

Returns a samlp URL. The SAML Request AssertionConsumerServiceURL will be used to POST back the assertion and it has to match with the application callback URL.

Parameters:

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

    to login with a specific provider.

Returns:

  • (url) —

    samlp URL.

See Also:



311
312
313
314
315
316
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 311

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

Signup using username/password

Parameters:

  • email (string) —

    User email

  • password (string) —

    User’s password

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

    Connection name. Works for database connections.

Returns:

  • (json) —

    Returns the created user

Raises:

See Also:



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

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 = {
    client_id:  @client_id,
    email:      email,
    connection: connection_name,
    password:   password
  }
  post('/dbconnections/signup', request_params)
end

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

Start passwordless workflow sending an email

Parameters:

  • email (string) —

    User email

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

    Defaults to ‘link’. Can be ‘code’. You can then authenticate with this user opening the link

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

    Append/override parameters to the link (like scope, redirect_uri, protocol, etc.)

Raises:

See Also:



112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 112

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 = {
    client_id:   @client_id,
    connection:  'email',
    email:       email,
    send:        send,
    authParams:  auth_params
  }
  post('/passwordless/start', request_params)
end

#start_passwordless_sms_flow(phone_number) ⇒ Object

Start passwordless workflow sending a SMS message

Parameters:

  • phone_number (string) —

    User’s phone number.

Raises:

See Also:



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

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

#token_info(id_token) ⇒ Object

Validates a JSON Web Token (signature and expiration)

Parameters:

  • id_token (string) —

    Token’s id.

Returns:

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

Raises:

See Also:



174
175
176
177
178
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 174

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

Unlinks a User

Parameters:

  • access_token (string) —

    Logged-in user access token

  • user_id (string) —

    User Id

Raises:

See Also:



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

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

Returns the user information based on the Auth0 access token.

Returns:

  • (json) —

    User information based on the Auth0 access token

See Also:



271
272
273
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 271

def 
  get('/userinfo')
end

#wsfed_metadata ⇒ xml

Retrives the WS-Federation metadata

Returns:

  • (xml) —

    Federation Metadata

See Also:



166
167
168
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 166

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

#wsfed_url(connection = UP_AUTH) ⇒ url

Returns a wsfed URL.

Parameters:

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

    to login with a specific provider.

Returns:

  • (url) —

    wsfed URL.

See Also:



322
323
324
325
326
327
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 322

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