SAML provisioning

With Just-in-Time provisioning, you can use a SAML assertion to create users on the fly the first time they try to log in to Cloudinary, eliminating the need to create Cloudinary users in advance. Just-in-Time provisioning works with your SAML-compliant identity provider to pass the correct user information to Cloudinary in a SAML 2.0 assertion. You can both create and modify users this way. The Just-in-Time provisioning uses SAML to communicate, so your organization must have SAML-based single sign-on enabled.

Considerations for SAML provisioning with Cloudinary

• A new SAML user is not sent an email inviting them to set a password.
• All users' names and sources are available via the Users page of the Console Settings. 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.
• 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).
• 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.

• When a user no longer needs access to Cloudinary you should remove them from the application access list in the IdP. This will ensure that they cannot log in anymore, but 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 must also delete the user from Cloudinary via the Cloudinary Console in order to free the user license.

  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.

Enabling SAML login entails the following two procedures:

1. Add Cloudinary as an application to your IdP
2. Configure SAML provisioning in Cloudinary

Add Cloudinary as an application to your IdP

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

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).
   
   
   
   
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).
   
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/consume as the Audience URI.
   3. Select EmailAddress as the Name ID format.
      
      

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:
   
   

5. Optionally add Feedback and click Finish when done.

Configure SAML provisioning in Cloudinary

In order to configure your Cloudinary account to use the SAML application you have set up, 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 (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 Users page and configure the SAML login fields as follows:

   • To set a URL: Select URL as the Metadata retrieval method and add the URL to the SAML metadata URL box.
   • To use metadata: Select Inline as the Metadata retrieval method and then copy/paste the metadata XML into the SAML metadata field.

2. Decide whether to Enforce SAML login by selecting Enabled. Make sure to first test your new SAML application before changing this setting.

3. Make sure Two-factor authentication (2FA) is Disabled (configure your two-factor authentication through your IdP if required).

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

Appendix - 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.