# SSO Sign-on

This data model allows you to connect to other applications via Redox by securely sharing the login context. This is common for providers launching an integrated application from within the EHR system. With SSO, providers can automatically log in, as well as pass context, like which patient and visit are open. [Learn more about how Redox supports SSO](https://docs.redoxengine.com/permalink/5t0LD9YzCvQFnckuDvQtoC).

Redox supports the following standards for launching SSO: 

- IdP-initiated SAML
- [SMART on FHIR](https://docs.redoxengine.com/permalink/1D6qKYsDD8qdf1AG4BRwKu)
- [OpenID Connect](https://docs.redoxengine.com/fhir-api-actions/authentication-and-app-launch/launch-app-within-an-ehr-system/#o-auth-or-open-id-connect-providers)

As with all of our data models, we provide abstraction, standardization, and normalization services to deliver a consistent experience for developers.

Send login context in the body of a `POST` request. 

This event type provides a mapping between existing Redox sources and destinations, as well as the claims in the JSON web token in a Redox data model format.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Meta` | object | Yes |  |
| `Meta.DataModel` | string | Yes | SSO |
| `Meta.EventType` | string | Yes | Sign-on |
| `Meta.EventDateTime` | string or null | No | DateTime of the event. *[ISO 8601 Format](http://en.wikipedia.org/wiki/ISO_8601)* |
| `Meta.Test` | boolean or null | No | Flag as a test message |
| `Meta.Source` | object | No | Where the message originated. *Included in messages from Redox* |
| `Meta.Source.ID` | string or null | No | ID of the source. *UUID* |
| `Meta.Source.Name` | string or null | No | Name of the source |
| `Meta.SessionID` | string or null | No | Session ID to be passed through for 3rd party sessions. *This is used for SMART App Launch and other OAuth/OpenID Connect flows where an access token is provided in addition to the SSO claims. The SessionID can be used on subsequent Redox API requests to fetch data.* |
| `Meta.SessionBaseURL` | string or null | No | The Base URL to use when issuing Redox FHIR queries within the SSO session context. *See our docs on [SMART via Redox](https://docs.redoxengine.com/basics/redox-fhir-api/understanding-smart-on-fhir/#your-sso-destination) for more details on how to use this field.* |
| `Meta.Destinations` | Array of object | No | List of destinations to send your message to. All messages must have at least one destination. Queries accept only one destination. *Required when sending data to Redox* |
| `Meta.Destinations[].ID` | string or null | No | ID of the destination. *UUID* |
| `Meta.Destinations[].Name` | string or null | No | Name of the destination |
| `Meta.FacilityCode` | string or null | No | Code for the facility related to the message. *Only use this field if a health system indicates you should. The code is specific to the health system's EHR and might not be unique across health systems. In general, the facility fields within the data models (e.g. OrderingFacility) are more reliable and informative.* |
| `Subject` | string | Yes | Subject Identifier. A locally unique and never reassigned identifier for the End-User, which is intended to be consumed by the Client. *The `Subject` value is a case sensitive string.* |
| `Expiration` | string | Yes | Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. *Typically we send date/times in ISO 8601 but this is sent as an epoch to stay compatible with JWT.* |
| `IssuedAt` | string | Yes | Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. *Typically we send date/times in ISO 8601 but this is sent as an epoch to stay compatible with JWT.* |
| `UserId` | string or null | No | End-User's user identification, the logical entity used to identify a user on a software, system, or websites. |
| `Name` | string or null | No | End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences. |
| `FirstName` | string or null | No | Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters. |
| `LastName` | string or null | No | Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters. |
| `MiddleName` | string or null | No | Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used. |
| `EmailAddress` | string or null | No | End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. This field is not guaranteed to be unique. |
| `NPI` | string or null | No | End-User's NPI number. Note that not all providers will have an NPI number. |
| `ProviderSpecialty` | string or null | No | The provider specialty. Note that not all providers will have a specialty. |
| `TimeZone` | string or null | No | String from [IANA](https://www.iana.org/time-zones) time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles. |
| `Locale` | string or null | No | End-User's locale, represented as a [BCP47 [RFC5646]](https://tools.ietf.org/html/bcp47) language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties MAY choose to accept this locale syntax as well. |
| `PhoneNumber` | object | No |  |
| `PhoneNumber.Office` | string or null | No | End-User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678. |
| `Patient` | object | No |  |
| `Patient.Identifiers` | Array of object | No | An array of identifiers for the patient. *Not all SSO sessions will have a Patient context attached.* |
| `Patient.Identifiers[].ID` | string or null | No | The identifier. |
| `Patient.Identifiers[].IDType` | string or null | No | The type of the identifier. *For example, MRN.* |
| `Patient.Demographics` | object | No |  |
| `Patient.Demographics.FirstName` | string or null | No | First Name of the Patient |
| `Patient.Demographics.LastName` | string or null | No | Last Name of the Patient |
| `Patient.Demographics.MiddleName` | string or null | No | Middle Name of the Patient |
| `Patient.Demographics.DOB` | string or null | No | Date of birth of the Patient |
| `Patient.Demographics.Sex` | string or null | No | Patient's Sex |
| `Patient.Demographics.PhoneNumber` | object | No |  |
| `Patient.Demographics.PhoneNumber.Home` | string or null | No | Patient's home phone number. *In E. 164 Format. (e.g. +16085551234)* |
| `Patient.Demographics.PhoneNumber.Office` | string or null | No | Patient's office phone number. *In E. 164 Format. (e.g. +16085551234)* |
| `Patient.Demographics.PhoneNumber.Mobile` | string or null | No | Patient's mobile phone number. *In E. 164 Format. (e.g. +16085551234)* |
| `Patient.Demographics.Address` | object | No | Patient's home address |
| `Patient.Demographics.Address.StreetAddress` | string or null | No | Street address |
| `Patient.Demographics.Address.City` | string or null | No | City |
| `Patient.Demographics.Address.State` | string or null | No | State |
| `Patient.Demographics.Address.ZIP` | string or null | No | ZIP |
| `Patient.Demographics.Address.County` | string or null | No | County |
| `Patient.Demographics.Address.Country` | string or null | No | Country. Value set 39791e31-0cee-4c58-a6c1-3d9e2c71d13b: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, IO, CM, CL, CO, CI, DK, EC, ER, FK, TF, GM, GI, GW, VA, IS, IM, JP, KI, LS, LT, MK, MV, MX, MS, NA, NC, MP, PK, PG, PL, RU, PM, SA, SG, SB, SS, SE, TZ, TO, TV, US, VN, EH, ZW, BQ, BR, BF, CA, TD, KM, CK, CU, DO, EE, FI, GE, GL, GN, GY, IN, IE, JE, KW, LB, LY, MO, ML, MR, MN, MM, NZ, NU, OM, PY, PT, RO, KN, SN, RS, ZA, LK, SJ, SY, TK, TM, UG, UM, UZ, WF, BA, BG, CV, CX, CD, CW, DJ, GQ, FO, PF, DE, GD, GG, HT, HK, IR, IL, KE, KG, LU, MY, MT, MU, ME, MZ, NP, NF, PW, PH, QA, BL, MF, ST, SX, SI, GS, SR, TJ, TG, TN, UA, VU, VG, BW, BN, KH, KY, CC, CR, CY, EG, FJ, FR, GH, GP, GU, HN, IQ, JM, KZ, KP, LA, LR, MW, MH, YT, MD, MA, NI, NG, NO, PA, PN, RE, RW, LC, SM, SC, SK, ES, CH, TH, TT, TR, GB, VE, VI, ZM, BV, BI, CF, CN, CG, HR, CZ, DM, SV, ET, GF, GA, GR, GT, HM, HU, ID, IT, JO, KR, LV, LI, MG, MQ, FM, MC, NR, NL, NE, PS, PE, PR, SH, VC, WS, SL, SO, SD, SZ, TW, TL, TC, AE, UY, YE, DR |
| `Visit` | object | No |  |
| `Visit.VisitNumber` | string or null | No | Number for the visit |
| `Visit.Location` | object | No | Location of the visit. |
| `Visit.Location.Type` | string or null | No | Type of location. *Examples: Clinic, Department, Home, Nursing Unit, Provider's Office, Phone* |
| `Visit.Location.Facility` | string or null | No | Facility. *Example: Community Hospital* |
| `Visit.Location.FacilityIdentifiers` | Array of object | No | List of IDs specific to this facility |
| `Visit.Location.FacilityIdentifiers[].ID` | string or null | No | An ID specific to this facility |
| `Visit.Location.FacilityIdentifiers[].IDType` | string or null | No | The source or system to which this ID pertains. *Could be an OID or a human-readable name* |
| `Visit.Location.Department` | string or null | No | Department |
| `Visit.Location.DepartmentIdentifiers` | Array of object | No | List of IDs specific to this department |
| `Visit.Location.DepartmentIdentifiers[].ID` | string or null | No | An ID specific to this department |
| `Visit.Location.DepartmentIdentifiers[].IDType` | string or null | No | The source or system to which this ID pertains. *Could be an OID or a human-readable name* |
| `Visit.Location.Room` | string or null | No | Room. *Example: 136* |
| `Order` | object | No |  |
| `Order.ID` | string or null | No | ID of the order assigned by the placing system |

## Example

```json
{
  "Meta": {
    "DataModel": "SSO",
    "EventType": "Sign-on",
    "EventDateTime": "2017-11-02T20:37:41.634Z",
    "Test": true,
    "Source": {
      "ID": "7ce6f387-c33c-417d-8682-81e83628cbd9",
      "Name": "Redox Dev Tools"
    },
    "SessionID": "abcdefghijklmnop",
    "SessionBaseURL": "https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development",
    "Destinations": [
      {
        "ID": "af394f14-b34a-464f-8d24-895f370af4c9",
        "Name": "Redox EMR"
      }
    ],
    "FacilityCode": null
  },
  "Subject": "https://healtsystem.com/provider/4356789876",
  "Expiration": "2026-11-20T22:33:54.042Z",
  "IssuedAt": "2026-11-20T22:18:54.042Z",
  "UserId": null,
  "Name": "Pat Granite MD",
  "FirstName": "Pat",
  "LastName": "Granite",
  "MiddleName": null,
  "EmailAddress": null,
  "NPI": "4356789876",
  "ProviderSpecialty": null,
  "TimeZone": "America/Chicago",
  "Locale": "en-US",
  "PhoneNumber": {
    "Office": "+16085551234"
  },
  "Patient": {
    "Identifiers": [
      {
        "ID": "0000000001",
        "IDType": "MR"
      },
      {
        "ID": "e167267c-16c9-4fe3-96ae-9cff5703e90a",
        "IDType": "EHRID"
      },
      {
        "ID": "a1d4ee8aba494ca",
        "IDType": "NIST"
      }
    ],
    "Demographics": {
      "FirstName": "Timothy",
      "LastName": "Bixby",
      "MiddleName": "Paul",
      "DOB": "2008-01-06",
      "Sex": "Male",
      "PhoneNumber": {
        "Home": "+18088675301",
        "Office": null,
        "Mobile": null
      },
      "Address": {
        "StreetAddress": "4762 Hickory Street",
        "City": "Monroe",
        "State": "WI",
        "ZIP": "53566",
        "County": "Green",
        "Country": "US"
      }
    }
  },
  "Visit": {
    "VisitNumber": null,
    "Location": {
      "Type": "Inpatient",
      "Facility": "RES General Hospital",
      "FacilityIdentifiers": [],
      "Department": "3N",
      "DepartmentIdentifiers": [],
      "Room": "136"
    }
  },
  "Order": {
    "ID": null
  }
}
```
