Add SSO connection in Tango portal

Tango functions as the service provider (SP) to run a SP-initiated single sign-on (SSO) in conjunction with your organization's identity provider (IdP)—such as Okta, Microsoft Azure, OneLogin, etc. SSO authenticates user identity in your organization's environment through an IdP and then passes the user's authorization credentials to log in to Tango portal. When you enable a new SSO for your Tango platform, you have the option to log in to the Tango portal with the IdP authentication.
 

OIDC vs. SAML SSO

OpenID Connect (OIDC) and Security Assertion Markup Language (SAML) are two authentication protocols that authenticate Tango portal users for SSO. They are both widely used protocols with different strengths and weaknesses. Here's a comparison of the two:
 

What do we recommend?

The ultimate choice between SAML and OIDC should be based on the specific needs of your organization, the types of applications you are integrating, and the existing infrastructure and skill set.

Tango recommends OIDC as:

• OIDC is easier to set up, simpler, lightweight, and more modern protocol.

• OIDC doesn’t require you to refresh your certificates. As with SAML, you have to update and refresh your certificate upon expiry.

Who’s this guide for?

This guide is intended for Tango account administrators with Manage Authentication rights to help configure SSO as a way of secure login to Tango portal.
 

How to add SSO to Tango portal?

Depending on your company policy and setup, you may choose to have one or more login methods. Your organization can have up to ten login methods including username/password, Google account, or multiple SSOs (including OIDCs and SAMLs). We recommend you disable any login method that your organization does not use. For example, disable username/password and google authentication if your corporate SSO is fully configured and ready to use. See Manage login methods in Tango portal for more information.

Adding OIDC or SAML SSO to your Tango portal involves the following steps:

Step 1: Gather information

You must have Manage rights for Authentication in your platform to add SSO to Tango portal. Authentication permission is turned off by default. If you don’t have the permission or you’re not a Tango admin, ask a Tango admin in your organization to give you permissions under Users > Permissions > Authentication. See Organization roles and permissions in Default user roles in Tango portal.

To gather information:

1. Sign in to the Tango portal.

2. Go to Team settings > Authentication.

3. Click Add SSO connection.

4. Select your choice of IdP: OIDC or SAML.

5. Click copy next to the Single Sign-On URL, or copy and keep the following links for later use:

   • Sandbox: https://sandbox-auth.tangocard.com/login/callback

   • Production: https://auth.tangocard.com/login/callback

6. (For SAML only) copy Tango attributes for IdP configuration.
   
   

You need these values to map the Tango and IdP applications later. The email address for your Tango user profile must match the email address on the IdP claim. We have provided Okta and Azure default names as examples below:

*For other IdPs, refer to your IdP documentation to find out their attribute names.

Step 2: Configure your IdP provider

To set up SSO for your Tango platform, you must first create an entry with your IdP provider and use Tango's configuration values copied from Tango portal.

 

Log in as an admin to your IdP provider and follow their instructions and create an entry. We have provided some examples below but we recommend you to always check with your IdP documentation for the latest.

Step 3: Configure Tango portal

Once the SSO entry has been created in your IdP, copy the required values in IdP for Tango portal configuration. After your SSO is enabled, you and your platform users can sign in to Tango using the new SSO.
 

To configure Tango portal:

1. Sign in to the Tango portal.

2. Go to Team settings > Authentication.

3. Click Add SSO connection.

4. Select OIDC or SAML and continue as follows:

   • For OIDC:

     1. Click Continue on the Single Sign-On page to go to the next.

     2. Enter a Connection display name. The connection display name will show up later on the Tango login page as a login method for users.
        
         

        Note:
        -You cannot have a duplicate names.
        -The connection display name may have up to 128 letters with no special characters.

        
        

     3. Enter a custom Client ID that you have configured in IdP. See our SSO configuration steps in IdP guide.

     4. Enter OpenID Connection ID Token Issuer URL. This field is the Tenant ID in IdP. See our SSO configuration steps in IdP guide. The URL link is automatically appended with the following extension as soon as you paste it in the Tango portal: (/.well-known/openid-configuration).

     5. Tango claim keys are automatically populated for standard OIDC. Only if your IdP does not follow the OIDC standard and you see different variables in your IdP, enter those exact variables here to continue.

     6. (Optional) Select Bypass MFA. When you bypass MFA, you won’t be challenged for an MFA when using SSO.

     7. Click Add. The connection is created, but disabled by default. You must test and enable the connection to make it available for your platform users. See how to test and enable SSO connection.

         

   • For SAML:

     1. Click Continue on the Single Sign-On page to go to the next.

     2. Enter Connection display name. The connection display name will show up later on the Tango login page as a login method for users.
        
         

        Note:
        -You cannot have a duplicate connection display name.
        -The connection display name may have up to 128 letters with no special characters.

        
        

         

     3. Enter the Entity ID and Metadata URL that you have configured in your IdP.

     4. (Optional) Click Enter details manually to enter SAML configurations such as Signing certificate, Log in URL, Log out URL, Debug Mode, etc. taken from your IdP.

     5. (Optional) Select Bypass MFA. When you bypass MFA, you won’t be challenged for an MFA when using SSO.

     6. Click Add. The connection is created, but disabled by default. You must test and enable the connection to make it available for your platform users. See how to test and enable SSO connection.

