-
Notifications
You must be signed in to change notification settings - Fork 5
Single Sign On
Clients who maintain their own customer login system may conduct Single Sign On (SSO) through the SnapMD virtual care management system. SSO makes SnapMD seamless to users and enables control over access to consultations.
SnapMD uses JSON Web Token (JWT) to ensure that users may log in to the system securely. The JWT is easy to use and should fit into most systems with minimal work.
The SSO process with JWT uses asymmetrical authentication.
SnapMD must have an account set up for a specific user before that user may implement SSO. Usually, this account can be set up, for a patient or staff (clinician or admin), via the SnapMD API. See the API area pages for patients and hospital staff pages for details.
To set up SSO for a user's site, SnapMD requires the public half of a 2018 RSA key pair and the issuer name the site uses in its JWT data. Instructions for both of these will be provided when SnapMD receives an SSO request.
The key pair ensures that a login request comes from a known server by signing it cryptographically. The issuer name matches a site's login request to its public key, which SnapMD has on file. These measures prevent an attacker from tampering with JWT data.
For most purposes, clients should use a JWT library in the programming language their site uses. While it is possible to build the token manually, there is more chance for coding errors to happen. A list of JWT libraries can be found at JWT.io. To ensure that the library can generate the required data, it must support RS256 encryption as well as signing.
SnapMD validates the following fields in JWT:
- jti (string): A unique identifier for the JWT. Should be in GUID format if Secured Session Option is included.
- email (string): The e-mail address for the user. This is used to identify the account in the SnapMD system.
- role (string): The role of the user to be logged on. Currently, "patient", "clinican" and "admin" are supported.
- iss (string): The issuer. This should be the issuer name that you verified with SnapMD support when setting up SSO.
- aud (string): The audience for this token. It should always be "snapmd".
- exp (integer): A timestamp (UNIX time) indicating a time after which the token should be considered invalid. SnapMD recommends that it be the current time plus 5-15 minutes. Longer expiration periods can be used in the sandbox for troubleshooting.
SnapMD does not check the referrer header or do any source restriction on SSO calls. A token is verified by its cryptographic signature. As such, the private key a user employs to log into the system must be protected at all times. If this key is compromised, an attacker can impersonate users on a client site.
The JWT library, from the data provided by the client, generates a string of characters called a token string. This signed token allows a user to log directly into the system.
This token is combined with a client's web site address to create the login URL that the user will access. The formats are:
- Patient access:
https://DOMAIN/customer.access?jwt=TOKEN[&page=selfscheduling&searchtext=PROVIDER_NAME&op=SECURED_SESSION_OPTION&language=[en|en-GB|es|es-MX]] - Clinician access:
https://DOMAIN/clinician.access?jwt=TOKEN - Admin access:
https://DOMAIN/admin.access?jwt=TOKEN
In the above URLs, "DOMAIN" is the domain for the client site and TOKEN is the JWT token created for the user. Redirect the user to this login URL or provide a clickable link, and the user will be taken to their homepage in the SnapMD system. The Patient access URL may contain optional parameters for target page and search text as part of redirect.