descope 1.0.6 → 1.1.0

data/README.md

@@ -5,7 +5,7 @@ for a backend written in Ruby. You can read more on the [Descope Website](https:
 
 ## Requirements
 
-The SDK supports Ruby 3.2 and above.
+The SDK supports Ruby 3.3.0 and above.
 
 ## Installing the SDK
 
@@ -37,6 +37,17 @@ Be aware that only the management key is truncated, and the JWT responses are pr
 
 Do not run with log level debug on Production!
 
+### Logging
+
+You can customize logging behavior:
+
+```ruby
+# Use your application's logger
+descope_client = Descope::Client.new(
+  project_id: '<project_id>',
+  logger: Rails.logger  # or any Logger-compatible object
+)
+```
 
 ## Authentication Methods
 These sections show how to use the SDK to perform various authentication/authorization functions:
@@ -45,13 +56,14 @@ These sections show how to use the SDK to perform various authentication/authori
 2. [Magic Link](#magic-link)
 3. [Enchanted Link](#enchanted-link)
 4. [OAuth](#oauth)
-5. [SSO/SAML](#ssosaml)
+5. [SSO (SAML / OIDC)](#sso-saml-oidc)
 6. [TOTP Authentication](#totp-authentication)
 7. [Passwords](#passwords)
 8. [Session Validation](#session-validation)
 9. [Roles & Permission Validation](#roles-permission-validation)
 10. [Tenant selection](#tenant-selection)
-11. [Logging Out](#logging-out)
+11. [Signing Out](#signing-out)
+12. [History](#history)
 
 ## API Management Function
 
@@ -66,10 +78,12 @@ These sections show how to use the SDK to perform permission and user management
 7. [Query SSO Groups](#query-sso-groups)
 8. [Manage Flows](#manage-flows-and-theme)
 9. [Manage JWTs](#manage-jwts)
-10. [Embedded links](#embedded-links)
-11. [Audit](#audit)
-12. [Manage ReBAC Authz](#manage-rebac-authz)
-13. [Manage Project](#manage-project)
+10. [Impersonate](#impersonate)
+11. [Embedded links](#embedded-links)
+12. [Audit](#audit)
+13. [Manage ReBAC Authz](#manage-rebac-authz)
+14. [Manage Project](#manage-project)
+15. [Manage SSO Applications](#manage-sso-applications)
 
 If you wish to run any of our code examples and play with them, check out our [Code Examples](#code-examples) section.
 
@@ -79,7 +93,7 @@ For rate limiting information, please confer to the [API Rate Limits](#api-rate-
 
 ### OTP Authentication
 
-Send a user a one-time password (OTP) using your preferred delivery method (email/SMS/Voice call). An email address or phone number must be provided accordingly.
+Send a user a one-time password (OTP) using your preferred delivery method (Email/SMS/Voice call). An email address or phone number must be provided accordingly.
 
 The user can either `sign up`, `sign in` or `sign up or in`
 
@@ -88,32 +102,32 @@ The user can either `sign up`, `sign in` or `sign up or in`
 # For sign up either phone or email is required
 email = 'desmond@descope.com'
 user = {'name': 'Desmond Copeland', 'phone': '212-555-1234', 'email': email}
-masked_address = descope_client.otp_sign_up(method: DeliveryMethod.EMAIL, login_id: 'someone@example.com', user: user)
+masked_address = descope_client.otp_sign_up(method: Descope::Mixins::Common::DeliveryMethod::EMAIL, login_id: 'someone@example.com', user: user)
 ```
 
 The user will receive a code using the selected delivery method. Verify that code using:
 
 ```ruby
 jwt_response = descope_client.otp_verify_code(
-    method: DeliveryMethod.EMAIL, login_id: 'someone@example.com', code: '123456'
+    method: Descope::Mixins::Common::DeliveryMethod::EMAIL, login_id: 'someone@example.com', code: '123456'
 )
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
 
 ### Magic Link
 
-Send a user a Magic Link using your preferred delivery method (_email / SMS_).
-The Magic Link will redirect the user to page where the its token needs to be verified.
+Send a user a Magic Link using your preferred delivery method (Email / SMS).
+The Magic Link will redirect the user to page where the token needs to be verified.
 This redirection can be configured in code, or generally in the [Descope Console](https://app.descope.com/settings/authentication/magiclink)
 
 The user can either `sign up`, `sign in` or `sign up or in`
 
 ```ruby
 masked_address = descope_client.magiclink_sign_up_or_in(
-    method: DeliveryMethod.EMAIL,
+    method: Descope::Mixins::Common::DeliveryMethod::EMAIL,
     login_id: 'desmond@descope.com',
     uri: 'https://myapp.com/verify-magic-link', # Set redirect URI here or via console
 )
@@ -123,8 +137,8 @@ To verify a magic link, your redirect page must call the validation function on
 
 ```ruby
 jwt_response = descope_client.magiclink_verify_token('token-here')
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
@@ -143,7 +157,7 @@ This method is similar to [Magic Link](#magic-link) but differs in two major way
 - This supports cross-device clicking, meaning the user can try to log in on one device,
   like a computer, while clicking the link on another device, for instance a mobile phone.
 
-The Enchanted Link will redirect the user to page where the its token needs to be verified.
+The Enchanted Link will redirect the user to a page where the token needs to be verified.
 This redirection can be configured in code per request, or set globally in the [Descope Console](https://app.descope.com/settings/authentication/enchantedlink).
 
 The user can either `sign up`, `sign in` or `sign up or in`
@@ -162,6 +176,9 @@ After sending the link, you must poll to receive a valid session using the `pend
 the previous step. A valid session will be returned only after the user clicks the right link.
 
 ```ruby
+
+pending_ref = res['pendingRef']
+
 def poll_for_session(descope_client, pending_ref)
   max_tries = 15
   i = 0
@@ -175,15 +192,15 @@ def poll_for_session(descope_client, pending_ref)
       jwt_response = descope_client.enchanted_link_get_session(pending_ref)
       done = true
     rescue Descope::AuthException, Descope::Unauthorized => e
-      puts 'Failed pending session, err: #{e}'
+      puts "Failed pending session, err: #{e}"
       nil
     end
 
     if jwt_response
-      puts 'jwt_response: #{jwt_response}'
+      puts "jwt_response: #{jwt_response}"
       refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME]['jwt']
 
-      puts 'refresh_token: #{refresh_token}'
+      puts "refresh_token: #{refresh_token}"
       puts :'Done logging out!'
       descope_client.sign_out(refresh_token)
       puts 'User logged out'
@@ -202,7 +219,8 @@ begin
     descope_client.enchanted_link_verify_token(token=token)
     # Token is valid
 rescue AuthException => e
-    # Token is invalid
+  # Token is invalid
+  puts "Failed to verify token, err: #{e}"
 end
 ```
 
@@ -224,13 +242,13 @@ The user will authenticate with the authentication provider, and will be redirec
 
 ```ruby
 jwt_response = descope_client.oauth_exchange_token(code)
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
 
-### SSO/SAML
+### SSO (SAML / OIDC)
 
 Users can authenticate to a specific tenant using SAML or Single Sign On. Configure your SSO/SAML settings on the [Descope console](https://app.descope.com/settings/authentication/sso). To start a flow call:
 
@@ -247,8 +265,8 @@ The user will authenticate with the authentication provider configured for that
 
 ```ruby
 jwt_response = descope_client.saml_exchange_token(code)
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
@@ -256,7 +274,7 @@ The session and refresh JWTs should be returned to the caller, and passed with e
 ### TOTP Authentication
 
 The user can authenticate using an authenticator app, such as Google Authenticator.
-Sign up like you would using any other authentication method. The sign up response
+Sign up like you would use any other authentication method. The sign-up response
 will then contain a QR code `image` that can be displayed to the user to scan using
 their mobile device camera app, or the user can enter the `key` manually or click
 on the link provided by the `provisioning_url`.
@@ -267,7 +285,7 @@ Existing users can add TOTP using the `update` function.
 # Every user must have a login ID. All other user information is optional
 email = 'desmond@descope.com'
 user = {name: 'Desmond Copeland', phone: '212-555-1234', email: 'someone@example.com'}
-totp_response = descope_client.totp_sign_up(method: DeliveryMethod.EMAIL, login_id: 'someone@example.com', user: user)
+totp_response = descope_client.totp_sign_up(method: Descope::Mixins::Common::DeliveryMethod::EMAIL, login_id: 'someone@example.com', user: user)
 
 # Use one of the provided options to have the user add their credentials to the authenticator
 provisioning_url = totp_response['provisioningURL']
@@ -285,8 +303,8 @@ jwt_response = descope_client.totp_sign_in_code(
     login_id: 'someone@example.com',
     code: '123456' # Code from authenticator app
 )
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
@@ -307,16 +325,16 @@ user = {
     email: login_id,
 }
 jwt_response = descope_client.password_sign_up(login_id:, password:, user:)
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 The user can later sign in using the same login_id and password.
 
 ```ruby
 jwt_response = descope_client.password_sign_in(login_id:, password:)
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on [session validation](#session-validation)
@@ -325,7 +343,7 @@ In case the user needs to update their password, one of two methods are availabl
 
 **Changing Passwords**
 
-_NOTE: send_reset will only work if the user has a validated email address. Otherwise password reset prompts cannot be sent._
+_NOTE: send_reset will only work if the user has a validated email address. Otherwise, password reset prompts cannot be sent._
 
 In the [password authentication method](https://app.descope.com/settings/authentication/password) in the Descope console, it is possible to define which alternative authentication method can be used in order to authenticate the user, in order to reset and update their password.
 
@@ -353,8 +371,8 @@ Alternatively, it is also possible to replace an existing active password with a
 ```ruby
 # Replaces the user's current password with a new one
 jwt_response = descope_client.password_replace(login_id: 'login', old_password: '1234', new_password: '4567')
-session_token = jwt_response['sessionJwt']
-refresh_token = jwt_response['refreshJwt']
+session_token = jwt_response[Descope::Mixins::Common::SESSION_TOKEN_NAME].fetch('jwt')
+refresh_token = jwt_response[Descope::Mixins::Common::REFRESH_SESSION_TOKEN_NAME].fetch('jwt')
 ```
 
 ### Session Validation
@@ -380,19 +398,19 @@ jwt_response = descope_client.validate_and_refresh_session('session_token', 'ref
 
 Choose the right session validation and refresh combination that suits your needs.
 
-Note: all those validation apis can receive an optional 'audience' parameter that should be provided when using jwt that has the 'aud' claim)
+Note: all those validation apis can receive an optional 'audience' parameter that should be provided when using jwt that has the 'aud' claim.
 
 Refreshed sessions return the same response as is returned when users first sign up / log in,
-containing the session and refresh tokens, as well as all of the JWT claims.
+containing the session and refresh tokens, as well as all the JWT claims.
 Make sure to return the tokens from the response to the client, or updated the cookie if you're using it.
 
 Usually, the tokens can be passed in and out via HTTP headers or via a cookie.
 The implementation can defer according to your framework of choice. See our [examples](#code-examples) for a few examples.
 
-If Roles & Permissions are used, validate them immediately after validating the session. See the [next section](#roles--permission-validation)
+If Roles & Permissions are used, validate them immediately after validating the session. See the [next section](#roles-permission-validation)
 for more information.
 
-### Roles & Permission Validation
+### Roles Permission Validation
 
 When using Roles & Permission, it's important to validate the user has the required
 authorization immediately after making sure the session is valid. Taking the `jwt_response`
@@ -459,13 +477,23 @@ After calling this function, you must invalidate or remove any cookies you have
 descope_client.sign_out('refresh_token')
 ```
 
-It is also possible to sign the user out of all the devices they are currently signed-in with. Calling `logout_all` will
+It is also possible to sign the user out of all the devices they are currently signed in with. Calling `logout_all` will
 invalidate all user's refresh tokens. After calling this function, you must invalidate or remove any cookies you have created.
 
 ```ruby
 descope_client.sign_out_all('refresh_token')
 ```
 
+### History
+You can get the current session user history.
+The request requires a valid refresh token.
+
+```ruby
+users_history_resp = descope_client.history(refresh_token)
+for user_history in users_history_resp:
+    # Do something
+```
+
 ## Management API
 
 It is very common for some form of management or automation to be required. These can be performed
@@ -570,6 +598,16 @@ descope_client.update_user(
         user_tenants: client.associated_tenants_to_hash_array(associated_tenants)
 )
 
+# Patch all user attribute in one api call
+descope_client.patch_user(
+        login_id: 'desmond@descope.com',
+        email: 'desmond@descope.com',
+        given_name: 'Desmond',
+        family_name: 'Copeland',
+        display_name: 'Desmond Copeland',
+        user_tenants: client.associated_tenants_to_hash_array(associated_tenants)
+)
+
 # Update explicit data for a user rather than overriding all fields
 descope_client.update_login_id(
         login_id: 'desmond@descope.com',
@@ -760,7 +798,7 @@ descope_client.update_role(
 descope_client.delete_role(name: 'My Updated Role',  tenant_id: 'The tenant ID to which this role is associated, leave empty, if role is a global one')
 
 # Load all roles
-roles_resp = descope_client.load_all_roles()
+roles_resp = descope_client.load_all_roles
 roles = roles_resp['roles']
     roles.each do |role|
       # Do something
@@ -769,11 +807,13 @@ roles = roles_resp['roles']
 ```
 
 # Search roles
+
+```ruby
 roles_resp = descope_client.search_roles(
-    names: ['role1', 'role2'], # Search for roles with the names 'role1' and 'role2'
-    role_name_like: 'role', # Search for roles that contain the string 'role'
-    tenant_ids: ['tenant1', 'tenant2'], # Search for roles that are associated with the tenants 'tenant1' and 'tenant2'
-    permission_names: ['permission1', 'permission2'] # Search for roles that have the permissions 'permission1' and 'permission2'
+  names: %w[role1 role2], # Search for roles with the names 'role1' and 'role2'
+  role_name_like: 'role', # Search for roles that contain the string 'role'
+  tenant_ids: %w[tenant1 tenant2], # Search for roles that are associated with the tenants 'tenant1' and 'tenant2'
+  permission_names: %w[permission1 permission2] # Search for roles that have the permissions 'permission1' and 'permission2'
 )
 
 roles = roles_resp['roles']
@@ -1124,6 +1164,13 @@ descope_client.create_test_user(
         user_tenants: client.associated_tenants_to_hash_array(associated_tenants)
 )
 
+# Search all test users, optionally according to tenant and/or role filter
+# results can be paginated using the limit and page parameters
+users_resp = descope_client.search_all_test_users()
+users = users_resp["users"]
+users.each do |user|
+  # Do something
+
 # Now test user got created, and this user will be available until you delete it,
 # you can use any management operation for test user CRUD.
 # You can also delete all test users.
@@ -1131,14 +1178,14 @@ descope_client.delete_all_test_users
 
 # OTP code can be generated for test user, for example:
 resp = descope_client.generate_otp_for_test_user(
-        method: DeliveryMethod.EMAIL, login_id: 'login-id'
+        method: Descope::Mixins::Common::DeliveryMethod::EMAIL, login_id: 'login-id'
 )
 code = resp['code']
 # Now you can verify the code is valid (using descope_client.*.verify for example)
 
 # Same as OTP, magic link can be generated for test user, for example:
 resp = descope_client.generate_magic_link_for_test_user(
-        method: DeliveryMethod.EMAIL, 
+        method: Descope::Mixins::Common::DeliveryMethod::EMAIL,
         login_id: 'login-id',
 )
 link = resp['link']
@@ -1151,6 +1198,78 @@ link = resp['link']
 pending_ref = resp['pendingRef']
 ```
 
+### Manage SSO Applications
+
+You can create, update, delete or load SSO applications:
+
+```ruby
+descope_client.create_sso_oidc_app(
+  name: "My First sso app",
+  login_page_url: "https://dummy.com/login",
+  id: "my-custom-id", # this is optional
+)
+
+# Create SAML sso application
+descope_client.create_saml_application(
+  name: "My First sso app",
+  login_page_url: "https://dummy.com/login",
+  id: "my-custom-id", # this is optional
+  use_metadata_info: true,
+  metadata_url: "https://dummy.com/metadata",
+  default_relay_state: "relayState",
+  force_authentication: false,
+  logout_redirect_url: "https://dummy.com/logout",
+)
+```
+
+# Update OIDC sso application
+# Update will override all fields as is. Use carefully.
+
+```ruby
+descope_client.update_sso_oidc_app(
+  id: "my-custom-id",
+  name: "My First sso app",
+  login_page_url: "https://dummy.com/login",
+)
+````
+
+# Update SAML sso application
+# Update will override all fields as is. Use carefully.
+
+```ruby
+descope_client.update_saml_application(
+  id: "my-custom-id",
+  name: "My First sso app",
+  login_page_url: "https://dummy.com/login",
+  use_metadata_info: false,
+  entity_id: "ent1234",
+  acs_url: "https://dummy.com/acs",
+  certificate: "my cert"
+)
+```
+
+# SSO application deletion cannot be undone. Use carefully.
+
+```ruby
+descope_client.delete_sso_app('my-custom-id')
+```
+
+# Load SSO application by id
+
+```ruby
+descope_client.load_sso_app('my-custom-id')
+```
+
+# Load all SSO applications
+
+```ruby
+resp = descope_client.load_all_sso_apps
+resp["apps"].each do |app|
+  # Do something
+end
+```
+
+
 ## API Rate Limits
 
 Handle API rate limits by comparing the exception to the APIRateLimitExceeded exception, which includes the RateLimitParameters map with the key 'Retry-After.' This key indicates how many seconds until the next valid API call can take place.
@@ -1158,7 +1277,7 @@ Handle API rate limits by comparing the exception to the APIRateLimitExceeded ex
 ```ruby
 begin
     descope_client.magiclink_sign_up_or_in(
-        method: DeliveryMethod.EMAIL,
+        method: Descope::Mixins::Common::DeliveryMethod::EMAIL,
         login_id: 'desmond@descope.com',
         uri: 'https://myapp.com/verify-magic-link',
     )

data/examples/ruby-on-rails-api/descope/Gemfile

@@ -3,12 +3,12 @@ source "https://rubygems.org"
 ruby "3.3.0"
 
 # Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
-gem "rails", "~> 7.1.3.2"
+gem "rails", "~> 7.1.3.3"
 
 gem 'descope', path: '../../../..'
 
 # The original asset pipeline for Rails [https://github.com/rails/sprockets-rails]
-gem "sprockets-rails"
+gem "sprockets-rails", ">= 3.5.0"
 
 # Use sqlite3 as the database for Active Record
 gem "sqlite3", "~> 1.4"
@@ -17,19 +17,19 @@ gem "sqlite3", "~> 1.4"
 gem "puma", ">= 5.0"
 
 # Bundle and transpile JavaScript [https://github.com/rails/jsbundling-rails]
-gem "jsbundling-rails"
+gem "jsbundling-rails", ">= 1.3.1"
 
 # Hotwire's SPA-like page accelerator [https://turbo.hotwired.dev]
-gem "turbo-rails"
+gem "turbo-rails", ">= 2.0.6"
 
 # Hotwire's modest JavaScript framework [https://stimulus.hotwired.dev]
-gem "stimulus-rails"
+gem "stimulus-rails", ">= 1.3.4"
 
 # Bundle and process CSS [https://github.com/rails/cssbundling-rails]
-gem "cssbundling-rails"
+gem "cssbundling-rails", ">= 1.4.1"
 
 # Build JSON APIs with ease [https://github.com/rails/jbuilder]
-gem "jbuilder"
+gem "jbuilder", ">= 2.12.0"
 
 # Use Redis adapter to run Action Cable in production
 # gem "redis", ">= 4.0.1"
@@ -63,7 +63,7 @@ group :development do
 
   # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
   # gem "spring"
-  gem 'rubocop-rails', '2.24.1', require: false
+  gem 'rubocop-rails', '2.25.0', require: false
   gem "rdoc", ">= 6.6.3.1", require: false
 end
 

data/examples/ruby-on-rails-api/descope/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../../../..
   specs:
-    descope (1.0.5)
+    descope (1.0.6)
       addressable (~> 2.8)
       jwt (~> 2.7)
       rest-client (~> 2.1)