stytch 6.4.0 → 7.2.0

data/lib/stytch/b2b_sessions.rb

@@ -6,14 +6,32 @@
 # or your changes may be overwritten later!
 # !!!
 
+require 'jwt'
+require 'json/jwt'
+require_relative 'errors'
 require_relative 'request_helper'
 
 module StytchB2B
   class Sessions
     include Stytch::RequestHelper
 
-    def initialize(connection)
+    def initialize(connection, project_id, policy_cache)
       @connection = connection
+
+      @policy_cache = policy_cache
+      @project_id = project_id
+      @cache_last_update = 0
+      @jwks_loader = lambda do |options|
+        @cached_keys = nil if options[:invalidate] && @cache_last_update < Time.now.to_i - 300
+        @cached_keys ||= begin
+          @cache_last_update = Time.now.to_i
+          keys = []
+          get_jwks(project_id: @project_id)['keys'].each do |r|
+            keys << r
+          end
+          { keys: keys }
+        end
+      end
     end
 
     # Retrieves all active Sessions for a Member.
@@ -41,18 +59,26 @@ module StytchB2B
       organization_id:,
       member_id:
     )
+      headers = {}
       query_params = {
         organization_id: organization_id,
         member_id: member_id
       }
       request = request_with_query_params('/v1/b2b/sessions', query_params)
-      get_request(request)
+      get_request(request, headers)
     end
 
     # Authenticates a Session and updates its lifetime by the specified `session_duration_minutes`. If the `session_duration_minutes` is not specified, a Session will not be extended. This endpoint requires either a `session_jwt` or `session_token` be included in the request. It will return an error if both are present.
     #
     # You may provide a JWT that needs to be refreshed and is expired according to its `exp` claim. A new JWT will be returned if both the signature and the underlying Session are still valid.
     #
+    # If an `authorization_check` object is passed in, this method will also check if the Member is authorized to perform the given action on the given Resource in the specified Organization. A Member is authorized if their Member Session contains a Role, assigned [explicitly or implicitly](https://stytch.com/docs/b2b/guides/rbac/role-assignment), with adequate permissions.
+    # In addition, the `organization_id` passed in the authorization check must match the Member's Organization.
+    #
+    # If the Member is not authorized to perform the specified action on the specified Resource, or if the
+    # `organization_id` does not match the Member's Organization, a 403 error will be thrown.
+    # Otherwise, the response will contain a list of Roles that satisfied the authorization check.
+    #
     # == Parameters:
     # session_token::
     #   A secret token for a given Stytch Session.
@@ -78,6 +104,21 @@ module StytchB2B
     #   delete a key, supply a null value. Custom claims made with reserved claims (`iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`) will be ignored.
     #   Total custom claims size cannot exceed four kilobytes.
     #   The type of this field is nilable +object+.
+    # authorization_check::
+    #   If an `authorization_check` object is passed in, this endpoint will also check if the Member is
+    #   authorized to perform the given action on the given Resource in the specified Organization. A Member is authorized if
+    #   their Member Session contains a Role, assigned
+    #   [explicitly or implicitly](https://stytch.com/docs/b2b/guides/rbac/role-assignment), with adequate permissions.
+    #   In addition, the `organization_id` passed in the authorization check must match the Member's Organization.
+    #
+    #   The Roles on the Member Session may differ from the Roles you see on the Member object - Roles that are implicitly
+    #   assigned by SSO connection or SSO group will only be valid for a Member Session if there is at least one authentication
+    #   factor on the Member Session from the specified SSO connection.
+    #
+    #   If the Member is not authorized to perform the specified action on the specified Resource, or if the
+    #   `organization_id` does not match the Member's Organization, a 403 error will be thrown.
+    #   Otherwise, the response will contain a list of Roles that satisfied the authorization check.
+    #   The type of this field is nilable +AuthorizationCheck+ (+object+).
     #
     # == Returns:
     # An object with the following fields:
@@ -102,19 +143,26 @@ module StytchB2B
     # status_code::
     #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
     #   The type of this field is +Integer+.
+    # verdict::
+    #   If an `authorization_check` is provided in the request and the check succeeds, this field will return
+    #   the complete list of Roles that gave the Member permission to perform the specified action on the specified Resource.
+    #   The type of this field is nilable +AuthorizationVerdict+ (+object+).
     def authenticate(
       session_token: nil,
       session_duration_minutes: nil,
       session_jwt: nil,
-      session_custom_claims: nil
+      session_custom_claims: nil,
+      authorization_check: nil
     )
+      headers = {}
       request = {}
       request[:session_token] = session_token unless session_token.nil?
       request[:session_duration_minutes] = session_duration_minutes unless session_duration_minutes.nil?
       request[:session_jwt] = session_jwt unless session_jwt.nil?
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
+      request[:authorization_check] = authorization_check unless authorization_check.nil?
 
-      post_request('/v1/b2b/sessions/authenticate', request)
+      post_request('/v1/b2b/sessions/authenticate', request, headers)
     end
 
     # Revoke a Session and immediately invalidate all its tokens. To revoke a specific Session, pass either the `member_session_id`, `session_token`, or `session_jwt`. To revoke all Sessions for a Member, pass the `member_id`.
@@ -147,13 +195,14 @@ module StytchB2B
       session_jwt: nil,
       member_id: nil
     )
+      headers = {}
       request = {}
       request[:member_session_id] = member_session_id unless member_session_id.nil?
       request[:session_token] = session_token unless session_token.nil?
       request[:session_jwt] = session_jwt unless session_jwt.nil?
       request[:member_id] = member_id unless member_id.nil?
 
-      post_request('/v1/b2b/sessions/revoke', request)
+      post_request('/v1/b2b/sessions/revoke', request, headers)
     end
 
     # Use this endpoint to exchange a Member's existing session for another session in a different Organization. This can be used to accept an invite, but not to create a new member via domain matching.
@@ -253,6 +302,7 @@ module StytchB2B
       session_custom_claims: nil,
       locale: nil
     )
+      headers = {}
       request = {
         organization_id: organization_id
       }
@@ -262,11 +312,19 @@ module StytchB2B
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
       request[:locale] = locale unless locale.nil?
 
-      post_request('/v1/b2b/sessions/exchange', request)
+      post_request('/v1/b2b/sessions/exchange', request, headers)
     end
 
     # Get the JSON Web Key Set (JWKS) for a project.
     #
+    # JWKS are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key set, and both key sets will be returned by this endpoint for a period of 1 month.
+    #
+    # JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old JWKS, and some JWTs will be signed by the new JWKS. The correct JWKS to use for validation is determined by matching the `kid` value of the JWT and JWKS.
+    #
+    # If you're using one of our [backend SDKs](https://stytch.com/docs/b2b/sdks), the JWKS roll will be handled for you.
+    #
+    # If you're using your own JWT validation library, many have built-in support for JWKS rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWKS to use for validation by inspecting the `kid` value.
+    #
     # == Parameters:
     # project_id::
     #   The `project_id` to get the JWKS for.
@@ -286,9 +344,131 @@ module StytchB2B
     def get_jwks(
       project_id:
     )
+      headers = {}
       query_params = {}
       request = request_with_query_params("/v1/b2b/sessions/jwks/#{project_id}", query_params)
