How to configure Single sign-on (SSO) for your OH portal employee companies

What is the context of the article?

Meddbase supports the setup of Single sign-on or ‘SSO’ specifically using SAML2 protocol. This enables a company's authorised managers to access the Occupational Health portal via SSO.

What is the purpose of the article?

This article

• Outlines how Single sign-on works
• Summarises the configuration tasks that need to be carried out, and by whom
• Outlines steps to carry out the configuration tasks

What are the pre-requisites for this article?

To use this article and undertake configuration, you need a good working knowledge of SAML 2.0.

How does Single sign-on work?

The SSO is set up against individual employer companies rather than at the chamber level. A unique identifier is used per employer company to identify the company at the portal end.

This unique identifier is configured at the identity provider end as well and set as a 'cookie' on the portal to identify the SSO configuration to be used.

A sign in request from the external identity provider is received at the Meddbase system site. This is validated against the identity provider certificate. The user is matched using an email claim from the identity provider against the local email ("work email" field on manager's record) for the user profile. If this is successful, it generates a URL with a short-lived login token pointing to the portal configured for the chamber.

The portal login then uses the authentication token with a 'direct-login' API call which logs in the user to the employer's OH portal.

Important points to note

1. As of the time of writing, SSO has been tested and implemented against Azure AD Identity provider.
2. Single sign-out is not supported.
3. Any subsequent attempt to access the OH Portal will take the user directly to the identity provider URL, where the user can log in (if they don't already have a logged in session).
4. The SSO can also be IdP-initiated.

What are the configuration tasks that need to be carried out?

There is a range of actions for configuration that need to take place. These actions and the role of the user are outlined in the table below.

The tasks that need to be carried out by the IT Administrator of the employer organisation (i.e. the client), are highlighted with a light-grey row colour.

How are the configuration tasks carried out?

Guidance on how to carry out these tasks is outlined below.

Task 1 - Find the API Domain key from Meddbase and share it with the employer organisation

To find the API domain key:

1. In the Meddbase chamber, go to Admin > Configuration > Online Portal

2. Make a note of the API domain key for the chamber

3. Share this with the IT administrator for the employer organisation

Task 2 - Share the Login URL with the employer organisation(s)

The format of the Login URL is:

https://patientbooking.co.uk/API domain Key/API Identifier/oh/#/ssologin

Please see Task 1 above for information on API domain key.

Please see Task 7 for information on API Identifier.

Task 3 - Carry out Azure setup for Single sign-on

This task is the responsibility of the IT Administrator for the employer organisation; namely, the employer of Manager's on the OH Portal.

Further documentation on this process for setting up a non-gallery application in Azure for Single sign-on is available on the following link - Single sign-On SAML protocol.

The following configuration is important and outlined below.

The 'User Identifier' (alternative) noted in the table above is an XML namespace.

Task 4 - Provide Meddbase Admin with Base64 Certificate and SAML Single sign-On Service URL

When the IT Administrator at the employer organisation has carried out their Azure setup, they will need to provide the Meddbase IT Administrator with the following information:

• Base64 Certificate
• SAML Single sign-on Service URL (Identity Provider's URL)*

*This is the Logout URL found under step 4 of the SAML-based Sign-on in Azure.

This is needed to complete the configuration of SSO for the employer in Meddbase.

Task 5 - Enable the Single sign-on Chargeable feature for the Meddbase chamber

To do this:

1. Go Admin > Configuration > Chargeable Features

2. Tick the box for Single sign-on

3. Click Yes to the pop-up notification

4. Then click Save

Task 6 - Ensure the company type set to 'Employer'

Each employer that wants to use SSO must be set up in Meddbase as a company with the type of 'Employer'. To ensure this is set:

1. Find the company record.

2. Go to Company Details.

3. In the company details be sure that the Type is set as Employer.

4. Click Save.

When the type value for the company is set to 'Employer', the Single sign-on option is visible.

Task 7 - Set Single sign-on settings for the company (i.e. the employer organisation) using Azure configuration information

Each company using Single sign-on will need their Single sign-on settings updated. This will need the login details employer's Azure information (the SAML Certificate in Base64 version noted in Task 4).

To do this:

1. Select the Single sign-on in the button bar for the employer record.

2. In the Single sign-on settings dialogue that appears, complete the field values referencing the guidance notes in the table below.

3. Click Save

The Single sign-on setting is saved.

Review date

This article was last updated on 14 October 2021 in the context of Meddbase version 1.244.0.29994