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'
JWT_BEARER = 
'urn:ietf:params:oauth:grant-type:jwt-bearer'

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.

See Also:



252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 252

def authorization_url(redirect_uri, options = {})
  fail Auth0::InvalidParameter, 'Must supply a valid redirect_uri' if redirect_uri.to_s.empty?
  request_params = {
    client_id: @client_id,
    response_type: options.fetch(:connection, 'code'),
    connection: options.fetch(:connection, nil),
    redirect_url: redirect_uri,
    state: options.fetch(:state, 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.

See Also:



74
75
76
77
78
79
80
81
82
83
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 74

def change_password(email, password, connection_name = UP_AUTH)
  fail 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

See Also:



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

def delegation(id_token, target, scope = 'openid', api_type = 'app', extra_parameters = {})
  fail 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

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

See Also:



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

def impersonate(user_id, app_client_id, impersonator_id, options)
  fail Auth0::InvalidParameter, 'Must supply a valid user_id' if user_id.to_s.empty?
  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, '')
    }
  }
  post("/users/#{user_id}/impersonate", request_params)
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

See Also:



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

def (username, password, id_token = nil, connection_name = UP_AUTH, options = {})
  fail Auth0::InvalidParameter, 'Must supply a valid username' if username.to_s.empty?
  fail 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:



269
270
271
272
273
274
275
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 269

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

#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

See Also:



119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 119

def (phone_number, code, scope = 'openid')
  fail Auth0::InvalidParameter, 'Must supply a valid phone number' if phone_number.to_s.empty?
  fail 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

See Also:



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

def refresh_delegation(refresh_token, target, scope = 'openid', api_type = 'app', extra_parameters = {})
  fail 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(client_id) ⇒ xml

Retrives the SAML 2.0 metadata

Parameters:

  • client_id (string) —

    Client id

Returns:

  • (xml) —

    SAML 2.0 metadata

See Also:



137
138
139
140
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 137

def saml_metadata(client_id)
  fail Auth0::InvalidParameter, 'Must supply a valid client_id' if client_id.to_s.empty?
  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:



282
283
284
285
286
287
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 282

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

See Also:



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

def (email, password, connection_name = UP_AUTH)
  fail Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
  fail 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.)

See Also:



90
91
92
93
94
95
96
97
98
99
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 90

def start_passwordless_email_flow(email, send = 'link', auth_params = {})
  fail Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
  request_params = {
    client_id:    @client_id,
    email:        email,
    send:         send,
    auth_params:  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.

See Also:



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

def start_passwordless_sms_flow(phone_number)
  fail 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.

See Also:



153
154
155
156
157
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 153

def token_info(id_token)
  fail 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

See Also:



230
231
232
233
234
235
236
237
238
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 230

def unlink_user(access_token, user_id)
  fail Auth0::InvalidParameter, 'Must supply a valid access_token' if access_token.to_s.empty?
  fail 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:



243
244
245
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 243

def 
  get('/userinfo')
end

#wsfed_metadata ⇒ xml

Retrives the WS-Federation metadata

Returns:

  • (xml) —

    Federation Metadata

See Also:



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

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:



293
294
295
296
297
298
 
# File 'lib/auth0/api/authentication_endpoints.rb', line 293

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