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 5 - Assign admin permissions to at least one SAML user

By default, SAML users 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 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 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

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 - Define group membership (optional)

In order for group configuration to function, you must ensure that your IT team has configured IDP to send groups in SAML assertions.
Group import is not supported: in other words, every group that you would like to apply permissions to in CAST Imaging must be created within Keycloak: a "mapper" then synchronizes the group in Keycloak with the group on the IDP side.

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 mappers specifically to synchronize your IDP groups and make them available in CAST Imaging.

Identify the Group Attribute name:

First ensure that you identify the Group Attribute name:

Open your browser DevTools (F12) - recommended use of Google Chrome or Microsoft Edge
Go to the Network tab
Ensure the Preserve log option is ticked
Logout from Keycloak completely
Login to Keycloak again using your SAML login
Using DevTools, look for POST requests to the /auth/realms/{realm}/broker/saml/ endpoint
Click the request, then click the Payload tab to the right

Find the SAMLResponse field (large base64 string)
Decode the base64, for example using https://www.samltool.com/decode.php , or:

echo "PASTE_BASE64_HERE" | base64 -d | xmllint --format -

In the decoded SAMLResponse, find the Group Attribute name. In the example below, the name is http://schemas.microsoft.com/ws/2008/06/identity/claims/groups:

<AttributeStatement>
    <Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
        <AttributeValue>Developers</AttributeValue>
        <AttributeValue>AIP-Admins</AttributeValue>
        <AttributeValue>Domain Users</AttributeValue>
    </Attribute>
</AttributeStatement>

Common variations to this may include:
- http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
- http://schemas.xmlsoap.org/claims/Group
- groups
- memberOf

Create groups in Keycloak

Every group that you would like to apply permissions to in CAST Imaging must be created within Keycloak: a “mapper” then synchronizes the group in Keycloak with the group on the IDP side. To create the group (or groups) in Keycloak:

Login to Keycloak with the default “admin” account
Ensure you are working in the aip-realm realm
Navigate to Groups (left menu)
Click Create group and add the group(s) you require:

Add a group mapper

For each group that you created previously, you will need to configure a mapper specifically to synchronize the IDP group with the Keycloak group. To do so click the Mappers tab in your SAML User Federation setting and click Add mapper:

Then configure the mapper as follows:

Name: mygroup-mapper (or any descriptive name)
Sync mode override: Force (syncs the group on every login (recommended))
Mapper type: Advanced Attribute to Group
Click the Add Attributes button and configure:
- Key: Enter the exact attribute name from your SAML response, e.g.: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
- Value: Enter a regular expression pattern to match the Keycloak group name, for example (?i).*developers.* - this matches any group name from the SAML response containing the word “developers”. Other value patterns
  - ^(Developers|AIP-Admins)$ - Only these specific groups
  - ^CAST-.* - Groups starting with “CAST-”
  - ^(?!Test-).*$ - Exclude groups starting with “Test-”
Regex Attribute Values: On
Group: select the group created previously which is the target for the mapper
Finally click Save

Test group membership

To test whether your group configuration is working:

Login to CAST Imaging using a SAML IDP login to force a synchronization
In Keycloak ensure you are working in the aip-realm realm
Navigate to Groups (left menu)
Select the group and then click the Members tab
Check that the user you logged in with is visible in the list:

Step 9 - 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: