Single Sign On (SSO): Configure

Overview

The purpose of this document is to provide a rough guideline on how to configure your Single Sign On (SSO) solution such as ADFS, OKTA, OneLogin, Tivoli, etc. for connectivity to Ripple Treasury.

 The screenshots provided in this document are from Azure Single Sign-On.

SSO Configuration

In Azure, create an entry for Single Sign-On (SSO) with SAML.

1. Download the public Base64 certificate and share with Ripple Treasury.

   1. Press “Download” on this entry and you should download a .cer file which you will need to share with Ripple Treasury Support or your solutions consultant.  This is the public key for your SAML integration and needs to be loaded on the Ripple Treasury systems before you can proceed with testing the integration.

2. Configure the Entity ID and Reply URL based your location.

   1. Both elements will have the same value.  Acceptable values for these elements will be based on the system with which you are trying to connect and are listed below.

3. Select your environment.

4. Configure the “environment” claim based the system type.

   1. Configure a custom claim for the environment you are attempting to connect to, acceptable values below.  Clients often have more than one environment they connect to, and SAML needs to be configured for each environment with which they want to connect.  The claim needs to be called environment and is case sensitive.  The values for the environment claim below are also case sensitive.

5. Configure the ClientID element and claim.

   1. Since Ripple Treasury is multi-tenant software as a service (SaaS) our client will need to pass an identifier to that we know which system to authenticate against.  This is done by creating another custom claim called clientID which is case sensitive.  Your solutions consultant or Ripple Treasury support will provide you with this identifier.  For instance, for Ripple Treasury this value would be “Ripple Treasury” in all capitals (this claim is also case sensitive.  Depending on your company’s internal identifier at Ripple Treasury, this may be a value different from your company’s name (e.g., your holding company name) and it is best to consult with Ripple Treasury.

   

6. Optionally, ensure you are passing the status of whether you are connecting with multi-factor authentication (MFA).

   1. Many of our clients are required by compliance to connect with a session that uses MFA, and Ripple Treasury is required to capture that information as proof to several governing bodies that MFA is being used.  If your company is using SWIFT payments, then this claim is mandatory.  If you are not using SWIFT payments and have no other compliance requirements around MFA there is still no harm in sending this information.  In Azure AD, the claim needs to be setup below (case sensitive).

Required Claims

For the integration to work correctly, the claim “Unique User Identifier (Name ID)” must match the username of the corresponding login define in Ripple Treasury or the value must be mapped to the user in the Ripple Treasury system. 

In the below diagram you can see that the required claim is user.userprincipalname.

If you were to click on this claim, you will be taken further to see the definition of that value and what needs to be passed.  In this case, e-mail is the value being passed for matching to the Ripple Treasury system.

Application Configuration: Mapping Logins When Ripple Treasury Users Do Not Match user.userprincipalname

If your Ripple Treasury users (operators) do not match what is being passed by user.userprincipalname then the user.userprincipalname needs to be added as per below in each operator.

Use this “Identity Token” section to configure the “user.userprincipalname” value which will be used to match Single Sign-On. This is to correspond to Ripple Treasury “Oper ID”.

“Identity Token Value” is equal to our “user.userprincipalname”

Copyright 2025 Ripple Labs Inc.