### Setting up SSOReady

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

Steps to configure SSOReady, including creating environments, API keys, and organizations.

```APIDOC
## Setting up SSOReady

### Description
Guides the user through the necessary setup steps in the SSOReady web application before implementing SCIM code.

### Prerequisites:
- Sign up for an SSOReady account: [https://app.ssoready.com/login](https://app.ssoready.com/login)

### Key Setup Steps:

1.  **Creating Environments:**
    - **Purpose:** To represent different deployment stages (e.g., production, staging).
    - **Action:** Navigate to the 'Environments' section and click 'New'.
    - **Configuration:** Assign a 'Redirect URL' (can be a placeholder like `http://localhost` if SAML is not immediately used).

2.  **Creating API Keys:**
    - **Purpose:** For authenticating API requests to SSOReady.
    - **Action:** Within an environment's view, click 'API Keys' in the left navbar and then 'Create API Key'.
    - **Usage:** The generated secret key (starting with `ssoready_sk_...`) is used for API authentication, such as when listing users or groups.

3.  **Creating Organizations:**
    - **Purpose:** To represent your customers or distinct tenants.
    - **Action:** Within an environment's view, click the 'Create organization' button.
    - **Properties:**
        - **External ID (Optional):** Use your internal identifier for the tenant (e.g., 'team ID', 'workspace ID'). This is provided as `organization_external_id` in API calls.
        - **Domains:** List email domains (e.g., `apple.com`) associated with the organization. SSOReady will enforce that SCIM users belong to these domains.
```

--------------------------------

### Self-Serve Setup URLs API

Source: https://github.com/ssoready/docs/blob/main/fern/pages/management-api.mdx

Generate self-serve setup URLs for customers to configure their SAML and SCIM settings.

```APIDOC
## POST /api/management/setup-urls

### Description
Creates a self-serve setup URL for a given organization.

### Method
POST

### Endpoint
/api/management/setup-urls

### Parameters
#### Request Body
- **organizationId** (string) - Required - The ID of the organization for which to create the setup URL.
- **redirectUri** (string) - Optional - A URL to redirect the user to after setup is complete.

### Request Example
```json
{
  "organizationId": "org_12345",
  "redirectUri": "https://your-app.com/sso/setup-complete"
}
```

### Response
#### Success Response (201)
- **setupUrl** (string) - The generated self-serve setup URL.

#### Response Example
```json
{
  "setupUrl": "https://app.ssoready.com/setup/abcdef123456"
}
```
```

--------------------------------

### Sync Cadence Options

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

Information on recommended frequencies for syncing users and groups from SSOReady.

```APIDOC
## Sync Cadence Recommendations

### Description
Guidance on how often to perform SCIM synchronization with SSOReady.

### Options:
1.  **Periodic Background Job (Recommended):**
    - Schedule a job to run hourly.
    - Iterate through all organizations with SCIM enabled.
    - Perform a sync for each organization.
    - Rationale: User and group data changes infrequently. Identity Providers like Microsoft Entra have sync limitations (e.g., ~40 minutes).

2.  **Force SCIM Sync Button:**
    - Provide a user-facing button to trigger a sync.
    - Suitable for simpler implementations or when background jobs are challenging.
    - Feasible for directories with a small number of users (typically < 100) to avoid timeouts.
    - Note: Periodic background syncing is the more typical user expectation.