-      get_request(request)
+      get_request(request, headers)
+    end
+
+    # MANUAL(Sessions::authenticate_jwt)(SERVICE_METHOD)
+    # ADDIMPORT: require 'jwt'
+    # ADDIMPORT: require 'json/jwt'
+    # ADDIMPORT: require_relative 'errors'
+
+    # Parse a JWT and verify the signature. If max_token_age_seconds is unset, call the API directly
+    # If max_token_age_seconds is set and the JWT was issued (based on the "iat" claim) less than
+    # max_token_age_seconds seconds ago, then just verify locally and don't call the API
+    # To force remote validation for all tokens, set max_token_age_seconds to 0 or call authenticate()
+    # Note that the 'user_id' field of the returned session is DEPRECATED: Use member_id instead
+    # This field will be removed in a future MAJOR release.
+    # If max_token_age_seconds is not supplied 300 seconds will be used as the default.
+    def authenticate_jwt(
+      session_jwt,
+      max_token_age_seconds: nil,
+      session_duration_minutes: nil,
+      session_custom_claims: nil,
+      authorization_check: nil
+    )
+      max_token_age_seconds = 300 if max_token_age_seconds.nil?
+
+      if max_token_age_seconds == 0
+        return authenticate(
+          session_jwt: session_jwt,
+          session_duration_minutes: session_duration_minutes,
+          session_custom_claims: session_custom_claims,
+          authorization_check: authorization_check
+        )
+      end
+
+      decoded_jwt = authenticate_jwt_local(session_jwt, max_token_age_seconds: max_token_age_seconds, authorization_check: authorization_check)
+      return decoded_jwt unless decoded_jwt.nil?
+
+      authenticate(
+        session_jwt: session_jwt,
+        session_duration_minutes: session_duration_minutes,
+        session_custom_claims: session_custom_claims,
+        authorization_check: authorization_check
+      )
+    rescue StandardError
+      # JWT could not be verified locally. Check with the Stytch API.
+      authenticate(
+        session_jwt: session_jwt,
+        session_duration_minutes: session_duration_minutes,
+        session_custom_claims: session_custom_claims,
+        authorization_check: authorization_check
+      )
+    end
+
+    # Parse a JWT and verify the signature locally (without calling /authenticate in the API)
+    # Uses the cached value to get the JWK but if it is unavailable, it calls the get_jwks()
+    # function to get the JWK
+    # This method never authenticates a JWT directly with the API
+    # If max_token_age_seconds is not supplied 300 seconds will be used as the default.
+    def authenticate_jwt_local(session_jwt, max_token_age_seconds: nil, authorization_check: nil)
+      max_token_age_seconds = 300 if max_token_age_seconds.nil?
+
+      issuer = 'stytch.com/' + @project_id
+      begin
+        decoded_token = JWT.decode session_jwt, nil, true,
+                                   { jwks: @jwks_loader, iss: issuer, verify_iss: true, aud: @project_id, verify_aud: true, algorithms: ['RS256'] }
+
+        session = decoded_token[0]
+        iat_time = Time.at(session['iat']).to_datetime
+        return nil unless iat_time + max_token_age_seconds >= Time.now
+
+        session = marshal_jwt_into_session(session)
+      rescue JWT::InvalidIssuerError
+        raise Stytch::JWTInvalidIssuerError
+      rescue JWT::InvalidAudError
+        raise Stytch::JWTInvalidAudienceError
+      rescue JWT::ExpiredSignature
+        raise Stytch::JWTExpiredSignatureError
+      rescue JWT::IncorrectAlgorithm
+        raise Stytch::JWTIncorrectAlgorithmError
+      end
+
+      # Do the auth check - intentionally don't rescue errors from here
+      if authorization_check && session['roles']
+        @policy_cache.perform_authorization_check(
+          subject_roles: session['roles'],
+          subject_org_id: session['member_session']['organization_id'],
+          authorization_check: authorization_check
+        )
+      end
+
+      session
+    end
+
+    # Note that the 'user_id' field is DEPRECATED: Use member_id instead
+    # This field will be removed in a future MAJOR release.
+    def marshal_jwt_into_session(jwt)
+      stytch_claim = 'https://stytch.com/session'
+      organization_claim = 'https://stytch.com/organization'
+
+      expires_at = jwt[stytch_claim]['expires_at'] || Time.at(jwt['exp']).to_datetime.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+      # The custom claim set is all the claims in the payload except for the standard claims and
+      # the Stytch session claim. The cleanest way to collect those seems to be naming what we want
+      # to omit and filtering the rest to collect the custom claims.
+      reserved_claims = ['aud', 'exp', 'iat', 'iss', 'jti', 'nbf', 'sub', stytch_claim, organization_claim]
+      custom_claims = jwt.reject { |key, _| reserved_claims.include?(key) }
+      {
+        'member_session' => {
+          'session_id' => jwt[stytch_claim]['id'],
+          'organization_id' => jwt[organization_claim]['organization_id'],
+          'member_id' => jwt['sub'],
+          # DEPRECATED: Use member_id instead
+          'user_id' => jwt['sub'],
+          'started_at' => jwt[stytch_claim]['started_at'],
+          'last_accessed_at' => jwt[stytch_claim]['last_accessed_at'],
+          # For JWTs that include it, prefer the inner expires_at claim.
+          'expires_at' => expires_at,
+          'attributes' => jwt[stytch_claim]['attributes'],
+          'authentication_factors' => jwt[stytch_claim]['authentication_factors'],
+          'custom_claims' => custom_claims
+        },
+        'roles' => jwt[stytch_claim]['roles']
+      }
     end
