Class: StytchB2B::SSO::SAML

Inherits:

Object

Object
StytchB2B::SSO::SAML

show all

Includes:: Stytch::RequestHelper

Defined in:: lib/stytch/b2b_sso.rb

Defined Under Namespace

Classes: CreateConnectionRequestOptions, DeleteEncryptionPrivateKeyRequestOptions, DeleteVerificationCertificateRequestOptions, UpdateByURLRequestOptions, UpdateConnectionRequestOptions

Instance Method Summary collapse

#create_connection(organization_id:, display_name: nil, identity_provider: nil, method_options: nil) ⇒ Object

Create a new SAML Connection.
#delete_encryption_private_key(organization_id:, connection_id:, private_key_id:, method_options: nil) ⇒ Object

Delete a SAML encryption private key.
#delete_verification_certificate(organization_id:, connection_id:, certificate_id:, method_options: nil) ⇒ Object

Delete a SAML verification certificate.
#initialize(connection) ⇒ SAML constructor

A new instance of SAML.
#update_by_url(organization_id:, connection_id:, metadata_url:, method_options: nil) ⇒ Object

Used to update an existing SAML connection using an IDP metadata URL.
#update_connection(organization_id:, connection_id:, idp_entity_id: nil, display_name: nil, attribute_mapping: nil, x509_certificate: nil, idp_sso_url: nil, saml_connection_implicit_role_assignments: nil, saml_group_implicit_role_assignments: nil, alternative_audience_uri: nil, identity_provider: nil, signing_private_key: nil, nameid_format: nil, alternative_acs_url: nil, idp_initiated_auth_disabled: nil, saml_encryption_private_key: nil, allow_gateway_callback: nil, method_options: nil) ⇒ Object

Updates an existing SAML connection.

Methods included from Stytch::RequestHelper

#delete_request, #get_request, #post_request, #put_request, #request_with_query_params

Constructor Details

#initialize(connection) ⇒ `SAML`

Returns a new instance of SAML.



570
571
572

# File 'lib/stytch/b2b_sso.rb', line 570

def initialize(connection)
  @connection = connection
end

Instance Method Details

#create_connection(organization_id:, display_name: nil, identity_provider: nil, method_options: nil) ⇒ `Object`