```

--------------------------------

### List SCIM Groups (GET /v1/scim/groups)

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

This snippet demonstrates how to list SCIM groups from SSOReady. It involves making a GET request to the /v1/scim/groups endpoint. The response may contain a nextPageToken for paginating through the list of groups. If nextPageToken is empty, it signifies the end of the list.

```shell
GET /v1/scim/groups
```

--------------------------------

### SCIM User with Okta Attributes (JSON)

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

This JSON example shows a SCIM user object that includes additional attributes synced from Okta. It demonstrates how user details like display name, first name, last name, and email addresses might be structured within the 'attributes' field.

```json
{
  "id": "scim_user_...",
  "scimDirectoryId": "scim_directory_...",
  "email": "ulysse.carion@ssoready.com",
  "deleted": false,
  "attributes": {
    "active": true,
    "displayName": "Ulysse Carion",
    "emails": [
      {
        "primary": true,
        "type": "work",
        "value": "ulysse.carion@ssoready.com"
      }
    ],
    "externalId": "00uhcdk08jtvkgwD95d7",
    "groups": [],
    "id": "scim_user_...",
    "locale": "en-US",
    "name": {
      "familyName": "Carion",
      "givenName": "Ulysse"
    },
    "userName": "ulysse.carion@ssoready.com"
  }
}
```

--------------------------------

### Provisioning (Creating) Groups

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

When provisioning groups, create a new group in your system if one does not exist, matching it using the `id` from SSOReady. Ensure new groups have a `ssoready_scim_group_id` attribute.

```APIDOC
## Provisioning Groups

### Description
When syncing groups from SSOReady, for each group where `deleted` is `false`, you should create a corresponding group in your system if it doesn't already exist. Use the `id` field from the SSOReady group to populate a unique identifier (e.g., `ssoready_scim_group_id`) in your system's group resource. This ensures proper matching during subsequent syncs.

### Considerations
- The `id` field from SSOReady is a globally unique identifier.
- Match SCIM groups to your system's groups using a dedicated attribute (e.g., `ssoready_scim_group_id`).
- If a group is not found in your system based on the `id`, create a new group.
- Group attributes are optional and their schema may vary; they are often not used by most SCIM implementations.
```

--------------------------------

### API Key ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/environments.mdx

An example of a non-sensitive API Key ID in SSOReady. It starts with 'api_key_'.

```text
api_key_...
```

--------------------------------

### Environment ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/environments.mdx

An example of a universally unique Environment ID in SSOReady. It starts with 'env_'.

```text
env_579r04bhgwhl0zq7f3ynj8hh0
```

--------------------------------

### List SCIM Groups

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

Retrieve a paginated list of SCIM groups. Use the `nextPageToken` in the response to fetch subsequent pages if available.

```APIDOC
## GET /v1/scim/groups

### Description
Retrieves a paginated list of SCIM groups from the SSOReady system. If the response includes a `nextPageToken` with a non-empty value, it indicates that there are more groups to fetch. To get the next page, repeat the request with the `page_token` query parameter set to the value of `nextPageToken`.

### Method
GET

### Endpoint
/v1/scim/groups

### Parameters
#### Query Parameters
- **page_token** (string) - Optional - Token for fetching the next page of results.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the SCIM group.
- **scimDirectoryId** (string) - Identifier for the SCIM directory.
- **displayName** (string) - The display name of the group.
- **deleted** (boolean) - Indicates if the group is marked as deleted.
- **attributes** (object) - A JSON object containing additional properties of the group. The schema can vary.
- **nextPageToken** (string) - Token for fetching the next page of results. An empty string indicates the end of the list.

#### Response Example
```json
{
  "groups": [
    {
      "id": "scim_group_123",
      "scimDirectoryId": "scim_directory_abc",
      "displayName": "Engineering",
      "deleted": false,
      "attributes": {}
    }
  ],
  "nextPageToken": "some_token_or_empty_string"
}
```
```

--------------------------------

### List SCIM Users

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

Retrieve a paginated list of SCIM users from SSOReady. This is essential for provisioning or deprovisioning users in your product based on changes in the enterprise directory.

```APIDOC
## GET /v1/scim/users

### Description
Retrieves a paginated list of SCIM users. Use this endpoint to sync users from SSOReady into your product, handling creation, updates, and deletion.

### Method
GET

### Endpoint
/v1/scim/users

### Parameters
#### Query Parameters
- **pageToken** (string) - Optional - Token for fetching the next page of results. If omitted or empty, the first page is returned.

### Request Example
```apidoc
GET /v1/scim/users?pageToken=your_next_page_token
Authorization: Bearer ssoready_sk_...
```

### Response
#### Success Response (200)
- **users** (array) - An array of user objects.
  - **id** (string) - The unique identifier for the user.
  - **externalId** (string) - The external identifier for the user (e.g., from the enterprise directory).
  - **active** (boolean) - Indicates if the user is active.
  - **deleted** (boolean) - Indicates if the user has been marked for deletion.
- **nextPageToken** (string) - A token to retrieve the next page of results. An empty string indicates the last page.

#### Response Example
```json
{
  "users": [
    {
      "id": "user_abc123",
      "externalId": "ent_user_xyz789",
      "active": true,
      "deleted": false
    }
  ],
  "nextPageToken": "next_token_value"
}
```
```

--------------------------------

### List SCIM Users (API Key)

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

Fetches a paginated list of SCIM users from SSOReady. Requires an API Key and organization external ID. Handles pagination using nextPageToken.

```HTTP
GET /v1/scim/users
Authorization: Bearer ssoready_sk_...

```

--------------------------------

### Initiate SAML Login Redirect

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-quickstart.mdx

Initiates a SAML login by redirecting the user's browser to their corporate identity provider. This is abstracted by the SSOReady SDK, which generates a URL. The provided code snippet requires an API Key and an organizationExternalId.

```javascript
import SSOReady from "@ssoready/ssoready";

const ssoready = new SSOReady(
  "ssoready_sk_...", // Your SSOReady API Key
);

const url = await ssoready.saml.createSAMLRedirect({
  organizationExternalId: "your-organization-external-id",
  // Other optional parameters can be passed here
});

// Redirect your user to this URL
window.location.href = url;
```

--------------------------------

### Redeem SAML Access Code

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-quickstart.mdx

Redeem a SAML access code to retrieve user details. This endpoint is called from your backend after a user is redirected from SSOReady with a `saml_access_code` query parameter.

```APIDOC
## POST /v1/saml/redeem

### Description
Redeems a SAML access code to obtain user authentication details, including email, organization ID, and organization external ID.

### Method
POST

### Endpoint
/v1/saml/redeem

### Parameters

#### Request Body
- **saml_access_code** (string) - Required - The SAML access code received via the callback URL.

### Request Example
```json
{
  "saml_access_code": "saml_access_code_..."
}
```

### Response
#### Success Response (200)
- **email** (string) - The email address of the authenticated user.
- **organizationId** (string) - The unique identifier for the SSOReady organization.
- **organizationExternalId** (string) - The external identifier for the SSOReady organization, as configured by the user.

#### Response Example
```json
{
  "email": "user@example.com",
  "organizationId": "org_12345",
  "organizationExternalId": "customer_abc"
}
```
```

--------------------------------

### Redeem SAML Access Code (API Request)

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-quickstart.mdx

This snippet demonstrates the API request to redeem a SAML access code for authenticated user details. It outlines the endpoint and expected request parameters.

```HTTP
POST /v1/saml/redeem
Content-Type: application/json

{
  "saml_access_code": "SAMl_ACCESS_CODE"
}
```

--------------------------------

### Initiate SAML Login Redirect

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-quickstart.mdx

Initiating SAML logins involves redirecting users to their corporate identity provider. SSOReady's SDKs simplify this by providing a URL that, when visited, triggers an HTTP POST to the identity provider with the necessary SAML message. This endpoint abstracts the complexity of generating the SAML request.

```APIDOC
## POST /v1/saml/redirect

### Description
Initiates a SAML login flow by redirecting the user's browser to their corporate identity provider.

### Method
POST

### Endpoint
/v1/saml/redirect

### Parameters
#### Request Body
- **organizationExternalId** (string) - Required - The unique identifier for the organization.
- **relayState** (string) - Optional - Any state information to be passed along during the SAML flow.

### Request Example
{
  "organizationExternalId": "org_12345",
  "relayState": "next=/dashboard"
}

### Response
#### Success Response (200)
- **redirectUrl** (string) - The URL to which the user's browser should be redirected to start the SAML authentication process.