+    # ENDMANUAL(Sessions::authenticate_jwt)
   end
 end

data/lib/stytch/b2b_sso.rb

@@ -9,6 +9,44 @@
 require_relative 'request_helper'
 
 module StytchB2B
+  class GetConnectionsRequestOptions
+    # Optional authorization object.
+    # Pass in an active Stytch Member session token or session JWT and the request
+    # will be run using that member's permissions.
+    attr_accessor :authorization
+
+    def initialize(
+      authorization: nil
+    )
+      @authorization = authorization
+    end
+
+    def to_headers
+      headers = {}
+      headers.merge!(@authorization.to_headers) if authorization
+      headers
+    end
+  end
+
+  class DeleteConnectionRequestOptions
+    # Optional authorization object.
+    # Pass in an active Stytch Member session token or session JWT and the request
+    # will be run using that member's permissions.
+    attr_accessor :authorization
+
+    def initialize(
+      authorization: nil
+    )
+      @authorization = authorization
+    end
+
+    def to_headers
+      headers = {}
+      headers.merge!(@authorization.to_headers) if authorization
+      headers
+    end
+  end
+
   class SSO
     include Stytch::RequestHelper
     attr_reader :oidc, :saml
@@ -20,7 +58,7 @@ module StytchB2B
       @saml = StytchB2B::SSO::SAML.new(@connection)
     end
 
-    # Get all SSO Connections owned by the organization.
+    # Get all SSO Connections owned by the organization. /%}
     #
     # == Parameters:
     # organization_id::
@@ -41,15 +79,21 @@ module StytchB2B
     # status_code::
     #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
     #   The type of this field is +Integer+.
+    #
+    # == Method Options:
+    # This method supports an optional +GetConnectionsRequestOptions+ object which will modify the headers sent in the HTTP request.
     def get_connections(
-      organization_id:
+      organization_id:,
+      method_options: nil
     )
+      headers = {}
+      headers = headers.merge(method_options.to_headers) unless method_options.nil?
       query_params = {}
       request = request_with_query_params("/v1/b2b/sso/#{organization_id}", query_params)
-      get_request(request)
+      get_request(request, headers)
     end
 
-    # Delete an existing SSO connection.
+    # Delete an existing SSO connection. /%}
     #
     # == Parameters:
     # organization_id::
@@ -70,11 +114,17 @@ module StytchB2B
     # status_code::
     #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
     #   The type of this field is +Integer+.
+    #
+    # == Method Options:
+    # This method supports an optional +DeleteConnectionRequestOptions+ object which will modify the headers sent in the HTTP request.
     def delete_connection(
       organization_id:,
-      connection_id:
+      connection_id:,
+      method_options: nil
     )
-      delete_request("/v1/b2b/sso/#{organization_id}/connections/#{connection_id}")
+      headers = {}
+      headers = headers.merge(method_options.to_headers) unless method_options.nil?
+      delete_request("/v1/b2b/sso/#{organization_id}/connections/#{connection_id}", headers)
     end
 
     # Authenticate a user given a token.
@@ -184,6 +234,7 @@ module StytchB2B
       session_custom_claims: nil,
       locale: nil
     )
+      headers = {}
       request = {
         sso_token: sso_token
       }
@@ -194,7 +245,7 @@ module StytchB2B
       request[:session_custom_claims] = session_custom_claims unless session_custom_claims.nil?
       request[:locale] = locale unless locale.nil?
 
-      post_request('/v1/b2b/sso/authenticate', request)
+      post_request('/v1/b2b/sso/authenticate', request, headers)
     end
 
     class OIDC
@@ -204,7 +255,7 @@ module StytchB2B
         @connection = connection
       end
 
-      # Create a new OIDC Connection.
+      # Create a new OIDC Connection. /%}
       #
       # == Parameters:
       # organization_id::
@@ -225,14 +276,20 @@ module StytchB2B
       # connection::
       #   The `OIDC Connection` object affected by this API call. See the [OIDC Connection Object](https://stytch.com/docs/b2b/api/oidc-connection-object) for complete response field details.
       #   The type of this field is nilable +OIDCConnection+ (+object+).
+      #
+      # == Method Options:
+      # This method supports an optional +CreateConnectionRequestOptions+ object which will modify the headers sent in the HTTP request.
       def create_connection(
         organization_id:,
-        display_name: nil
+        display_name: nil,
+        method_options: nil
       )
+        headers = {}
+        headers = headers.merge(method_options.to_headers) unless method_options.nil?
         request = {}
         request[:display_name] = display_name unless display_name.nil?
 
-        post_request("/v1/b2b/sso/oidc/#{organization_id}", request)
+        post_request("/v1/b2b/sso/oidc/#{organization_id}", request, headers)
       end
 
       # Updates an existing OIDC connection.
@@ -253,6 +310,7 @@ module StytchB2B
       # * `token_url`
       # * `userinfo_url`
       # * `jwks_url`
+      #  /%}
       #
       # == Parameters:
       # organization_id::
@@ -300,6 +358,9 @@ module StytchB2B
       # warning::
       #   If it is not possible to resolve the well-known metadata document from the OIDC issuer, this field will explain what went wrong if the request is successful otherwise. In other words, even if the overall request succeeds, there could be relevant warnings related to the connection update.
       #   The type of this field is nilable +String+.
+      #
+      # == Method Options:
+      # This method supports an optional +UpdateConnectionRequestOptions+ object which will modify the headers sent in the HTTP request.
       def update_connection(
         organization_id:,
         connection_id:,
@@ -310,8 +371,11 @@ module StytchB2B
         authorization_url: nil,
         token_url: nil,
         userinfo_url: nil,
-        jwks_url: nil
+        jwks_url: nil,
+        method_options: nil
       )
+        headers = {}
+        headers = headers.merge(method_options.to_headers) unless method_options.nil?
         request = {}
         request[:display_name] = display_name unless display_name.nil?
         request[:client_id] = client_id unless client_id.nil?
@@ -322,7 +386,7 @@ module StytchB2B
         request[:userinfo_url] = userinfo_url unless userinfo_url.nil?
         request[:jwks_url] = jwks_url unless jwks_url.nil?
 
-        put_request("/v1/b2b/sso/oidc/#{organization_id}/connections/#{connection_id}", request)
+        put_request("/v1/b2b/sso/oidc/#{organization_id}/connections/#{connection_id}", request, headers)
       end
     end
 
@@ -333,7 +397,7 @@ module StytchB2B
         @connection = connection
       end
 
