> For the complete documentation index, see [llms.txt](https://docs.medable.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.medable.com/cortex-api/scripting/modules-1/saml-module.md).

# SAML Module

The SAML module allows you to implement Single-Sign-On via SAML v2.0 protocol. Using this library, you can configure your org to act as a Service Provider.Import

```
import { ServiceProvider, IdentityProvider } from 'saml'
```

### IdentityProvider

[IdentityProvider(options)](https://docs.medable.com/reference#section-identityprovider-options-)\
The configuration for a service that authenticates users in the SAML flow.

### IdentityProvider(options)

Creates a new instance of `IdentityProvider`, required as an argument for `ServiceProvider` methods.

**Arguments**

* `options` (Object)
  * `sso_login_url` (String) The login URL to use during a login request.
  * `sso_logout_url` (String) The logout URL to use during a logout request.
  * `certificates` (String\[]) An array of PEM formatted certificates.
  * `force_authn` (Boolean=false) If true, forces re-authentication.
  * `sign_get_request` (Boolean=false) If true, signs the request.
  * `allow_unencrypted_assertion` (Boolean=false) If true, allows unencrypted assertions.

### ServiceProvider

[ServiceProvider(options)](https://docs.medable.com/reference#section-serviceprovider-options-)\
[ServiceProvider.create\_login\_request\_url(idp, options)](https://docs.medable.com/reference#section-serviceprovider-create_login_request_url-idp-options-)\
[ServiceProvider.create\_logout\_request\_url(idp, options)](https://docs.medable.com/reference#section-serviceprovider-create_logout_request_url-idp-options-)\
[ServiceProvider.create\_logout\_response\_url(idp, options)](https://docs.medable.com/reference#section-serviceprovider-create_logout_response_url-idp-options-)\
[ServiceProvider.create\_metadata()](https://docs.medable.com/reference#section-serviceprovider-create_metadata-)\
[ServiceProvider.post\_assert(idp, options)](https://docs.medable.com/reference#section-serviceprovider-post_assert-idp-options-)\
[ServiceProvider.redirect\_assert(idp, options)](https://docs.medable.com/reference#section-serviceprovider-redirect_assert-idp-options-)

### ServiceProvider(options)

A service provider that uses an `IdentityProvider` for authentication in the SAML flow.

**Arguments**

* `options` (Object)
  * `entity_id` (String The unique sp identifier (often the URL of the metadata file).
  * `private_key` (String) Service provider private key in PEM format.
  * `certificate` (String) Service provider certificate in PEM format.
  * `assert_endpoint` (String) The URL of service provider assert endpoint.
  * `alt_private_keys` (String\[]) Additional private keys to use when attempting to decrypt responses (for rollover).
  * `alt_certs` (String\[]) Additional certificates to expose in the SAML metadata (for rollover).
  * `force_authn` (Boolean=false) If true, forces re-authentication.
  * `auth_context` (String) The SAML AuthnContextClassRef.
  * `nameid_format` (String) The Name ID format.
  * `sign_get_request` (Boolean=false) If true, signs the request.
  * `allow_unencrypted_assertion` (Boolean=false) If true, allows unencrypted assertions.

**Returns**

* `updated` (ServiceProvider) true if the value was set, or false if the cache value did not initially equal `chk`.

### ServiceProvider.create\_login\_request\_url(idp, options)

Get a URL to initiate a login.

**Arguments**

* `idp` (IdentityProvider) An IdentityProvider instance.
* `options` (Object)
  * `relay_state` (String) The SAML relay state.
  * `force_authn` (Boolean=false) If true, forces re-authentication.
  * `auth_context` (String) The SAML AuthnContextClassRef.
  * `nameid_format` (String) The Name ID format.
  * `sign_get_request` (Boolean=false) If true, signs the request.

**Returns**

* `response` (Object)
  * `url` the request url
  * `id` the request id

### ServiceProvider.create\_logout\_request\_url(idp, options)

Creates a SAML Request URL to initiate a user logout.

**Arguments**

* `idp` (IdentityProvider) An IdentityProvider instance.
* `options` (Object)
  * `relay_state` (String) The SAML relay state.
  * `nameid_format` (String) The Name ID format.
  * `sign_get_request` (Boolean=false) If true, signs the request.
  * `session_index` (String) The session index to use.
  * `allow_unencrypted_assertion` (Boolean=false) If true, allows unencrypted assertions.

**Returns**

* `url` (String) The request url.

### ServiceProvider.create\_logout\_response\_url(idp, options)

Creates a SAML Response URL to confirm a successful IdP initiated logout.

**Arguments**

* `idp` (IdentityProvider) An IdentityProvider instance.
* `options` (Object)
  * `in_response_to` (String) The ID of the request that this is in response to. Should be checked against any sent request IDs.
  * `sign_get_request` (Boolean=false) If true, signs the request.
  * `relay_state` (String) The SAML relay state.

**Returns**

* `url` (String) The request url.

### ServiceProvider.create\_metadata()

Returns the XML metadata used during the initial SAML configuration.

**Returns**

* `url` (String)

### ServiceProvider.post\_assert(idp, options)

Gets a SAML response object if the login attempt is valid, used for post binding.

**Arguments**

* `idp` (IdentityProvider) An IdentityProvider instance.
* `options` (Object)
  * `request_body` (Object) An object containing the parsed query string parameters. This object should contain the value for either a SAMLResponse or SAMLRequest.
  * `allow_unencrypted_assertion` (Boolean=false) If true, allows unencrypted assertions.
  * `require_session_index` (Boolean=false) If false, allow the assertion to be valid without a SessionIndex attribute on the AuthnStatement node.

**Returns**

* `response` (Object) A SAML response object.
  * `response_header` (Object)
    * `id` (String)
    * `destination` (String)
    * `in_response_to` (String)
  * `type` "authn\_response" (String)
  * `user` (Object)
    * `name_id` (String)
    * `session_index` (String)
    * `attributes` (Object)

### ServiceProvider.redirect\_assert(idp, options)

Gets a SAML response object if the login attempt is valid, used for redirect binding.

**Arguments**

* `idp` (IdentityProvider) An IdentityProvider instance.
* `options` (Object)

  * `request_body` (Object) An object containing the parsed query string parameters. This object should contain the value for either a SAMLResponse or SAMLRequest.
  * `allow_unencrypted_assertion` (Boolean=false) If true, allows unencrypted assertions.
  * `require_session_index` (Boolean=false) If false, allow the assertion to be valid without a SessionIndex attribute on the AuthnStatement node.

  **Returns**

  * `response` (Object) A SAML response object.
    * `response_header` (Object)
      * `id` (String)
      * `destination` (String)
      * `in_response_to` (String)
    * `type` "authn\_response" (String)
    * `user` (Object)
      * `name_id` (String)
      * `session_index` (String)
      * `attributes` (Object)