Configuring SAML: Overview
Aspera on Cloud administrators can configure Aspera on Cloud to support SAML (Security Assertion Markup Language) 2.0 authentication for your users. When a user attempts to sign in to Aspera on Cloud using SAML, Aspera on Cloud redirects the user to the identity provider (IdP) sign-on URL. The user signs in to the IdP with their SAML credentials, and the IdP sends a SAML assertion to Aspera on Cloud; Aspera on Cloud then grants access to the SAML user.
Aspera on Cloud supports multiple SAML IdPs.
Process overview
- Configure your SAML Identity Provider.
- Configure SAML for Aspera on Cloud. Configure an Aspera on Cloud default SAML
workspace, including shared inbox access and permissions, if desired.
Note: Configuring SAML default workspaces is optional if you prefer to assign user access and permissions using Aspera on Cloud SAML groups.
- Apply the Aspera on Cloud-generated SAML metadata to the IdP.
- Configure SAML groups in Aspera on Cloud, using the IdP group Distinguished Name
(DN) to map an Aspera on Cloud SAML group to an IdP SAML group.
Note: Configuring mapped SAML groups is optional if you prefer to assign user access and permissions using SAML default workspaces.
- Customize the label on the SAML button that users click on the user login page.
- Grant additional access and permissions beyond those defined in default SAML workspaces or SAML groups.
IdP requirements
To use SAML with Aspera on Cloud, you must already have an identity provider (IdP) that meets the following requirements:
- Supports SAML 2.0
- Able to use an HTTP POST binding
- Generates fingerprints using the SHA-1 algorithm
- Not configured to use pseudonyms
- Can return assertions to Aspera on Cloud that include the entire contents of the signing certificate
- If prompted, set to sign the SAML response (signing the SAML assertion is optional)
Certificate or fingerprint
To configure SAML on Aspera on Cloud, you can use either the IdP certificate or the fingerprint. If you use an IdP fingerprint, it must be encrypted using the SHA-1 algorithm.
IdP metadata
The following formats are required for IdP configuration with Aspera on Cloud:
| Tag | Format |
|---|---|
| NameID | urn:oasis:names:tc:saml:1.1:nameid-format:unspecified |
| EntityID | https://api.ibmaspera.com/api/v1/oauth2/<your_org_subdomain>/saml/<saml_id>/metadata |
| Binding | urn:oasis:names:tc:saml:2.0:bindings:HTTP-POST |
| Callback URL | https://api.ibmaspera.com/api/v1/oauth2/<your_org_subdomain>/saml/<saml_id>/callback |
Once you complete SAML configuration in Aspera on Cloud, Aspera on Cloud generates XML metadata that you can copy and apply to your IdP. For more details, see "Configuring SAML metadata on the IdP" in Configuring SAML authentication: Procedures.
SAML assertion
Aspera on Cloud expects the assertion from the IdP to contain the following elements:
| Aspera on Cloud Attribute Mapping Field | Required or Optional |
|---|---|
| Required | |
| First Name | Optional |
| Last Name | Optional |
| Member Of | Required to map Aspera on Cloud SAML groups to existing groups in the IdP database |
Default SAML workspaces
In the SAML configuration interface ( Organization > Authentication > SAML ), you can configure one or more existing Aspera on Cloud workspaces as default SAML workspaces. Each SAML user gains automatic membership in each default SAML workspace you configure.
In each default SAML workspace, you can configure SAML-user access and permissions to existing shared inboxes. Each SAML user has automatic membership and access permissions in the group inboxes you designate in default SAML workspaces.
Default SAML workspaces and shared inboxes must already exist
You must create a workspace (and any shared inboxes in it) as a separate operation before you can designate a workspace as a default SAML workspace (see Creating a new workspace and Creating a new shared inbox ). Once the workspaces and shared inboxes exist, you can designate workspaces as SAML defaults, assigning shared inbox access and permissions in the same operation (see "Configuring SAML authentication" in Configuring SAML authentication: Procedures ).
SAML user access and permissions
SAML members gain access to all files and folders shared to the default workspaces, even if they were shared before the SAML member's initial login. In addition, SAML users gain access to shared inbox packages in the shared inboxes you designate, according to the permissions you configure, even if that package was sent before the SAML user first logged in.
If you add or remove default SAML workspaces, SAML users gain or lose membership in the workspaces automatically. The same applies to changes you make to shared inbox access and permissions in a default SAML workspace.
If desired, you can add further access and permissions for an individual SAML user account, but you cannot restrict permissions beyond those configured in the user's default SAML workspaces or SAML groups.
- Access and permission changes are applied only when a user logs in. Changes you make while a given SAML user is logged in to Aspera on Cloud will not affect the user until they log out and back in.
- If you update the email address for a SAML user, the user will receive AoC notifications at the new address. However, the user must continue to log in to AoC using their original email address.
SAML groups
You can create an Aspera on Cloud group, mark that group as a SAML group, then map that Aspera on Cloud SAML group to an IdP group using the group Distinguished Name (DN); be sure to enter the DN in the AoC UI exactly as configured at the IdP. Aspera on Cloud grants new SAML users membership in Aspera on Cloud SAML groups based on the IdP group membership data contained in the IdP response messages. This grant requires accurate mapping of the AoC Member of attribute mapping field (Organization > Authentication > SAML > Create new/<existing_SAML_config_name>) to the DN of the IdP group in the SAML assertion (see "SAML assertion" above).
You can restrict login to members of IdP-mapped Aspera on Cloud groups. With this restriction in place, users without membership in an IdP group mapped to an Aspera on Cloud SAML group cannot log in to Aspera on Cloud. Without that restriction in place, a SAML user who is not a member of any IdP groups can log in to Aspera on Cloud, but will not gain membership in any Aspera on Cloud SAML group. However, such a user gains membership in configured default SAML workspaces, if any exist. To configure this restriction, see "Configuring SAML Authentication" in Configuring SAML authentication: Procedures.
With one exception, you can manage Aspera on Cloud SAML groups just like any other group, including adding an Aspera on Cloud SAML group to a non-SAML group. The exception is that you cannot manually add users to or remove users from an Aspera on Cloud SAML group. Aspera on Cloud SAML group membership is granted upon login to a user who is a member of an IdP group that is mapped to a corresponding Aspera on Cloud SAML group.
You can convert a SAML group to a standard group, and vice versa. See "Configuring Aspera on Cloud SAML Groups" in Configuring SAML authentication: Procedures.
SAML users
SAML users can log in to Aspera on Cloud through membership in a configured default SAML workspace, or through their membership in an IdP group that has a corresponding mapped Aspera on Cloud SAML group, or both.
There is no need to configure SAML users in Aspera on Cloud. When a SAML user logs in to Aspera on Cloud for the first time, Aspera on Cloud automatically generates an account for that user based on the information provided in the SAML response. If the SAML response includes group membership information, Aspera on Cloud gives the SAML user membership in the corresponding Aspera on Cloud group (if it exists), which is mapped to the IdP group using the group Distinguished Name (DN). If your Aspera on Cloud SAML configuration includes default SAML workspaces, the user gains membership in these workspaces and any shared inboxes in these workspaces that you designated, according to the permissions you selected during SAML configuration.
Once a SAML user has established an Aspera on Cloud account, you can manage that user in the same ways you can manage non-SAML users.
- When you delete a SAML user from the IdP database, you should manually delete the corresponding Aspera on Cloud user account.
- If you update the email address for a SAML user, the user will receive AoC notifications at the new address. However, the user must continue to log in to AoC using their original email address.
Adding access and permissions
If desired, you can update a SAML user account to grant additional access and permissions, but you cannot restrict permissions beyond those configured in the default SAML workspaces or the user's SAML groups. For example:
- If default SAML Workspace1 includes access to SharedInboxA with Can Send and Can Receive permission, you can update an individual SAML user account to add Can Invite permission to SharedInboxA. You cannot remove Can Send or Can Receive permission, because those are configured at the default workspace level.
- If a SAML user is a member of mapped Aspera on Cloud SAML GroupA that has membership in Workspace2, you cannot remove the SAML user's membership in Workspace2 without removing the user from SAML GroupA.
- You can grant access to an existing SharedInboxB in default Workspace1 that is not included in default workspace configuration.
- You can grant access to workspaces not included in the configured SAML default workspaces.
- You can add SAML users to non-SAML groups.
Users with preexisting AoC accounts
When a SAML user logs in to Aspera on Cloud for the first time, Aspera on Cloud checks for a preexisting Aspera on Cloud account with the same email address. If an account with a matching email address already exists, Aspera on Cloud merges the preexisting account with the new SAML account, resulting in one SAML user account.
In this way, a preexisting user who logs in through SAML becomes a SAML user; the new SAML user loses access to Aspera on Cloud via the preexisting account. However, the user's preexisting access and permissions are retained, in addition to the access and permissions granted with their SAML account. If such a user is deleted from the IdP database, they lose all access to Aspera on Cloud, the same as any other Aspera on Cloud SAML user.
Login restrictions
If desired, you can restrict user login for certain domains:
- Include domains: List domains from which users can log in. For example, if you select Include domains and list abc.com and xyz.com, only users with email addresses from those two domains are allowed to log in. Users from all other domains than those listed are not allowed to log in.
- Exclude domains: List domains from which users cannot log in. For example, if you select Exclude domains and list rst.com and bgt.com, users with email addresses from those two domains are not allowed to log in. Users from all other domains than those listed are allowed to log in.
You can also restrict login to users who are members in Aspera on Cloud groups that are mapped to SAML groups. See "SAML groups" above.