# General SSO Setup

Welkin Health supports Single Sign-On (SSO) via the SAML 2.0 protocol, allowing your team members to log in using your organization's existing identity provider (IdP) instead of maintaining separate Welkin credentials. This page covers the general SSO setup process applicable to any SAML 2.0-compatible IdP.

## Why use SSO?

* **Improved security** – authentication is managed by your IdP, which can enforce your organization's password policies, MFA, and conditional access rules
* **Reduced friction** – care team members log in once and access Welkin without a separate username/password
* **Centralized access control** – deprovisioning a user from your IdP automatically removes their Welkin access

## Supported identity providers

Welkin supports any SAML 2.0-compliant IdP, including:

* Google Workspace (see [Google SSO Setup](/integrations/single-sign-on/google-sso-setup.md))
* OneLogin (see [OneLogin Setup and Configuration](/integrations/single-sign-on/onelogin-setup-and-configuration.md))
* Okta
* Azure Active Directory / Microsoft Entra ID
* Ping Identity
* Other SAML 2.0 providers

## General SAML setup steps

### Step 1: Gather Welkin's Service Provider (SP) metadata

1. Log in to the Welkin Admin portal
2. Navigate to **Settings → Single Sign-On (SSO)**
3. Download the **SP Metadata XML** or note the following values:
   * **Entity ID (Audience URI)** – your Welkin SP entity ID
   * **ACS URL (Assertion Consumer Service URL)** – the URL where your IdP sends SAML responses
   * **SP Certificate** – used by the IdP to encrypt assertions (optional but recommended)

### Step 2: Create a SAML application in your IdP

In your IdP's admin console:

1. Create a new SAML application or integration
2. Enter Welkin's **Entity ID** in the "Audience" or "SP Entity ID" field
3. Enter Welkin's **ACS URL** in the "ACS URL", "Reply URL", or "Redirect URI" field
4. Configure attribute mappings – Welkin requires:
   * `email` – the user's email address (must match their Welkin user account)
   * `firstName` – user's first name
   * `lastName` – user's last name
5. Save and note the IdP's **SSO URL**, **Entity ID**, and **X.509 Certificate**

### Step 3: Configure SSO in Welkin Admin

1. Return to **Settings → Single Sign-On** in the Welkin Admin portal
2. Enter your IdP details:
   * **IdP Entity ID** – from your IdP settings
   * **SSO URL** – the SAML login URL from your IdP
   * **IdP Certificate** – paste the X.509 certificate from your IdP
3. Click **Save**
4. Optionally, enable **Force SSO** – prevents users from logging in with email/password, requiring SSO for all logins

### Step 4: Test SSO

1. Click **Test SSO** in the Welkin Admin SSO settings
2. You will be redirected to your IdP's login page
3. Log in with a test user account
4. Confirm you are redirected back to Welkin and logged in successfully
5. Verify the user's name and email appear correctly in Welkin

## SSO and user provisioning

SSO handles authentication (verifying identity) but not provisioning (creating accounts). Users must still have a Welkin account created before they can log in via SSO. For automated user provisioning, see [User Provisioning: API](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/admin/user-provisioning-api.md).

## Troubleshooting

**"User not found" after SSO:** The email from the IdP does not match a Welkin user account. Create the user account first or verify the email attribute mapping.

**"Invalid SAML response":** The certificate may be expired or the ACS URL may be incorrect. Re-download the IdP certificate and confirm the ACS URL matches exactly.

**Redirect loop after login:** Check that the ACS URL in your IdP does not have a trailing slash mismatch (e.g., `https://app.welkin.com/sso/callback` vs. `https://app.welkin.com/sso/callback/`).


---

# 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.welkinhealth.com/integrations/single-sign-on/general-sso-setup.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.