#### Response Example
{
  "redirectUrl": "https://your-idp.com/saml/sso?SAMLRequest=..."
}
```

--------------------------------

### SCIM Request Log ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/scim-request-logs.mdx

Provides an example of a SCIM request log ID, which is a universally unique identifier starting with 'scim_request_'.

```text
scim_request_03cgnctzz5mjxhfciozcgfbzd
```

--------------------------------

### List Users in a Group

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

Retrieve a list of users who are members of a specific SCIM group by providing the group's ID.

```APIDOC
## GET /v1/scim/users

### Description
Lists SCIM users, with an option to filter by group membership.

### Method
GET

### Endpoint
/v1/scim/users

### Parameters
#### Query Parameters
- **scim_group_id** (string) - Required - The SSOReady-assigned ID of the SCIM group (e.g., `scim_group_...`).

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
  - **id** (string) - The unique identifier for the user.
  - **username** (string) - The username of the user.
  - **emails** (array) - A list of email addresses for the user.
  - **name** (object) - An object containing the user's name.
    - **givenName** (string) - The user's first name.
    - **familyName** (string) - The user's last name.

#### Response Example
```json
{
  "users": [
    {
      "id": "user-123",
      "username": "john.doe@example.com",
      "emails": [
        {
          "value": "john.doe@example.com",
          "type": "work"
        }
      ],
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      }
    }
  ]
}
```
```

--------------------------------

### API Key Secret Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/environments.mdx

An example of a sensitive API Key Secret in SSOReady. It starts with 'ssoready_sk_'. This secret should be kept confidential and used for authentication with SSOReady's SDKs or HTTP API.

```text
ssoready_sk_...
```

--------------------------------

### SCIM Bearer Token Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/scim-directories.mdx

Provides an example of a SCIM bearer token assigned by SSOReady for authenticating requests from identity providers. These tokens are used in the Authorization header.

```text
ssoready_scim_bearer_token_9yk9nijlzz8oggcsxf69ujbdw
```

--------------------------------

### Exchange SAML Access Code for User Details

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-logins.mdx

This example demonstrates a POST request to the /v1/saml/redeem endpoint to exchange a SAML access code for user information.

```HTTP
POST /v1/saml/redeem
```

--------------------------------

### SSOReady Callback URL Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-logins.mdx

This snippet shows a typical SSOReady callback URL that includes a SAML access code, which is used to exchange for user details.

```URL
https://yourcompany.com/ssoready-callback?saml_access_code=saml_access_code_...
```

--------------------------------

### SCIM User ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/scim-users.mdx

Illustrates the format of a SCIM user ID, which is universally unique and starts with 'scim_user_'.

```text
scim_user_eayqn84gu63k99rg5gcffesms
```

--------------------------------

### SAML Login Flow ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/saml-login-flows.mdx

Demonstrates the format of a SAML login flow ID, which starts with 'saml_flow_' and is universally unique.

```text
saml_flow_c2nrnid1sr9nexrqorczyxqpb
```

--------------------------------

### SAML Connection ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/saml-connections.mdx

Demonstrates the format of a SAML connection ID. These IDs are universally unique and start with 'saml_conn_'.

```text
saml_conn_56gbsrki2z8im0iejiamm9529
```

--------------------------------

### Redeem SAML Access Code (API Response)

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-quickstart.mdx

This snippet shows the expected API response when successfully redeeming a SAML access code. It includes the user's email and organization identifiers.

```JSON
{
  "email": "user@example.com",
  "organizationId": "org_12345",
  "organizationExternalId": "external_org_abc"
}
```

--------------------------------

### XML Canonicalization Example with Entity Expansion

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-technical-primer.mdx

This snippet demonstrates an XML document and its expected canonicalized output as per the XML Canonicalization specification, including handling of entity expansion. It highlights a security vulnerability related to entity expansion that should be avoided.

```xml
<!DOCTYPE doc [
<!ATTLIST doc attrExtEnt ENTITY #IMPLIED>
<!ENTITY ent1 "Hello">
<!ENTITY ent2 SYSTEM "world.txt">
<!ENTITY entExt SYSTEM "earth.gif" NDATA gif>
<!NOTATION gif SYSTEM "viewgif.exe">
]>
<doc attrExtEnt="entExt">
    &ent1;, &ent2;!