Create a new 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. You may also use the organization_slug or organization_external_id here as a convenience. The type of this field is String.
display_name: A human-readable display name for the connection. The type of this field is nilable String.
identity_provider: Name of the IdP. Enum with possible values: ‘classlink`, `cyberark`, `duo`, `google-workspace`, `jumpcloud`, `keycloak`, `miniorange`, `microsoft-entra`, `okta`, `onelogin`, `pingfederate`, `rippling`, `salesforce`, `shibboleth`, or `generic`.

Specifying a known provider allows Stytch to handle any provider-specific logic.

The type of this field is nilable +CreateConnectionRequestIdentityProvider+ (string enum).

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](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 StytchB2B::SSO::SAML::CreateConnectionRequestOptions object which will modify the headers sent in the HTTP request.

# File 'lib/stytch/b2b_sso.rb', line 603

def create_connection(
  organization_id:,
  display_name: nil,
  identity_provider: 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[:identity_provider] = identity_provider unless identity_provider.nil?

  post_request("/v1/b2b/sso/saml/#{organization_id}", request, headers)
end

#delete_encryption_private_key(organization_id:, connection_id:, private_key_id:, method_options: nil) ⇒ `Object`

Delete a SAML encryption private key.

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. You may also use the organization_slug or organization_external_id here as a convenience. 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.
private_key_id: The ID of the encryption private key to be deleted. 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.
private_key_id: The ID of the encryption private key. 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.

Method Options:

This method supports an optional StytchB2B::SSO::SAML::DeleteEncryptionPrivateKeyRequestOptions object which will modify the headers sent in the HTTP request.

# File 'lib/stytch/b2b_sso.rb', line 856

def delete_encryption_private_key(
  organization_id:,
  connection_id:,
  private_key_id:,
  method_options: nil
)
  headers = {}
  headers = headers.merge(method_options.to_headers) unless method_options.nil?
  delete_request("/v1/b2b/sso/saml/#{organization_id}/connections/#{connection_id}/encryption_private_keys/#{private_key_id}", headers)
end

#delete_verification_certificate(organization_id:, connection_id:, certificate_id:, method_options: nil) ⇒ `Object`

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: The organization ID that the SAML connection belongs to. You may also use the organization_slug or organization_external_id here as a convenience. The type of this field is String.
connection_id: The ID of the SAML connection. The type of this field is String.
certificate_id: The ID of the certificate to be deleted. 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.
certificate_id: The ID of the certificate that was deleted. 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.

Method Options:

This method supports an optional StytchB2B::SSO::SAML::DeleteVerificationCertificateRequestOptions object which will modify the headers sent in the HTTP request.

# File 'lib/stytch/b2b_sso.rb', line 818

def delete_verification_certificate(
  organization_id:,
  connection_id:,
  certificate_id:,
  method_options: nil
)
  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

#update_by_url(organization_id:, connection_id:, metadata_url:, method_options: nil) ⇒ `Object`

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. You may also use the organization_slug or organization_external_id here as a convenience. 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](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 StytchB2B::SSO::SAML::UpdateByURLRequestOptions object which will modify the headers sent in the HTTP request.

# File 'lib/stytch/b2b_sso.rb', line 774

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

#update_connection(organization_id:, connection_id:, idp_entity_id: nil, display_name: nil, attribute_mapping: nil, x509_certificate: nil, idp_sso_url: nil, saml_connection_implicit_role_assignments: nil, saml_group_implicit_role_assignments: nil, alternative_audience_uri: nil, identity_provider: nil, signing_private_key: nil, nameid_format: nil, alternative_acs_url: nil, idp_initiated_auth_disabled: nil, saml_encryption_private_key: nil, allow_gateway_callback: nil, method_options: nil) ⇒ `Object`

Updates an existing SAML connection.

Note that a newly created connection will not become active until all of the following are provided:

‘idp_sso_url`
‘attribute_mapping`
‘idp_entity_id`
‘x509_certificate`

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. You may also use the organization_slug or organization_external_id here as a convenience. 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.
idp_entity_id: A globally unique name for the IdP. This will be provided by the IdP. The type of this field is nilable String.
display_name: A human-readable display name for the connection. The type of this field is nilable String.
attribute_mapping: An object that represents the attributes used to identify a Member. This object will map the IdP-defined User attributes to Stytch-specific values. Required attributes: ‘email` and one of `full_name` or `first_name` and `last_name`. The type of this field is nilable object.
x509_certificate: A certificate that Stytch will use to verify the sign-in assertion sent by the IdP, in [PEM](en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format. See our [X509 guide](stytch.com/docs/b2b/api/saml-certificates) for more info. The type of this field is nilable String.
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](stytch.com/docs/b2b/guides/rbac/role-assignment) for more information about role assignment. The type of this field is nilable list of SAMLConnectionImplicitRoleAssignment.
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 +SAMLGroupImplicitRoleAssignment+.

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. Read our [SSO migration guide](stytch.com/docs/b2b/guides/migrations/additional-migration-considerations) for more info. The type of this field is nilable String.
identity_provider: Name of the IdP. Enum with possible values: ‘classlink`, `cyberark`, `duo`, `google-workspace`, `jumpcloud`, `keycloak`, `miniorange`, `microsoft-entra`, `okta`, `onelogin`, `pingfederate`, `rippling`, `salesforce`, `shibboleth`, or `generic`.

Specifying a known provider allows Stytch to handle any provider-specific logic.

The type of this field is nilable +UpdateConnectionRequestIdentityProvider+ (string enum).

signing_private_key: A PKCS1 format RSA private key used for signing SAML requests. Only PKCS1 format (starting with “—–BEGIN RSA PRIVATE KEY—–”) is supported. When provided, Stytch will generate a new x509 certificate from this key and return it in the signing_certificates array. The type of this field is nilable String.
nameid_format: The NameID format the SAML Connection expects to use. Defaults to ‘urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. The type of this field is nilable String.
alternative_acs_url: An alternative URL to use for the ‘AssertionConsumerServiceURL` in SP initiated SAML AuthNRequests. This value can be used when you wish to migrate an existing SAML integration to Stytch with zero downtime. Note that you will be responsible for proxying requests sent to the Alternative ACS URL to Stytch. Read our [SSO migration guide](stytch.com/docs/b2b/guides/migrations/additional-migration-considerations) for more info. The type of this field is nilable String.
idp_initiated_auth_disabled: Determines whether IDP initiated auth is allowed for a given SAML connection. Defaults to false (IDP Initiated Auth is enabled). The type of this field is nilable Boolean.
saml_encryption_private_key: A PKCS1 format RSA private key used to decrypt encrypted SAML assertions. Only PKCS1 format (starting with “—–BEGIN RSA PRIVATE KEY—–”) is supported. The type of this field is nilable String.
allow_gateway_callback: (no documentation yet) The type of this field is nilable Boolean.

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](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 StytchB2B::SSO::SAML::UpdateConnectionRequestOptions object which will modify the headers sent in the HTTP request.

# File 'lib/stytch/b2b_sso.rb', line 699

def update_connection(
  organization_id:,
  connection_id:,
  idp_entity_id: nil,
  display_name: nil,
  attribute_mapping: nil,
  x509_certificate: nil,
  idp_sso_url: nil,
  saml_connection_implicit_role_assignments: nil,
  saml_group_implicit_role_assignments: nil,
  alternative_audience_uri: nil,
  identity_provider: nil,
  signing_private_key: nil,
  nameid_format: nil,
  alternative_acs_url: nil,
  idp_initiated_auth_disabled: nil,
  saml_encryption_private_key: nil,
  allow_gateway_callback: 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?
  request[:identity_provider] = identity_provider unless identity_provider.nil?
  request[:signing_private_key] = signing_private_key unless signing_private_key.nil?
  request[:nameid_format] = nameid_format unless nameid_format.nil?
  request[:alternative_acs_url] = alternative_acs_url unless alternative_acs_url.nil?
  request[:idp_initiated_auth_disabled] = idp_initiated_auth_disabled unless idp_initiated_auth_disabled.nil?
  request[:saml_encryption_private_key] = saml_encryption_private_key unless saml_encryption_private_key.nil?
  request[:allow_gateway_callback] = allow_gateway_callback unless allow_gateway_callback.nil?

  put_request("/v1/b2b/sso/saml/#{organization_id}/connections/#{connection_id}", request, headers)
end

Class: StytchB2B::SSO::SAML

Defined Under Namespace

Instance Method Summary collapse

Methods included from Stytch::RequestHelper

Constructor Details

#initialize(connection) ⇒ SAML

Instance Method Details

#create_connection(organization_id:, display_name: nil, identity_provider: nil, method_options: nil) ⇒ Object

Parameters:

Returns:

Method Options:

#delete_encryption_private_key(organization_id:, connection_id:, private_key_id:, method_options: nil) ⇒ Object

Parameters:

Returns:

Method Options:

#delete_verification_certificate(organization_id:, connection_id:, certificate_id:, method_options: nil) ⇒ Object

Parameters:

Returns:

Method Options:

#update_by_url(organization_id:, connection_id:, metadata_url:, method_options: nil) ⇒ Object

Parameters:

Returns:

Method Options:

Parameters:

Returns:

Method Options:

#initialize(connection) ⇒ `SAML`

#create_connection(organization_id:, display_name: nil, identity_provider: nil, method_options: nil) ⇒ `Object`

#delete_encryption_private_key(organization_id:, connection_id:, private_key_id:, method_options: nil) ⇒ `Object`

#delete_verification_certificate(organization_id:, connection_id:, certificate_id:, method_options: nil) ⇒ `Object`

#update_by_url(organization_id:, connection_id:, metadata_url:, method_options: nil) ⇒ `Object`