From f015b4bc6a51ef0fb59fae2fcceae379b7ef6d7d Mon Sep 17 00:00:00 2001 From: Josh Cunningham Date: Fri, 20 Jul 2018 12:40:49 -0700 Subject: [PATCH 1/2] Add deprecation notices --- lib/auth0/api/authentication_endpoints.rb | 176 +++++++++++----------- 1 file changed, 91 insertions(+), 85 deletions(-) diff --git a/lib/auth0/api/authentication_endpoints.rb b/lib/auth0/api/authentication_endpoints.rb index deaced42..adf7858b 100644 --- a/lib/auth0/api/authentication_endpoints.rb +++ b/lib/auth0/api/authentication_endpoints.rb @@ -138,7 +138,93 @@ def start_passwordless_sms_flow(phone_number) post('/passwordless/start', request_params) end + # Retrive SAML 2.0 metadata XMLfor an Application. + # @see https://auth0.com/docs/api/authentication#get-metadata + # @return [xml] SAML 2.0 metadata + def saml_metadata + get("/samlp/metadata/#{@client_id}") + end + + # Retrieve WS-Federation metadata XML for a tenant. + # @see https://auth0.com/docs/api/authentication#get-metadata36 + # @return [xml] WS-Federation metadata + def wsfed_metadata + get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml') + end + + # Return the user information based on the Auth0 access token. + # @see https://auth0.com/docs/api/authentication#get-user-info + # @return [json] User information based on the Auth0 access token + def user_info + get('/userinfo') + end + + # Return an authorization URL. + # @see https://auth0.com/docs/api/authentication#authorization-code-grant + # @param redirect_uri [string] URL to redirect after authorization + # @param options [hash] Can contain response_type, connection, state and additional_parameters. + # @return [url] Authorization URL. + 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 + + # Returns an Auth0 logout URL with a return URL. + # @see https://auth0.com/docs/api/authentication#logout + # @see https://auth0.com/docs/logout + # @param return_to [string] URL to redirect after logout. + # @param include_client [bool] Include the client_id in the logout URL. + # @param federated [boolean] Perform a federated logout. + # @return [url] Logout URI + 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 + + # 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. + # @see https://auth0.com/docs/api/authentication#accept-request + # @param connection [string] Connection to use; empty to show all + # @return [url] SAMLP URL + 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 + + # Return a WS-Federation URL. + # @see https://auth0.com/docs/api/authentication#accept-request35 + # @param connection [string] Connection to use; empty to show all + # @return [url] WS-Federation URL + 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 + # Login using phone number + verification code. + # @deprecated 4.5.0 - Legacy authentication pipeline; use a Password Grant instead # @see https://auth0.com/docs/api/authentication#resource-owner # @param phone_number [string] User's phone number. # @param code [string] Verification code. @@ -157,21 +243,8 @@ def phone_login(phone_number, code, scope = 'openid') post('/oauth/ro', request_params) end - # Retrive SAML 2.0 metadata XMLfor an Application. - # @see https://auth0.com/docs/api/authentication#get-metadata - # @return [xml] SAML 2.0 metadata - def saml_metadata - get("/samlp/metadata/#{@client_id}") - end - - # Retrieve WS-Federation metadata XML for a tenant. - # @see https://auth0.com/docs/api/authentication#get-metadata36 - # @return [xml] WS-Federation metadata - def wsfed_metadata - get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml') - end - # Validate a JSON Web Token (signature and expiration). + # @deprecated 4.5.0 - legacy endpoint, use /userinfo instead. # @see https://auth0.com/docs/api/authentication#get-token-info # @param id_token [string] ID Token to use # @return User information associated with the user id (sub property) of the token. @@ -182,6 +255,7 @@ def token_info(id_token) end # Refresh a delegation token. + # @deprecated 4.5.0 - feature is disabled, no replacement currently. # @see https://auth0.com/docs/api/authentication#delegation # @param refresh_token [string] Token to refresh # @param target [string] Target to sign the new token. @@ -204,6 +278,7 @@ def refresh_delegation(refresh_token, target, scope = 'openid', api_type = 'app' end # Retrieve a delegation token. + # @deprecated 4.5.0 - feature is disabled, no replacement currently. # @see https://auth0.com/docs/api/authentication#delegation # @param id_token [string] Token's id. # @param target [string] Target to sign the new token. @@ -226,6 +301,7 @@ def delegation(id_token, target, scope = 'openid', api_type = 'app', extra_param end # Retrieve an impersonation URL to login as another user. + # @deprecated 4.5.0 - feature is disabled. # @see https://auth0.com/docs/api/authentication#impersonation # @param user_id [string] Impersonate user id # @param app_client_id [string] Application client id @@ -257,6 +333,7 @@ def impersonate(user_id, app_client_id, impersonator_id, options) # rubocop:enable Metrics/MethodLength, Metrics/AbcSize # Unlink a user's account from the identity provider. + # @deprecated 4.5.0 - endpoint is disabled, use the Management API instead. # @see https://auth0.com/docs/api/authentication#unlink # @param access_token [string] Logged-in user access token # @param user_id [string] User Id @@ -270,77 +347,6 @@ def unlink_user(access_token, user_id) post('/unlink', request_params) end - # Return the user information based on the Auth0 access token. - # @see https://auth0.com/docs/api/authentication#get-user-info - # @return [json] User information based on the Auth0 access token - def user_info - get('/userinfo') - end - - # Return an authorization URL. - # @see https://auth0.com/docs/api/authentication#authorization-code-grant - # @param redirect_uri [string] URL to redirect after authorization - # @param options [hash] Can contain response_type, connection, state and additional_parameters. - # @return [url] Authorization URL. - 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 - - # Returns an Auth0 logout URL with a return URL. - # @see https://auth0.com/docs/api/authentication#logout - # @see https://auth0.com/docs/logout - # @param return_to [string] URL to redirect after logout. - # @param include_client [bool] Include the client_id in the logout URL. - # @param federated [boolean] Perform a federated logout. - # @return [url] Logout URI - 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 - - # 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. - # @see https://auth0.com/docs/api/authentication#accept-request - # @param connection [string] Connection to use; empty to show all - # @return [url] SAMLP URL - 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 - - # Return a WS-Federation URL. - # @see https://auth0.com/docs/api/authentication#accept-request35 - # @param connection [string] Connection to use; empty to show all - # @return [url] WS-Federation URL - 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 - private # Build a URL query string from a hash. From 040f17e6c2e74bb2c9035489388e11819eab6d5c Mon Sep 17 00:00:00 2001 From: Josh Cunningham Date: Mon, 23 Jul 2018 13:33:58 -0700 Subject: [PATCH 2/2] PR feedback --- lib/auth0/api/authentication_endpoints.rb | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/lib/auth0/api/authentication_endpoints.rb b/lib/auth0/api/authentication_endpoints.rb index adf7858b..73a63e02 100644 --- a/lib/auth0/api/authentication_endpoints.rb +++ b/lib/auth0/api/authentication_endpoints.rb @@ -138,7 +138,7 @@ def start_passwordless_sms_flow(phone_number) post('/passwordless/start', request_params) end - # Retrive SAML 2.0 metadata XMLfor an Application. + # Retrive SAML 2.0 metadata XML for an Application. # @see https://auth0.com/docs/api/authentication#get-metadata # @return [xml] SAML 2.0 metadata def saml_metadata @@ -224,7 +224,8 @@ def wsfed_url(connection = UP_AUTH) end # Login using phone number + verification code. - # @deprecated 4.5.0 - Legacy authentication pipeline; use a Password Grant instead + # @deprecated 4.5.0 - Legacy authentication pipeline; use a Password Grant + # instead - https://auth0.com/docs/api-auth/tutorials/password-grant # @see https://auth0.com/docs/api/authentication#resource-owner # @param phone_number [string] User's phone number. # @param code [string] Verification code. @@ -244,7 +245,7 @@ def phone_login(phone_number, code, scope = 'openid') end # Validate a JSON Web Token (signature and expiration). - # @deprecated 4.5.0 - legacy endpoint, use /userinfo instead. + # @deprecated 4.5.0 - Legacy endpoint, use /userinfo instead. # @see https://auth0.com/docs/api/authentication#get-token-info # @param id_token [string] ID Token to use # @return User information associated with the user id (sub property) of the token. @@ -255,7 +256,8 @@ def token_info(id_token) end # Refresh a delegation token. - # @deprecated 4.5.0 - feature is disabled, no replacement currently. + # @deprecated 4.5.0 - Feature is disabled, no replacement currently; see + # https://auth0.com/docs/api-auth/tutorials/adoption/delegation # @see https://auth0.com/docs/api/authentication#delegation # @param refresh_token [string] Token to refresh # @param target [string] Target to sign the new token. @@ -278,7 +280,8 @@ def refresh_delegation(refresh_token, target, scope = 'openid', api_type = 'app' end # Retrieve a delegation token. - # @deprecated 4.5.0 - feature is disabled, no replacement currently. + # @deprecated 4.5.0 - Feature is disabled, no replacement currently; see + # https://auth0.com/docs/api-auth/tutorials/adoption/delegation # @see https://auth0.com/docs/api/authentication#delegation # @param id_token [string] Token's id. # @param target [string] Target to sign the new token. @@ -301,7 +304,7 @@ def delegation(id_token, target, scope = 'openid', api_type = 'app', extra_param end # Retrieve an impersonation URL to login as another user. - # @deprecated 4.5.0 - feature is disabled. + # @deprecated 4.5.0 - Feature is disabled. # @see https://auth0.com/docs/api/authentication#impersonation # @param user_id [string] Impersonate user id # @param app_client_id [string] Application client id @@ -333,7 +336,8 @@ def impersonate(user_id, app_client_id, impersonator_id, options) # rubocop:enable Metrics/MethodLength, Metrics/AbcSize # Unlink a user's account from the identity provider. - # @deprecated 4.5.0 - endpoint is disabled, use the Management API instead. + # @deprecated 4.5.0 - Endpoint is disabled in favor of the Management API; + # see https://auth0.com/docs/migrations/guides/account-linking # @see https://auth0.com/docs/api/authentication#unlink # @param access_token [string] Logged-in user access token # @param user_id [string] User Id