All Collections
SAML-based Federation Authentication
SAML-based Federation Authentication

Ripple version 2.7.0

Alphaus Support Team avatar
Written by Alphaus Support Team
Updated over a week ago

Overview

SAML-based federation authentication is now available on Ripple and Wave, allowing you to log-in using SSO (Single Sign-On).

Compared to the conventional password authentication access, this function enables centralized management for the admins and enhances security.

Procedure

This article first explains the procedure using Auth0 as an example, but the system supports other SAML 2.0 based IdPs (ID provider) such as Okta and Google Workspace.

SP (Service Provider) here refers to Ripple and Wave. The procedure covers step-by-step instructions for the Ripple settings, following by the Wave settings (both settings are almost the same, but the values to be keyed in in the process are different).

  1. Create a SAML application with Ripple as SP with Auth0

    1.1 Select [Applications] and click [+ CREATE APPLICATIONS]

    1.2 Select [Single Page Web Applications] and click [CREATE]

    1.3 Select [Addons] and enable [SAML2 WEB APP]

    1.4 Once SAML2 WEB APP is enabled, the following page will pop up

    > Click [Settings] and key the following in [Application Callback URL] 

    https://login.alphaus.cloud/ripple/saml

    The black screen SAML settings below can remain default

    Click [ENABLE]

    1.5 Go back to [Usage] tab and download "Identity Provider Metadata"

  2. Generate IdP ID on Ripple

    2.1 Go back to Ripple and click "Preferences" > "IdP settings

    2.2 Fill out the form below and click "submit"

    Name: Please give it any name you like

    SAML Metadata: Upload the metadata downloaded in step 1.5

    2.3 Please take a note of this IdP ID later as you will need it later

  3. Set-up user on Auth0

    3.1 Return to Auth0 and select corresponding user from [Users & Roles] > [Users]

    3.2 Click [View Details] to move to the following page

    3.3 Generate code to key into the black part above based on the user_metadata sample below

    {
    "rippleIdpId": "db4e02b5-91fa-4109-9b90-648750405ce0",
    "rippleProfiles": "MSP-5aa311904d5d6:ripple/RIPPLE_ADMIN,user/USER_ADMIN,rbac/RBAC_ADMIN"
    }

    3.3.1 Take the Auth0 Idp ID you have copied in step 2.2

    And paste it into the user-metadata sample above 

    "rippleIdpId": "< PASTE HERE >",

    3.3.2 Copy the MSP ID from Ripple user setting page

    Paste the MSP ID in the user_metadata sample like below

    "rippleProfiles": "< PASTE HERE >:

    3.3.3 Set the role(s) to grant permission

    In this sample, it is set to allow the three roles highlighted with the red rectangle 

    ripple/RIPPLE_ADMIN,user/USER_ADMIN,rbac/RBAC_ADMIN"


    ​

    3.3.4 Paste the user_metadata generated based on the sample as shown below and click [SAVE]

  4. Set rules on Auth0

    4.1 Go back to IdP Auth0, select [Rules] from the left menu and click [+ CREATE RULE]

    4.2 Select [Empty Rule] (You can put whatever you like for [Name], but here, we put "Alphaus-Ripple")

    4.3 Copy this sample RULE script below 

    function (user, context, callback) {
    context.samlConfiguration.mappings = {
    'https://app.alphaus.cloud/ripple/SAML/Attributes/IDPID': 'user_metadata.rippleIdpId',
    'https://app.alphaus.cloud/ripple/SAML/Attributes/Profiles': 'user_metadata.rippleProfiles',
    'https://app.alphaus.cloud/ripple/SAML/Attributes/SessionName': 'email'
    };
    callback(null, user, context);
    }

    And paste it into the black part and click [SAVE CHANGES]

  5. Login

    5.1 Go back to the SAML2 Web App you just created for Auth0 and jump to the Login page from the Identify Provider Login URL

    5.2 The procedure is successfully completed if you see something like below

    5.3 Please login to Ripple and check the status on the upper right

  6. Settings for Wave

    6.1 Generate code based on Wave ver. user_metadata sample 


    {
    "waveIdpId": "0a771745-261a-4ff0-b923-36e9672db65b", 　　　　　　　　"waveProfiles":"reseller|UL3yxO2S|600fa583ce8a0:wave/WAVE_ADMIN,user/USER_ADMIN,rbac/RBAC_ADMIN"
    }

    6.2 Obtain the IdP ID by selecting "Settings" > "Identity Provider Settings" > "Add Identity Provider"

    And paste it into the user_metadata sample above

    "waveIdpId": "< PASTE HERE >",


    ​

    6.3 Obtain Wave ID from the Wave settings page

    And paste it to the Wave ID part of the user-metadata sample 

    "waveProfiles":"< PASTE HERE > :

    6.4 Paste this sample RULE Script into Auth0 Rules 

    function (user, context, callback) 
    {
    context.samlConfiguration.mappings = {
    'https://app.alphaus.cloud/wave/SAML/Attributes/IDPID': 'user_metadata.waveIdpId',
    'https://app.alphaus.cloud/wave/SAML/Attributes/Profiles': 'user_metadata.waveProfiles',
    'https://app.alphaus.cloud/wave/SAML/Attributes/SessionName': 'email'
    };
    callback(null, user, context);
    }


    ​

    6.5 From here, you can complete the setting in the same procedure as Ripple

    Thank you for reading through till the end!

To configure your organization’s IdP and Alphaus Ripple/Wave to trust each other
​

  1. You begin by registering Ripple/Wave with your IdP. In your organization’s IdP, you create a SAML application with Ripple/Wave as a service provider (SP) by using this URL https://login.alphaus.cloud/ripple/saml (for Ripple) and https://login.alphaus.cloud/wave/saml (for Wave) as ACS URL and entity ID.
    ​

  2. Using your organization’s IdP, you generate/download metadata XML file that can describe your IdP as an IAM identity provider in Ripple/Wave. It must include the issuer name, a creation date, an expiration date, and keys that Ripple/Wave can use to validate authentication responses (assertions) from your organization.
    ​

  3. In Ripple, you create a SAML identity provider entity by going to IdP settings page https://app.alphaus.cloud/ripple/identity-provider-setting. In Wave, you create a SAML identity provider entity by going to settings page https://app.alphaus.cloud/wave/settings. As part of this process, you upload the SAML metadata document that was produced by the IdP in your organization in step 2.
    ​

  4. In Ripple/Wave user management, you create one or more roles.
    ​

  5. In your organization’s IdP, you define assertions that map users or groups in your organization to the roles. Note that different users and groups in your organization might map to different roles. The exact steps for performing the mapping depend on what IdP you’re using. The attributes for the mappings are as follows:

For Ripple:
​

For Wave:
​

Note

  1. Only users with Admin role will be able to create/read/update/delete SAML identity provider entities.

  2. IDP ID can be obtained from the list of SAML identity provider entities.

  3. Only 5 profiles are allowed in a single assertion.

  4. A profile should be in the format of ${MSPID}:${namespace1}/${roleName1}[,${namespaceN}/${roleNameN}] for Ripple and ${waveID}:${namespace1}/${roleName1}[,${namespaceN}/${roleNameN}] for Wave. This is an example of a profile with a single role MSP-123456:ripple/RIPPLE_ADMIN and this is an example of a profile with multiple roles abcd123:wave/WaveAdmin,rbac/ReadOnly,user/ReadOnly

For Ripple:
​

For Wave:
​

Did this answer your question?