Step 4: Test the SSO connection

As a Tango portal admin, you should test your SSO connection before enabling it for other users. To test the SSO connection, change it to the testing mode. When the test is successful, enable the connection to make the SSO available for all users on the platform.

To test the SSO connection:

1. Make sure you are Signed in to the Tango portal with manage authentication permissions.

2. Go to Team settings > Authentication.

3. Find OIDC SSO or SAML SSO on the list.

4. Click ellipsis menu then select Enable testing.

   

    

5. Click Enable testing again to confirm. The label changes on the Tango portal to Testing. You are given a URL to test.
    

   

6. Click ellipsis menu then select Service Provider URL.

7. Click copy Service provider URL then click Close.

8. Paste the copied URL in an incognito browser and hit Enter. The UI indicates that the SSO is in Testing mode. You know the test is successful if you can log in to the Tango portal dashboard directly and without entering your password using the Service provider URL link.
    

To copy the testing URL anytime after, click Service provider URL from the ellipsis menu next to the SSO. Use the Service provider URL link for Service Provider (SP)-initiated logins (such as Okta) after the test is completed. It will allow your users to skip the Tango login page and directly log in to the Tango application.
 

Step 5: Enable SSO authentication

You must enable your SSO to make it available for all users in your platform. Enable the authentication after your test confirms the connection is working.
 

To enable SSO authentication:

1. Make sure you are Signed in to the Tango portal with manage authentication permissions.

2. Go to Team settings > Authentication.

3. Find OIDC SSO or SAML SSO on the list.

4. Click Enable next to the connection.

5. Click Enable for all users.
    

   

   
   The newly added SSO shows up as a login method in your Authentication and your Tango login page. At this point you and all users can sign in to Tango portal using SSO. 
    

   

    

Step 6: Sign in to Tango portal with SSO

Once the SSO authentication is enabled, you can sign in to Tango portal using the SSO.
 

To sign in with SSO:

1. Go to the Tango portal.

2. Enter your email address and select the Remember email checkbox.
   You may need to skip this step if you have logged in to Tango portal before.

3. Click Continue.

4. Select Continue with [your] SSO Connection to log in. 

5. If prompted, enter your email address and click Continue. If your IdP prompts you to sign in, enter your credentials to log in to your IdP, and you will be redirected back to Tango. Receive a text message, email, or authenticator app with your six-digit verification code. Enter your six-digit code and click Verify. For more information see Sign in to Tango portal .

How to disable SSO authentication? 

If an SSO authentication is disabled, access to the SSO method will be disabled for all users. Users must set up a different SSO method the next time they log in. You must have at least one method enabled. All SSO methods are enabled by default.
 

To disable SSO authentication on your platform:

1. Sign in to the Tango portal with manage authentication permissions.

2. Go to Team settings > Authentication.

3. Find OIDC SSO or SAML SSO on the list and click Disable.
   A message box warns you that access to this login method will be stopped for all platform users.
    

   

    

4. Click Disable for all users.
   If logged out, you cannot log back in using the disabled SSO. You must use a different method such as email and password or Google SSO, or set up a different MFA method next time you log in. Contact your Customer Support Manager (CSM) or success@tangocard.com.

How to edit SSO authentication?

You may need to correct some values, update the expired signing certificate, or update the metadata URL. The default connections on your platform cannot be edited by admins, but they can be disabled.
 

To edit the SSO connection:

1. Sign in to the Tango portal with manage authentication permissions.

2. Go to Team settings > Authentication.

3. Find OIDC SSO or SAML SSO on the list.

4. Click ellipsis menu then select Edit and make the necessary changes.

5. Click Update.
    

   

    

How to delete SSO authentication?

Admins can delete the SSO authentications apart from the default connections (google-oauth2 and username/password). The default SSOs on your platform cannot be deleted by other users.

To delete SSO authentication:

1. Sign in to the Tango portal with manage authentication permissions.

2. Go to Team settings > Authentication.

3. Find OIDC SSO or SAML SSO on the list.

4. Click ellipsis menu then select Delete and confirm.

More resources

• SSO configuration steps in Okta IdP
• SSO configuration steps in Azure IdP
• SSO configuration steps in OneLogin IdP