-      # Create a new SAML Connection.
+      # Create a new SAML Connection. /%}
       #
       # == Parameters:
       # organization_id::
@@ -354,14 +418,20 @@ module StytchB2B
       # connection::
       #   The `SAML Connection` object affected by this API call. See the [SAML Connection Object](https://stytch.com/docs/b2b/api/saml-connection-object) for complete response field details.
       #   The type of this field is nilable +SAMLConnection+ (+object+).
+      #
+      # == Method Options:
+      # This method supports an optional +CreateConnectionRequestOptions+ object which will modify the headers sent in the HTTP request.
       def create_connection(
         organization_id:,
-        display_name: nil
+        display_name: nil,
+        method_options: nil
       )
+        headers = {}
+        headers = headers.merge(method_options.to_headers) unless method_options.nil?
         request = {}
         request[:display_name] = display_name unless display_name.nil?
 
-        post_request("/v1/b2b/sso/saml/#{organization_id}", request)
+        post_request("/v1/b2b/sso/saml/#{organization_id}", request, headers)
       end
 
       # Updates an existing SAML connection.
@@ -371,6 +441,7 @@ module StytchB2B
       # * `attribute_mapping`
       # * `idp_entity_id`
       # * `x509_certificate`
+      #  /%}
       #
       # == Parameters:
       # organization_id::
@@ -394,6 +465,20 @@ module StytchB2B
       # idp_sso_url::
       #   The URL for which assertions for login requests will be sent. This will be provided by the IdP.
       #   The type of this field is nilable +String+.
+      # saml_connection_implicit_role_assignments::
+      #   All Members who log in with this SAML connection will implicitly receive the specified Roles. See the [RBAC guide](https://stytch.com/docs/b2b/guides/rbac/role-assignment) for more information about role assignment.
+      #   The type of this field is nilable list of +String+.
+      # saml_group_implicit_role_assignments::
+      #   Defines the names of the SAML groups
+      #  that grant specific role assignments. For each group-Role pair, if a Member logs in with this SAML connection and
+      #  belongs to the specified SAML group, they will be granted the associated Role. See the
+      #  [RBAC guide](https://stytch.com/docs/b2b/guides/rbac/role-assignment) for more information about role assignment.
+      #          Before adding any group implicit role assignments, you must add a "groups" key to your SAML connection's
+      #          `attribute_mapping`. Make sure that your IdP is configured to correctly send the group information.
+      #   The type of this field is nilable list of +String+.
+      # alternative_audience_uri::
+      #   An alternative URL to use for the Audience Restriction. This value can be used when you wish to migrate an existing SAML integration to Stytch with zero downtime.
+      #   The type of this field is nilable +String+.
       #
       # == Returns:
       # An object with the following fields:
@@ -406,6 +491,9 @@ module StytchB2B
       # connection::
       #   The `SAML Connection` object affected by this API call. See the [SAML Connection Object](https://stytch.com/docs/b2b/api/saml-connection-object) for complete response field details.
       #   The type of this field is nilable +SAMLConnection+ (+object+).
+      #
+      # == Method Options:
+      # This method supports an optional +UpdateConnectionRequestOptions+ object which will modify the headers sent in the HTTP request.
       def update_connection(
         organization_id:,
         connection_id:,
@@ -413,21 +501,80 @@ module StytchB2B
         display_name: nil,
         attribute_mapping: nil,
         x509_certificate: nil,
-        idp_sso_url: nil
+        idp_sso_url: nil,
+        saml_connection_implicit_role_assignments: nil,
+        saml_group_implicit_role_assignments: nil,
+        alternative_audience_uri: nil,
+        method_options: nil
       )
+        headers = {}
+        headers = headers.merge(method_options.to_headers) unless method_options.nil?
         request = {}
         request[:idp_entity_id] = idp_entity_id unless idp_entity_id.nil?
         request[:display_name] = display_name unless display_name.nil?
         request[:attribute_mapping] = attribute_mapping unless attribute_mapping.nil?
         request[:x509_certificate] = x509_certificate unless x509_certificate.nil?
         request[:idp_sso_url] = idp_sso_url unless idp_sso_url.nil?
