SAML SSO

Last updated: Oct-31-2023

SAML is an industry standard that many SSO IdPs (Identity Providers) use to provide authentication and authorization services. This feature can enable your users to log in to Cloudinary with your organization's SAML-based SSO IdP, such as Okta, Azure AD, OneLogin, etc.

SAML SSO can be used for login only, or it can be further extended to also be used for provisioning, where your SAML-compliant IdP controls both the authentication (login), and the user's creation and authorization (provisioning). This effectively lets you create Cloudinary users on the fly the first time they try to log in to Cloudinary via your IdP, eliminating the need to create them in advance.

Configure SAML SSO in Cloudinary

Note
If you also plan on implementing SAML Provisioning, you should first prepare your IdP as described in that section, before configuring Cloudinary as described in this section.

In order to configure your Cloudinary account to allow SSO for logging in, you will need to supply your application's Identity Provider Metadata, either as a URL to the file (of the form: https://<orgname>.okta.com/app/<random_string>/sso/saml/metadata), or by copy/pasting the data itself (for example in Okta, you can find the URL and metadata by clicking the Identity Provider Metadata link on the Sign On tab of your application's settings).

  1. In the Cloudinary Console Settings, access the Account Security page and configure the SAML Login fields as follows:

    • To set a URL: Select URL as the Metadata retrieval method and add the URL into the field below.
    • To use metadata: Select Inline as the Metadata retrieval method and then copy/paste the metadata XML into the field below.
  2. Decide whether to Enforce SAML login by selecting Enabled. Make sure to first test the SSO works before changing this setting. When enabled, all users must log in to Cloudinary using SAML authentication. Only the Master admin can log in directly using the Cloudinary login screen.

  3. Click the Save button at the bottom of the page.

Considerations for SAML SSO with Cloudinary

  • Only existing users can login to Cloudinary this way. If you also want to extend this functionality and also create users on the fly the first time they try to log in to Cloudinary, see the SAML Provisioning feature described below.
  • If your account has SAML (SSO) login enabled and you use the Media Library Widget or one of our Integrations, you must whitelist the domain console.cloudinary.com. If you need assistance, contact Support.
  • The two-factor authentication (2FA) user setting is ignored when using SAML Login to log in to Cloudinary, as the SSO IdP is trusted.
  • A Cloudinary account can simultaneously allow both access through SSO using SAML or by using the credentials from Cloudinary (email and password as provisioned via the Cloudinary Console or the Provisioning API). To require all users to log in through SAML, set the Enforce SAML login setting in the User Settings.
  • Even if you set Enforce SAML login to Enabled, any user created with the Master admin role will automatically get an invitation to set a Console password and will be able to log in directly to the Console, if needed.
  • When a user no longer needs access to Cloudinary, you should remove them from the application access list in the IdP to ensure that they won't be able to log in anymore. However, this user will continue to have an account in Cloudinary, which may take up one user license. If this user is not expected to use Cloudinary in the future, you should also delete the user from Cloudinary in order to free up the user license, either via the Cloudinary Console, or with custom code using the Provisioning API.

    Similarly, groups and product environments are not deleted, but the user can be de-associated with groups and product environments on an IdP update. Groups and product environment permissions and settings are managed in the Cloudinary Console Settings.

SAML provisioning

With SAML provisioning, you can create users on the fly the first time they try to log in to Cloudinary, eliminating the need to create Cloudinary users in advance. SAML provisioning works with your SAML-compliant IdP to pass the correct user information to Cloudinary. You can both create and modify users this way. The SAML provisioning feature also requires that your organization must have SAML-based single sign-on enabled.

Important
The SAML Provisioning option is currently available only for accounts with an Enterprise plan and is enabled upon request.

Enabling SAML login entails the following two procedures:

  1. Add Cloudinary as an application to your IdP.
  2. Configure your Cloudinary account to use SSO. Follow the instructions for Configuring SAML SSO in Cloudinary.

Add Cloudinary as an application to your IdP

Note
If your Cloudinary contract includes Setup Services, a Cloudinary Solutions Architect can help you deploy this feature. Please contact your Customer Success Manager to coordinate.

To add a Cloudinary-SAML application to your identity provider (IdP):

