# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.medable.com/cortex-api/scripting/modules-1/saml-module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.