+        request[:saml_connection_implicit_role_assignments] = saml_connection_implicit_role_assignments unless saml_connection_implicit_role_assignments.nil?
+        request[:saml_group_implicit_role_assignments] = saml_group_implicit_role_assignments unless saml_group_implicit_role_assignments.nil?
+        request[:alternative_audience_uri] = alternative_audience_uri unless alternative_audience_uri.nil?
 
-        put_request("/v1/b2b/sso/saml/#{organization_id}/connections/#{connection_id}", request)
+        put_request("/v1/b2b/sso/saml/#{organization_id}/connections/#{connection_id}", request, headers)
+      end
+
+      # Used to update an existing SAML connection using an IDP metadata URL.
+      #
+      # A newly created connection will not become active until all the following are provided:
+      # * `idp_sso_url`
+      # * `idp_entity_id`
+      # * `x509_certificate`
+      # * `attribute_mapping` (must be supplied using [Update SAML Connection](update-saml-connection))
+      #  /%}
+      #
+      # == Parameters:
+      # organization_id::
+      #   Globally unique UUID that identifies a specific Organization. The `organization_id` is critical to perform operations on an Organization, so be sure to preserve this value.
+      #   The type of this field is +String+.
+      # connection_id::
+      #   Globally unique UUID that identifies a specific SSO `connection_id` for a Member.
+      #   The type of this field is +String+.
+      # metadata_url::
+      #   A URL that points to the IdP metadata. This will be provided by the IdP.
+      #   The type of this field is +String+.
+      #
+      # == Returns:
+      # An object with the following fields:
+      # request_id::
+      #   Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
+      #   The type of this field is +String+.
+      # status_code::
+      #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
+      #   The type of this field is +Integer+.
+      # connection::
+      #   The `SAML Connection` object affected by this API call. See the [SAML Connection Object](https://stytch.com/docs/b2b/api/saml-connection-object) for complete response field details.
+      #   The type of this field is nilable +SAMLConnection+ (+object+).
+      #
+      # == Method Options:
+      # This method supports an optional +UpdateByURLRequestOptions+ object which will modify the headers sent in the HTTP request.
+      def update_by_url(
+        organization_id:,
+        connection_id:,
+        metadata_url:,
+        method_options: nil
+      )
+        headers = {}
+        headers = headers.merge(method_options.to_headers) unless method_options.nil?
+        request = {
+          metadata_url: metadata_url
+        }
+
+        put_request("/v1/b2b/sso/saml/#{organization_id}/connections/#{connection_id}/url", request, headers)
       end
 
       # Delete a SAML verification certificate.
       #
       # You may need to do this when rotating certificates from your IdP, since Stytch allows a maximum of 5 certificates per connection. There must always be at least one certificate per active connection.
+      #  /%}
       #
       # == Parameters:
       # organization_id::
@@ -451,12 +598,18 @@ module StytchB2B
       # status_code::
       #   The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
       #   The type of this field is +Integer+.
+      #
+      # == Method Options:
+      # This method supports an optional +DeleteVerificationCertificateRequestOptions+ object which will modify the headers sent in the HTTP request.
       def delete_verification_certificate(
         organization_id:,
         connection_id:,
-        certificate_id:
+        certificate_id:,
+        method_options: nil
       )
-        delete_request("/v1/b2b/sso/saml/#{organization_id}/connections/#{connection_id}/verification_certificates/#{certificate_id}")
+        headers = {}
+        headers = headers.merge(method_options.to_headers) unless method_options.nil?
+        delete_request("/v1/b2b/sso/saml/#{organization_id}/connections/#{connection_id}/verification_certificates/#{certificate_id}", headers)
       end
     end
   end