</doc>

<!-- Output.xml
<doc attrExtEnt="entExt">
    Hello, world!
</doc>
-->
```

--------------------------------

### SAML Assertion XML Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-technical-primer.mdx

This XML snippet represents a typical SAML 2.0 Response, including issuer information, digital signatures, status, and the assertion itself. It's used to convey authentication and authorization information between parties.

```xml
<?xml version="1.0" encoding="UTF-8"?><saml2p:Response Destination="https://auth.ssoready.com/v1/saml/saml_conn_bttep2j98bp0a30kas2462aek/acs" ID="id23923151776201191671508486" InResponseTo="saml_flow_0esp5wie0qgf848tf2yk8y5ex" IssueInstant="2024-07-19T20:54:07.107Z" Version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"><saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.okta.com/exkig8gdo63cjI4OD5d7</saml2:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/><ds:Reference URI="#id23923151776201191671508486"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><ds:DigestValue>LG8xAT5bB2FL8o080efFIvlxSgxo+XbHe7jpD0Zhboo=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>Pywv2l94wmFtmPgmUKSF7Q4gPPQbrWXTejp2FDHbm5g5NGBouUrYPKGcSfrysG/TUaUZevLiFc8VdkqUcThz+bPFgyt/ePomTJ1e2DfvAptK3wHjXYF88lZwk+p3JtJNohjfiq8wqEauSvM1jPpRfML3k5vOZS/diEzvrzaiB2noyupFZcCbgxSrdAdeVC6sjsUFu96FgjvHXwR41BCZftwrAanld7VZJ4P1GI30tJ6vwLh6H9ZvWx8MQ1vgMZuT2IDXifykeCLoo2GKqXyARIJGbzHzLWgRHBZqeDNskZWLg9HWjJy8eWpeye6OLs/7FuEj/GQGd/v8hMGoCL2U0A==</ds:SignatureValue><ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIIDqDCCApCgAwIBAgIGAZDMRerRMA0GCSqGSIb3DQEBCwUAMIGUMQswCQYDVQQGEwJVUzETMBEG
A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
MBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi05MjI1NDYzMjEcMBoGCSqGSIb3DQEJ
ARYNaW5mb0Bva3RhLmNvbTAeFw0yNDA3MTkxODMzMTJaFw0zNDA3MTkxODM0MTJaMIGUMQswCQYD
VQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsG
A1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi05MjI1NDYzMjEc
MBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC

ggEBALnkZbxmKDN9vSl7vwR1GgHXRLCQmvItOM8mbF19EUlx12tXzmA1wmafxZBo8+Zr7v4N9K+m
MPWlpNr9MKO0wUkrsv9NzuQeRXowHVsiQ6O2Vaxsb1o9kxjpR/Cego/sT2Cw2A8sACeQhWoQoe1h
jHOzIfvKf2OBpQ/BaelRCqZbYE9doZc1ufEp9xz6nSFRwJbF37pPo89qGeFPrYbsJkydysOM8SKO
On55UI8dv0iI0msQvBegPa1Bvauex0/UcIq6o6N9wc03pq26OulcXC5rKuUeNTnmA7mX04wOC+a2
jBe64W3aEGDCqk+ulw5hv8zsBAuD4vYsuRYkTCVtOgUCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEA
V+Mp98LuveJp4xFsC+6kv0f6w9HXDb/2KbUWiqxsocuJ9E+YEJv3tNC7F9uivvgGNah3hJENlin0
+5wZqY59cNYRhl227lLPJUS7XGNnlN0QG9ns0tgjgWB4e/yQbxoy+e9wzj+MKrurmkNEaZiymo+Y
OiSQuxQVw/JiZgifjNMIYmxF/12sKfn/6VHfhBAxDaUWLWzPq410On7KlOEb6FwIudRAaIL1NE2y
LckoOiWYbmZJt1A5d+2IwdGCoH6GIsu3Dp990YISiC1rCg4pFI4s3d+VEaVn1udKv3f/UMnNTOz0
jn3ZKSxD7x5NuHm8zEcDnxTiSXxkSs9RpZqrUg==</ds:X509Certificate></ds:X509Data></ds:KeyInfo></ds:Signature><saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"><saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></saml2p:Status><saml2:Assertion ID="id23923151778251751045676989" IssueInstant="2024-07-19T20:54:07.107Z" Version="2.0" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"><saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.okta.com/exkig8gdo63cjI4OD5d7</saml2:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/><ds:Reference URI="#id23923151778251751045676989"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><ds:DigestValue>5dyl0RFX07wyxI7u6Gw8u/GnO198XDNyj72TJY0KqLc=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>gEacn07XIGlNYhgL4FO5BvK2qeulGDgLfV6LXQoZV9shUbreHrK2C9sYCBECDrCJfFzsT8PLcbcK2DgEG34Zzl1RI893Qc+hMxvl/SQ/rli7EL4bE9t1tIYHLr5d88NKXqoixNcVwf1GYkDt8xw4NjS6i7cfnIgOnJ7TjdJVtLSMNjF+yOXbzEVG7oOE618eIb0GrVk21eEOhlHl+rGiaheyzJaaX3zKTISJjcS9195bhe1v4D8XMGVj4AJO73JLpMfs3v7QArgrhQNAlbCsysdlqUAIaZBEWJgjE/k2W38jzm728wFUsewHwbKt4k060CKQ5Y6/0Wexq/7PhEN78A==</ds:SignatureValue><ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIIDqDCCApCgAwIBAgIGAZDMRerRMA0GCSqGSIb3DQEBCwUAMIGUMQswCQYDVQQGEwJVUzETMBEG
A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
MBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGRldi05MjI1NDYzMjEcMBoGCSqGSIb3DQEJ

```

--------------------------------

### Docker Containers for SSOReady Components

Source: https://github.com/ssoready/docs/blob/main/fern/pages/self-hosting.mdx

This snippet lists the Docker container images provided by SSOReady for self-hosting various components. These containers manage the web application, API, SAML/SCIM proxy, database migrations, and the self-serve setup UI.

```shell
docker run --name ssoready-app ssoready/ssoready-app
docker run --name ssoready-api ssoready/ssoready-api
docker run --name ssoready-auth ssoready/ssoready-auth
docker run --name ssoready-migrate ssoready/ssoready-migrate
docker run --name ssoready-admin ssoready/ssoready-admin
```

--------------------------------

### SCIM Base URL Examples

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/scim-directories.mdx

Shows the typical structure of SCIM base URLs assigned by SSOReady. These URLs are used by identity providers to send SCIM requests. It includes variations for default and custom domains.

```text
https://auth.ssoready.com/v1/scim/scim_directory_...
```

```text
https://auth.yourcompany.com/v1/scim/scim_directory_...
```

--------------------------------

### SSOReady Database Migration Command

Source: https://github.com/ssoready/docs/blob/main/fern/pages/self-hosting.mdx

Command to run the SSOReady database migration tool. This command pulls the migration image, connects to a specified PostgreSQL database (using the provided connection string), and applies the necessary schema updates. It requires Docker to be installed and running.

```bash
docker run --network=host ssoready/ssoready-migrate:sha-18090f8 -d 'postgres://postgres:password@localhost/postgres?sslmode=disable' up
```

--------------------------------

### Canonicalization Vulnerability Example in Python

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-technical-primer.mdx

Demonstrates a vulnerability where working with the pre-canonicalization SAML payload can be tricked by attacker-inserted comments. It shows how to correctly use the canonicalized payload to prevent such attacks. This highlights the importance of SAML assertion processing.

```python
saml_payload = # ... input from the ACS URL
validated_payload = canonicalize_and_validate(saml_payload)

# watch out! you should work with validated_payload, not saml_payload
email = saml_payload["NameID"].children[0].text
```

--------------------------------

### Filter Users by Group ID

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

Lists SCIM users filtered by their group membership. Requires a `scim_group_id` which is the SSOReady-assigned ID for the SCIM Group. Supports pagination similar to general user listing.

```HTTP
GET /v1/scim/users?scim_group_id=scim_group_...
```

--------------------------------

### SAML AuthnRequest XML Payload

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-technical-primer.mdx

An example of the XML payload for a SAML AuthnRequest, which is part of initiating a SAML login. The Issuer element must match the SP Entity ID.

```xml
<AuthnRequest xmlns="urn:oasis:names:tc:SAML:2.0:protocol" Version="2.0" IssueInstant="2024-09-23T22:41:38.243Z">
    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
        https://auth.ssoready.com/v1/saml/saml_conn_5jvy8l0lgia5al1a45s9lo977
    </Issuer>
</AuthnRequest>
```

--------------------------------

### SCIM User Data Structure (JSON)

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

This JSON object represents the structure of a user object received from SSOReady during a SCIM sync. It includes essential fields like user ID, email, and a flag indicating if the user is deleted. The 'attributes' field is a flexible JSON object that can contain additional user details provided by the Identity Provider.

```json
{
  "id": "scim_user_...",
  "scimDirectoryId": "scim_directory_...",
  "email": "alice@example.com",
  "deleted": false, // if "true", go to "Deprovisioning (deleting) users" below
  "attributes": {
    // A JSON object of properties about this user. Exact schema depends on Identity Provider and your customer's setup.
  }
}
```

--------------------------------

### Deprovisioning (Deleting) Groups

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

SSOReady does not recommend implementing group deprovisioning unless there's a specific use-case, as support varies across Identity Providers. If implemented, it should mirror user deprovisioning logic but should not affect group members.

```APIDOC
## Deprovisioning Groups

### Description
Deprovisioning groups is generally not recommended unless a specific use-case necessitates it, due to inconsistent support across Identity Providers. If you choose to implement group deprovisioning, follow a process similar to user deprovisioning: match the group using its `id` and then either soft-delete or hard-delete it in your system. Importantly, deprovisioning a group should not affect the individual users within that group, as users can belong to multiple groups.
```

--------------------------------

### SCIM Group JSON Structure

Source: https://github.com/ssoready/docs/blob/main/fern/pages/scim-quickstart.mdx

This JSON object represents the structure of a SCIM group as returned by SSOReady. Key fields include a unique 'id', 'scimDirectoryId', 'displayName', and a 'deleted' flag. The 'attributes' field can contain additional, provider-specific properties.

```json
{
  "id": "scim_group_...",
  "scimDirectoryId": "scim_directory_...",
  "displayName": "Engineering",
  "deleted": false,
  "attributes": {
    // A JSON object of properties about this group. Exact schema depends on Identity Provider and your customer's setup.
  }
}
```

--------------------------------

### SSOReady Organization ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/organizations.mdx

Provides an example of a universally unique Organization ID used in SSOReady. This ID starts with 'org_' and is a unique identifier for each organization.

```text
org_ac4vpckpze4ugjm70lzkmtwd2
```

--------------------------------

### SCIM Group ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/scim-groups.mdx

Demonstrates the format of a SCIM group ID, which is a universally unique identifier starting with 'scim_group_...'.

```plaintext
scim_group_1b480vb5wd27avbqunvl1sa1s
```

--------------------------------

### SCIM Directory ID Example

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/scim-directories.mdx

Illustrates the format of a unique SCIM directory identifier used within SSOReady. These IDs are universally unique and start with 'scim_directory_'.

```text
scim_directory_aler4q1vev4x0uxoxxzk696ou
```

--------------------------------

### User Matching SQL Query

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-logins.mdx

This SQL query demonstrates how to match a user based on their email and organization ID received from SSOReady.

```SQL
-- $1 is the `email` from SSOReady
-- $2 is the `organizationExternalId` from SSOReady

