Authentication - SAML

Note

Enabling and configuring a new authentication mode will NOT disable any existing authentication modes you may have configured or that may have been provided out of the box.

Overview

This section describes how to set up and configure CAST Imaging to allow authentication using your on premises SAML authentication system.

Requirements

Configuring CAST Imaging to use SAML Single Sign-on requires that you have already set up and configured access via HTTPS.

Step 1 - Obtain metadata

Ensure you are working in the aip-realm realm
Click the Realm settings option on the left
Then click SAML 2.0 Identity Provider Metadata in the General tab:

The metadata will be opened in a new tab in your browser - save the contents as a file called metadata.xml.
Send this file your organization’s IT administrator, in order that they can register CAST Imaging in the SAML IDP server. Once this step is complete, the IT administrator will provide you with an IDP metadata URL which is required for the next step.

Step 2 - Configure SAML settings

To configure SAML now that you have the IDP metadata URL:

Ensure you are working in the aip-realm realm
Click the Identity providers option on the left
Then click SAML v2.0:

Choose an Alias if you want to customize the provider settings
Enter the IDP metadata URL into the SAML entity descriptor field.
Click Add:

If the IDP metadata URL is correct, all settings will be automatically populated

Step 3 - Add custom mappers

Mappers are required to match the attributes from the SAML response with the mandatory user attributes in CAST Imaging, i.e. firstName, lastName, email, so that this information will be automatically populated when a user logs in.

Open the IDP metadata URL in a browser - the XML content will be displayed.
Search for the mandatory user attribute name for example email will look similar to this:

<auth:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" Optional="true"
				xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
				<auth:DisplayName>E-Mail Address</auth:DisplayName>
				<auth:Description>The e-mail address of the user</auth:Description>
</auth:ClaimType>

Copy the ClaimType Uri value (in the example above this is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)
Now ensure you are working in the aip-realm realm
Click the Identity providers option on the left
then click Mappers in your SAML configuration:
then click Add mapper:

Fill in the fields as follows:

Name: email (or to match the attribute you are mapping, e.g firstName / lastName)
Sync mode override: Inherit (default)
Mapper type: Attribute Importer
Attribute Name: paste in the ClaimType Uri found previously
Name Format: ATTRIBUTE_FORMAT_BASIC (default)
User Attribute Name: email (or to match the attribute you are mapping, e.g firstName / lastName)

Click Save and repeat the same process for the firstName / lastName attributes.

Now after a login, the mandatory fields will be imported from the SAML response.

Step 4 - Define group membership

If you need to grant CAST Imaging permissions to IDP groups (this is highly recommended) rather than, or as well as, individual IDP users, you will need to configure a mapper specifically to synchronize your IDP groups and make them available in CAST Imaging. To do so, add a mapper:

ensure you are working in the aip-realm realm
click the Identity providers option on the left
then click Mappers in your SAML configuration
then click Add mapper
then click By configuration
select the Group Membership Mapper Type and give it a descriptive name, e.g.: “group-mapper”.
in the Token Claim Name dialog, enter the attribute name in SAML which defines the group membership for your IDP users, for example this may be:
- groups
- memberOf
- roles
- etc.
Set Full group path: Toggle ON to include full path (e.g., “/parent/child”) or OFF for just group name
Add to ID token: Usually ON
Add to access token: Usually ON

When complete, click the Save button. You can check whether the groups have been successfully retrieved using the following interface:

Step 5 - Assign admin permissions to at least one SAML user

By default, SAML users/groups will not have any permissions assigned to them, so although users can login to CAST Imaging, they will not be able to make any changes. Therefore at least one user (or group) will need to be granted the ADMIN profile. CAST recommends using the local authentication mechanism to do so. This mechanism will still be active and therefore you can log in to CAST Imaging using the default admin / admin credentials and assign the ADMIN profile to a SAML user (or group) using the User Permissions option.

Finally test that the SAML user can successfully log in to CAST Imaging using their company email address and that they have permission to access the administration settings in CAST Imaging:

Step 6 - Assign permissions to other SAML users/groups

All further permission configuration should always be actioned in CAST Imaging itself, using the User Permissions option.

Ensure that you can login to CAST Imaging using SAML:

Step 8 - Disable all existing authentication methods

CAST highly recommends that you now disable all existing authentication methods to prevent users accessing CAST Imaging via a “back door” log in. In most cases this will involve disabling or deleting the Local Authentication users/groups provided out-of-the-box and any that you have created yourself.

To do so:

temporarily disable the SAML authentication mechanism (this is necessary otherwise “local” users/groups will not be visible)

disable or delete the local users/groups to prevent them being used:

finally re-enable the SAML authentication mechanism.

Troubleshooting

If you do not see the option to login to CAST Imaging with the SAML identity provider, you will need to change the theme as follows:

Ensure you are working in the aip-realm realm
Click the Realm settings option on the left
Then click Themes
Choose keycloak for the Login theme: