Single Sign-On Setup

1. Overview

Ursa Studio’s preferred setup for SSO is to build SSO authentication into the web server (sometimes called the Application Load Balancer or the Reverse Proxy) that sits in front of the Ursa Studio application. This could take the form of a Shibboleth-SP-enhanced Apache Webserver in an on-premise deployment, a Cognito-enhanced Application Load Balancer in an AWS deployment, or the Authentication blade of the Azure App Service. In all these arrangements, the web server restricts traffic to Ursa Studio such that only properly authenticated users are allowed in, and the user details are injected into the HTTP header by the web server. Unless told not to via the ESCHEW_SSO_SIGNATURE_VERIFICATION environment variable, Ursa Studio verifies cryptographically that the HTTP headers were in fact created by the proper authority.

In this mode, users will never see the Ursa Studio login screen. Rather, their browser will be redirected to their Identify Provider, and upon successful login will be taken directly into Ursa Studio.

An alternate setup is Delegated Authentication, in which the Ursa Studio login screen is exposed to the user but Ursa Studio simply passes on the username and password to a delegated service to perform authentication. This provides the centralized user management benefits of SSO, but does not provide the user convenience of not having to enter credentials into Ursa Studio. This setup is currently supported for AD and Okta.

In both regimens, Ursa Studio authorization (user type, report grants, scoping restrictions, etc) is performed by Ursa Studio, so even with SSO authentication all users must be independently set up in the Ursa Studio User Manager, with an identical username (typically, but not necessarily, an email address) to the SSO service.

2. Sample AWS Setup

2.1 Create User Pool in AWS Cognito

In this sample setup we’ll power the AWS Cognito user pool via an app client that connects to an Okta SAML IdP, but the same process should work for any IdP.

Add SAML as a "Federated identity provider". Your sign-in options should be just the user name, not case sensitive. Do not enable self-service password recovery, as this is handled by Ursa Studio. Do not enable self-registration. The required attributes are just email.

Add an app client. The defaults here again are fine, although you need only keep the ALLOW_REFRESH_TOKEN_AUTH flow configuration. Also, set the access token expiration and the ID token expiration to be 15 minutes, and the refresh token expiration to 60 minutes (i.e. the minimum values for each). Do not leave these as the defaults!

Add a domain name, per the amazoncognito.com convention you’ll see in the setup screen.

2.2 Configure Okta (or comparable Identity Provider)

Add a SAML 2.0 web app. Via admin -> Add App -> New App -> Web -> SAML 2.0

The SSO URL and the Audience URI you’ll enter for Okta will be driven by the Domain Name and the User Pool ID from Cognito, for example:

SSO URL: https://ursa-sso-test.auth.us-east-1.amazoncognito.com/saml2/idpresponse
Audience URI: urn:amazon:cognito:sp:us-east-1_m0sCvK0nr

Attribute statements: Email / Unspecified / user.email

Once saved, assign to the users in your IdP to whom you wish to give access to Ursa Studio. These users will have to have user accounts in Ursa Studio as well, to dictate their in-app permissions, and the username must be identical to the email address in the IdP.

Copy the metadata URL, e.g. https://ursahealth-ops.okta.com/app/.../sso/saml/metadata

2.3 Finish Cognito Setup

From the “Identity providers” link in the leftbar of the Cognito pool, and add a SAML provider, pasting in that metadata URL from Okta. The name of the identity provider can be Okta.

From the “Attribute mapping” link in the leftbar of the Cognito pool, and you’ll want to capture the “Email” SAML attribute into the “Email” user pool attribute.

From the “App client settings” link in the leftbar of the Cognito pool, enable both the Okta and Cognito User Pool. The URLs to be inputted here are based on the domain name that Ursa Studio will be running under, e.g.:

Callback URL: https://aws-test.ursahealth.com/oauth2/idpresponse
Sign out URL: https://aws-test.ursahealth.com/logout

The only allowed OAUTH flow should be “Authorization code grant.” The allowed scopes can be email, openid, aws.cognito.signin.user.admin, and profile. The app client needs to generate a client secret.

2.4 Enable Cognito Pool

Enable the Cognito pool from within the AWS Application Load Balancer’s 443 listener. Click to view/edit the listener rules, and make sure the THEN step authenticates through the Cognito user pool and app client you’ve just set up, before forwarding to the application server’s target.

If you have a health check running in the Application Load Balancer's Target Group, you should set the health check path to /App/health to avoid needless errors in the logs. The health check requests are not going to have the appropriate SSO headers, and requests to this path are specifically excluded from alerts complaining about missing SSO headers.

3. Sample Azure Setup

Note that you should only follow these steps if your instance of Ursa Studio is hosted in Azure. If Ursa Studio is hosted in AWS, even if you're using AzureAD as your identity provider, then you should follow the "Sample AWS Setup" steps, above.

3.1 Register App in Azure AD

From the App Registration blade of Azure AD, create a new registration for “accounts in this organizational directory only.” The redirect URI should be https://your.ursastudio.url/.auth/login/aad/callback

Copy the Application (client) ID and the Directory (tenant) ID for later use

From the authentication blade of this Azure AD App Registration, set the front-channel logout URL to
https://your.ursastudio.url/logout

Check ID tokens (for implicit and hybrid flows) and set the supported account type to be Single Tenant.

From the Expose an API blade click the “set” link. Set the application ID URI to be
https://your.ursastudio.url
and add a scope called user_impersonation.

From the Certificates & Secrets blade, create a new client secret and copy the value for later use.

3.2 Enable Authentication in App Service

From the Authentication (Preview) blade of the App Service, add a Microsoft/Azure AD identity provider. You’ll want to “provide the details of an existing app registration”. Enter the Application ID from step one and set the Issuer URL to be https://login.microsoftonline.com/<tenant-id-from-above>/v2.0

Require authentication and choose HTTP 302 for unauthenticated requests. Add the client secret that you created in the previous step. Otherwise the defaults are fine.

4. Ursa Studio Setup for SSO

Note that you should never put Ursa Studio in TRUST_SSO_AUTH mode if it is directly accessible from the Internet without first passing through an SSO-enforcing load balancer. Passing in these environment variables greatly reduces the authentication the Ursa Studio performs natively by default, so it is imperative that authentication is happening appropriately before any requests can make it to Ursa Studio.

To enable SSO mode, set the environment variable TRUST_SSO_AUTH=true.

If the SSO service puts the user details in a JWT (as with AWS Cognito and Azure App Service), it is necessary to identify the HTTP data header via the SSO_DATA_HEADER environment variable, for example:

SSO_DATA_HEADER=x-amzn-oidc-data
Or 
SSO_DATA_HEADER=x-ms-token-aad-id-token

If the SSO service simply adds the email address in plain text as an HTTP header, then it is necessary to identify that in the SSO_EMAIL_HEADER environment variable. Note that in this case it is not possible to verify cryptographically that the user email address was added by the web server. As such, it is also necessary to add the environment variable ESCHEW_SSO_SIGNATURE_VERIFICATION=true.

When SSO is working correctly, the Ursa Studio login screen will be bypassed altogether. If users are ever sent to the Ursa Studio login screen after signing in through their SSO system, that means that Ursa Studio was unable to identify or verify the user details from the user claims forwarded on from the SSO system. In this case, the application logs typically will contain a descriptive error message of what went wrong.

When a user clicks the “Logout” button from within Ursa Studio, the Ursa Studio session will be destroyed, but their user session for the SSO service will not be affected. Thus if the user navigates immediately back to Ursa Studio, the SSO service will immediately create a new, authenticated Ursa Studio session, as if the logout had never happened.

This logout behavior is common for SSO systems, which often do not want a constituent site to be able to end the session across the entire SSO system. That said, if customers want an Ursa Studio logout to destroy the SSO session, they can add the logout endpoint of the SSO system as the environment variable SSO_LOGOUT_REDIRECT_URL, to which Ursa Studio will redirect the browser after it ends the Ursa Studio session. If this variable is not set, Ursa Studio will by default redirect to the ursahealth.com home page upon logout.

5. Ursa Studio Setup for Delegated Authentication

To delegate authentication to Okta without full SSO, add the environment variable OKTA_DOMAIN to the deployment. To delegate authentication to AD, add the environment variables LDAP_URL and LDAP_BASE_DN to the deployment.