select id from users where email = $1 and organization_id = $2;
-- or, if you don't have organization_id on users
select id from users where email = $1;
```

--------------------------------

### Retrieve SAML Email from Firebase User

Source: https://github.com/ssoready/docs/blob/main/fern/pages/firebase.mdx

This JavaScript code snippet shows how to retrieve the SAML email address of a logged-in user from Firebase Authentication. It accesses the user's provider data and filters for the SSOReady OIDC provider to get the relevant user identifier, which corresponds to the SAML email in this setup.

```javascript
const auth = getAuth();
const samlEmail = auth.currentUser.providerData
    .find(({ providerId }) => providerId === "oidc.ssoready-saml")
    .uid
```

--------------------------------

### Get SCIM Group by ID

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/scim-groups.mdx

Retrieve a specific SCIM group by its unique identifier from the SSOReady system.

```APIDOC
## GET /ssoready/api/scim/groups/{id}

### Description
Retrieves a specific SCIM group by its unique ID.

### Method
GET

### Endpoint
/ssoready/api/scim/groups/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the SCIM group.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the SCIM group (e.g., 'scim_group_1b480vb5wd27avbqunvl1sa1s').
- **displayName** (string) - The human-readable name of the group, assigned by the customer's identity provider.
- **deleted** (boolean) - Indicates if the group has been deprovisioned or deleted in the identity provider. `true` if deleted, `false` otherwise.
- **attributes** (object) - A collection of arbitrary attributes provisioned by the identity provider. The structure and content of these attributes can vary significantly between identity providers.

#### Response Example
{
  "id": "scim_group_1b480vb5wd27avbqunvl1sa1s",
  "displayName": "Engineering Team",
  "deleted": false,
  "attributes": {
    "costCenter": "12345",
    "department": "Technology"
  }
}
```

--------------------------------

### Get SAML Redirect URL

Source: https://github.com/ssoready/docs/blob/main/fern/pages/ssoready-concepts/saml-login-flows.mdx

Retrieves the SAML redirect URL for initiating the SSO authentication flow.

```APIDOC
## GET /api/saml/redirect-url

### Description
This endpoint is used to obtain the SAML redirect URL. This URL initiates the Single Sign-On (SSO) authentication process by redirecting the user to their identity provider.

### Method
GET

### Endpoint
/api/saml/redirect-url

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address of the user attempting to log in.

### Request Example
```
GET /api/saml/redirect-url?email=user@example.com
```

### Response
#### Success Response (200)
- **redirect_url** (string) - The URL to which the user should be redirected to start the SAML authentication flow.

#### Response Example
```json
{
  "redirect_url": "https://idp.example.com/saml/sso?id=..."
}
```
```

--------------------------------

### SAML Response Structure with Assertion

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-technical-primer.mdx

Illustrates the structure of a SAML 2.0 protocol response containing a SAML assertion, highlighting the necessary namespace declarations from the top-level response.

```xml
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml:Assertion>
        <!-- ... -->
    </saml:Assertion>
</samlp:Response>
```

--------------------------------

### Run SSOReady Database Migrations

Source: https://github.com/ssoready/docs/blob/main/fern/pages/self-hosting.mdx

Applies necessary database migrations to a PostgreSQL database using the `ssoready/ssoready-migrate` Docker image. The command ensures the database has the required tables for SSOReady functionality and is idempotent.

```bash
docker run --network=host ssoready/ssoready-migrate:main -d 'postgres://...' up
```

--------------------------------

### SAMLSignedInfo XML with Namespaces

Source: https://github.com/ssoready/docs/blob/main/fern/pages/saml-technical-primer.mdx

This XML snippet shows the SignedInfo element with necessary XML namespaces defined. Including namespaces like 'xmlns:ds' is essential for correct canonicalization and signature verification in SAML assertions.

```xml
<ds:SignedInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
    <ds:Reference URI="#id23923151778251751045676989">
        <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        </ds:Transforms>
        <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
        <ds:DigestValue>
            5dyl0RFX07wyxI7u6Gw8u/GnO198XDNyj72TJY0KqLc=
        </ds:DigestValue>
    </ds:Reference>
</ds:SignedInfo>
```