All services require a valid token from the IdP when called.

All services require TLS (version 1.2 or higher) for transport security.

In line with industry best practices the HIMSA IdP does not allow IFRAME based usage for any kind of user interactive authentication. An X-FRAME-OPTIONS HTTP header is always returned with the value ‘SameOrigin’.

Authentication

Noah ES contains an Identity Provider that supports OAuth 2.0 and OpenId Connect. The Identity Provider (IdP) is used for Authentication.

1. Request

Parameters that must be supplied:

URI and port number
- Global endpoint: https://idp.himsa-sso.com:443
- If wanting to force a specific region
  - EU Production: https://idp-eu.himsa-sso.com:443
  - US Production: https://idp-us.himsa-sso.com:443
  - AU Production: https://idp-au.himsa-sso.com:443
- QA environment: E.g. https://idp-qa.himsa-sso.com:443 or https://idp-qa-eu.himsa-sso.com:443
ClientId: Supplied by HIMSA
Client secret: Supplied by HIMSA if required
Scope: openid profile noah.cloud.app.users.api
- If relevant for your app and app registration allows: offline_access
Flow: Authorization Code + PKCE
RedirectURI: IdP will redirect the client to this after successful authentication. You must inform HIMSA about this, because we need to whitelist it
Extra options
- culture-lcid: Culture LCID code for localizing the website

2. Response

When the client is redirected to the RedirectURI, the response will contain:

auth_code
- Must be exchanged afterwards for an id token + access token
- It is prefixed with the region code, e.g. “us.”. We suggest that you use this to redirect the user to a hosted version of your web based app located in the same location as the account that the user selected (e.g. redirect from app.company.com to app-eu.company.com). Especially important for Noah ES accounts, to avoid processing e.g. EU patient data in your data center outside the EU

2a. Web-based apps with a server component

We suggest that you hook into the OIDC/OAuth flow (in .NET e.g. in OnAuthorizationCodeReceived) and use this to redirect the user to a hosted version of your web based app located in the same location as the account that the user selected (e.g. redirect from app.company.com to app-eu.company.com), initially skipping the exchange of the auth_code. Especially important for Noah ES accounts, to avoid processing e.g. EU patient data in your data center outside the EU.

After redirect to your regional host, your app should see the user as unauthenticated and initiate a new log in flow, which this time will make use of the existing IdP SSO session and silently issue a new auth_code.

Rationale:

If deciding to host your app in multiple regions e.g. because of various requirements about data residency (e.g. GDPR) and any desires about of security, deployment, maintenance, high availability, latency, performance etc. consider this:

You probably don’t want the user to make an up-front decision about which region is the target (also: the user can select an account from a different region during log in), unless you want to explicitly select a region, in which case you probably wouldn’t use the global endpoint but rather the regional IdP endpoints.

We encourage you to use different client secrets for each of your regions (e.g. for security reasons), but use the same clientId in all regions (if it is the same app used in all regions). That also means that you probably won’t be able to exchange the initial auth_code for an id+access token that you received on your global app endpoint, if the auth_code was intended for at different region. Even if you were to know the client secret, you shouldn’t try to pass the access token to the other region (at least not unencrypted). Also simply redirecting to your regional endpoint with the initial auth_code won’t work, as the PKCE code verifier won’t be known by the other region.

2b. Desktop (and SPA) apps

Assuming you cannot force the auth_code exchange on a specific regional IdP according to the prefix of the auth_code, you can simply exchange it via the global idp.himsa-sso.com endpoint. We will exchange it for you internally with the issuing regional IdP and return the id token and access token.

3. Exchange auth_code for an id token and/or access token

Note: This is done automatically if you are using HIMSA's .NET Client.

Id token

tenantid claim: The tenantId that the user selected

Access and refresh tokens may vary greatly in length. Make no assumptions about the contents. It can change at any point in time

4. Connecting to API

We suggest that you use the URI returned as claim “api” in the id token, especially if using the global IdP endpoint that allows the user to select any account from any of our regions.

HIMSA's .NET Client

Either use the constructor that takes an access token or a refresh token as input

5. Renewal of access token