Note
The following instructions use Okta as an example for configuration, although you could use any SAML compliant identity provider (the flow may vary between IdP's).
  1. Create a new SAML 2.0 Web application (e.g., in the Okta Admin console, select Applications from the Applications menu, click Add Application and then Create New App, select Web as the Platform and SAML 2.0 as the Sign on method).

    SAML

  2. Give your app a name (e.g., Cloudinary), and then optionally select a logo and visibility options (you can download a Cloudinary logo from our brand assets page). SAML
  3. Configure SAML settings as follows:
    1. Enter https://cloudinary.com/saml/consume as the Single sign on URL for both the Recipient URL and the Destination URL.
    2. Enter https://cloudinary.com/saml as the Audience URI.
    3. Select EmailAddress as the Name ID format.

      SAML
  4. Federate Okta user profile field values to Cloudinary SAML attributes. These are fields and values that Cloudinary expects to receive for each user. Add an attribute statement for the following SAML Assertion Fields, including their corresponding values:

    SAML Assertion Field Cloudinary User Field Type Required Notes
    User.CloudinaryAccountID Provisioning Account ID String Yes Account ID's are located in the Cloudinary Console under Settings > Account > Provisioning API Access.
    User.Username (External) User ID String Yes Must be unique: used as the immutable id for creating a new user in your Cloudinary account.
    User.FirstName First name String Yes
    User.LastName Last name String No
    User.Email E-mail String Yes
    User.CloudinaryRole Role String (list) No
    Default: media_library_user
    Possible values:
    master_admin; admin; technical_admin; billing; reports; media_library_admin; media_library_user
    User.CloudinaryUserGroups User Groups String array No
    If provided, the user is automatically assigned to these groups. If the list includes groups that don't currently exist in Cloudinary, they are automatically created and the user is assigned to them.
    Note: groups are ignored for all roles except for media_library_user.
    User.CloudinarySubAccounts 1 Product environments String array No
    Default: all product environments
    The string array can contain product environment IDs and/or names
    Note: product environments are ignored for the master_admin role.

    Footnote
    1. The product environment was previously referred to as a sub-account.

    For example, in Okta:

    SAML

  5. Optionally add Feedback and click Finish when done.

Important
You also need to configure your Cloudinary account to use SSO. Follow the instructions for Configuring SAML SSO in Cloudinary.

Considerations for SAML provisioning with Cloudinary

  • A new SAML provisioned user to Cloudinary is not sent an email inviting them to set a password.
  • All users' names and sources are available via the User Management page of the Console Settings. Therefore, the Cloudinary Console can also be used for reviewing and updating auto-provisioned user accounts, except for password related fields and options.
  • If a user had an account in Cloudinary before the SAML integration and uses the same email in your IdP, the user will now log in through the IdP but will continue to use the same account in Cloudinary.
  • Folder-level permissions, collection-level permissions, etc. cannot be set directly for users. They are indirectly controlled by the user group associations.
  • Cloudinary uses the username field as a unique immutable ID for creating a new user in your Cloudinary account. If any supplied attributes change (including possibly the user email, groups and product environment associations), the user account details will be updated accordingly. This means you should use a unique value for the 'username' field (e.g., if you use the user's email as a username you won't be able to update their email address using a SAML assertion in the future).
  • With SAML Provisioning, any login request must include all mandatory fields in the assertion message, where attributes and values are case-sensitive.
  • The SAML protocol supports only provisioning. Deprovisioning should be handled with custom code using the Provisioning API. If SSO is enforced on the account, users will not be able to log in if access is removed on the identity provider.

Error handling

On a failed log-in to Cloudinary, SAML errors are returned to the user's browser in the response body of a 400 error. The response includes an Error Code and Description where possible.

Error Description
1 USER_CREATION_ERROR
2 MISSING_ACCOUNT_ID
3 INVALID_ACCOUNT_ID
4 MISSING_FIRST_NAME
5 MISSING_EMAIL
6 INVALID_EMAIL_ADDRESS
7 ROLE_LOOKUP_ERROR
8 INVALID_SUBACCOUNT_IDENTIFIER
9 LICENSE_LIMIT_EXCEEDED
10 USER_UPDATE_ERROR
11 PROVISIONING_NOT_ALLOWED
12 USER_ACCOUNT_MISMATCH
13 USER_GROUP_CREATION_ERROR
14 INVALID_NAME_ID
15 SAML_VALIDATION_FAILED
16 INVALID_SAML_RESPONSE

✔️ Feedback sent!

Rate this page: