Skip to main content
You are viewing the documentation for Interana version 2. For documentation on the most recent version of Interana, go to


Scuba Docs

How to set up other forms of authentication


This document explains authentication and the different methods that can be used with Interana, and how to set them up. This document covers the following topics:

What you should know about digital authentication

Interana authentication

What you should know about digital authentication

Digital authentication is used when accessing a non-public application to ensure privacy and security. First you must authenticate, to show proof that you are who you say you are. The most common authentication method is with a username and password, also known as password auth. Password auth is the Interana default authentication method.

In some cases, an application allows you to authenticate once, then generates a token for subsequent interactions using your stored token for authentication. If you forget your login credentials, such as a password, the application may prompt you to answer a previously established security question. A second method of authentication (two factor authentication, or 2FA) may also be required, such as entering a code sent to a mobile phone number.

What is Single Sign On (SSO)?

Single sign-on (SSO) is a session and user authentication service that allows users to have one set of login credentials (e.g., name and password) that accesses multiple applications. Many applications don't want to worry about storing user credentials, dealing with flows for registration and password reset, and so on. Likewise, users don't want to remember separate passwords for every application, and businesses want a single point of control for their employees.

SSO provides a solution to these problems. Centralized identity providers use a set of protocols that delegate authentication for many applications. A special type of secret handshake is used to ensure applications know the identity provider can be trusted to authenticate its users?

In a web SSO service, an agent module on the application server retrieves the authentication credentials for a user from the dedicated SSO policy server. The SSO service then authenticates the user against a user repository, such as a lightweight directory access protocol (LDAP) directory.

Integrating an application with an identity provider

To understand how to integrate an application with an identity provider, you need to know the sign-in protocol, the authentication protocol, and the token type.

Microsoft SME, David Gregory, used an excellent example in his ADFS deep dive blog post, comparing the authentication process to the process we go through when boarding an airplane:

When you go to the airport to board a flight, what is your sign-in protocol, authentication protocol, and token type?

What is the Sign-in protocol? I go to the one of those check-in kiosks, then print my boarding pass, then go through TSA line, then go to the boarding gate, and finally board the plane. It is expected that I interact with the airport in this fashion and performs these actions in sequence, otherwise, I will not get on my plane.
What is the Authentication protocol? While my boarding pass is part of this, I have to provide my ID or passport to prove who I am.
What is the Token Type? My boarding pass is my token to get on the plane.

This is a great analogy, because you use your ID or passport to authenticate yourself before you can proceed to the security line at the airport. Once you're in the security line, your boarding pass becomes the token you need to actually board the plane. Unless you are flying internationally, your ID or passport won't be checked again.

Also, since we purchased a ticket (from the airline) before arriving at the airport, we had a pre-existing relationship with that airline (in the form of my purchased ticket). Similarly, an application may pre-register with an identity provider to acquire a private credential, so they know it's safe to be exchanging information with you.

Common sign-in protocols, authentication protocols, and token types

The most common sign-in protocols include WS-Fed, OAuth and SAML, with SAML also being a token type. Other sign-in protocols include OpenID, OpenID Connect, Google Authentication, and Facebook Connect.

The most common authentication protocols include the Password Authentication Protocol (PAP), and the Challenge-Handshake Authentication Protocol (CHAP).

  • PAP initializes authentication when a user logs in with their username and password at the beginning of the connection.
  • CHAP authentication is initialized by the server that sends a random string (usually 128B long) to the client. The client uses his password and the string received from the server as parameters for a MD5 hash function. The results are then sent together, along with his username in plain text.

The most common token types include SAML (Security Assertion Markup Language) and JWT (JSON Web Token). Google Auth uses a proprietary token which does not have a published standard.

Interana authentication

If you use an authentication method other than password auth, you will need to log in to the config node of the Interana cluster and disable password auth with this command: ia settings update auth password_auth disabled

Interana supports the following methods of authentication:

Authentication method Notes
Google auth Interana delegates management to Google for authentication, which uses the OAuth2 sign-in protocol. The OAuth2 authentication protocol and token type are opaque to Interana. Google simply provides client libraries with which Interana interacts. Once a user has authenticated, Interana stores a browser cookie for the user so they don't have to go through the authentication process again.
SAML auth Interana lets you register with any identity provider that complies with the SAML sign-in protocol. This authentication protocol is opaque to Interana, and uses a SAML token. Once a user has authenticated, Interana stores a browser cookie for the user so they have to go through the authentication process again.
Token auth Interana lets a user (who has already authenticated with one of the other protocols listed in this table) generate a private token that can be used repeatedly to invoke the Interana query API. This token is stored in the Interana config DB.
Microsoft ADFS and
Azure AD auth

Active Directory Federation Services (ADFS) is a software component developed by Microsoft. It can be installed on Windows Server operating systems to provide single sign-on access to systems and applications located across networks.

Azure Active Directory (Azure AD) is Microsoft’s multi-tenant, cloud based directory and identity management service. 

Okta auth Okta provides reliable integration for SSO to web and mobile apps with a robust federation engine and flexible access policy.
OneLogin auth OneLogin is a cloud identity management platform that provides secure single sign-on. The multi-factor authentication simplifies identity and access management (IAM) for a secure enterprise environment.

Google auth

When a user navigates to Interana in a browser, Interana checks to see if the user is already logged in. For Google auth, Interana stores a cookie in the browser once a user has successfully logged in. This section explains how Google auth is implemented with Interana. For more information, see the Google document that explains OAuth2 implementation:

For step-by-step instructions that set Google as the default login, see Configure the default login as Google.

When a user navigates to Interana for the first time and Google auth is enabled (and is not logged in), Interana displays a Sign in with Google button that (when clicked) redirects to the /api/google endpoint on the API node of the Interana cluster. 

     <div id="gSignInWrapper" style="display:none">
       <hr size=1>                                                                                       
       <div class="clearfix">                                                                            
         <span id="gLabel">Or sign in with</span>                                                        
         <div id="gCustomBtn" onclick="location.href='/api/google';" >                                   
           <span id="gIcon"></span>                                                                      
           <span id="gButtonText">Google</span>                                                          

If Interana gets a login request from a previously unknown user, Interana creates a new user. Once the user login credentials are verified, Interana sets a browser cookie that contains the user_id, customer_id, and user_name, so the user doesn't need to sign in every time.

SAML auth

Interana supports the SAML login protocol. To configure SAML for you platform, verify that your identity provider supports SAML and the necessary configuration requirements. 

When working with a SAML Auth provider, you first make a connection and load the SAML configuration. The configuration can be stored locally, on the Interana cluster, or loaded remotely from a URL. Typically, the URL for the SAML provider is stored on the config node of the Interana cluster.

Once the desired IDP URL from the SAML config is loaded, Interana redirects authentication requests directly to the SAML provider. If Interana gets a login request from an unknown user, a new user is created.

The following task provides step-by-step instructions for using ADFS as the SAML provider: Configure the default login as ADFS.

Token auth

Interana supports API tokens that can be passed as part of the Authorization header. These tokens can be generated by admin users and are long-lasting.

Microsoft ADFS and Azure AD auth

You can use Microsoft ADFS or Azure AD as an authentication provider instead of the standard Interana password authentication. For more information, see the following articles:

Okta auth

You can use Okta as an authentication provider instead of the standard Interana password authentication. For more information, see the following article:

OneLogin auth

You can use OneLogin as an authentication provider instead of the standard Interana password authentication. For more information, see the following article: