Authentication and Authorization

Follow

Countly provides Okta, LDAP, and Amazon Cognito features for authentication and authorization purposes as add-ons to Countly Enterprise. Under the LDAP category, you can use the Microsoft Azure directory or Active directory. 

To deploy them, contact your Account Manager.

 

Group synchronizing

The group name in Countly must be the same as the group names in the respective identity providers.This applies to all the authentication features listed here.

Okta

Availability

This feature is available as a paid add-on for Countly Enterprise.

The Okta feature allows Countly to bypass its regular authentication procedures and use the Okta user credentials of the organization instead. The Okta integration feature is available in Countly Enterprise v20.04 and above.

What is Okta?

Okta Identity Cloud provides secure identity management with Single Sign-On, Multi-factor Authentication. Okta's Universal Directory allows you to store unlimited users and attributes from applications and sources like AD or HR systems. 

Getting Started

Enabling Okta in Countly

Setup help

If you cannot see the Okta integration option on your Countly account, it is possible that it is not included in your package. Please contact your Account Manager. If it is included in your package but you are unable to see the option, please reach out to our Support Team, who will help you set it up.

First, enable the Okta feature by going to Management > Feature Management and click on the enable toggle button for Okta. 

Credentials

The organization’s user needs to use the same Countly login credentials as their organization’s Okta authentication account.

Steps in your Okta Developer Console

Important

These steps have been taken from Okta’s documentation. As they may update their product and documentation, please visit the Okta App Registration page for complete details.

You can either use an existing OpenID Connect app or create one.

  1. In the Okta dev console and then Create New Application.

Authentication-and-Authorization-V4-Google-Docs.png

 

  1. Fill the Application Settings fieldslike app name and Countly domain for your organization redirect URLs (e.g., https://countly.yourdomain.com/okta/login-callback forlogin and https://countly.yourdomain.com for logout).

Authentication-and-Authorization-V4-Google-Docs-2.png

And that is all! Now you can continue the setup on Countly and easily finalize the Okta integration.

Installing Okta in Countly

Create and enable a config.js file from sample.config.js:

Countly-hosted installation

If your server is Countly-hosted, please contact Support and provide us with the information listed below.

<module.exports = {




    orgUrl: 'https://dev-623170.okta.com', 




    clientId: '0oa16eh84vg4cHHSb4x7',




    clientSecret: 'wgyItX95EjtusUoccVhtLY2t8OvvicrVt5CHHE6v',




    apiToken: '00mmBkLFJhOiGcOsLaf--DuezUGdo_0j8abT4OO2yx',




    globalAdminGroup: 'countly-global-admin',




    baseUrl: 'https://user.count.ly',




};>

orgUrl: can be found in the top right section of the Okta dashboard

Authentication-and-Authorization-V4-Google-Docs-3.png

clientId and clientSecret fields: listed in the Okta dashboard, under the Applications tab.

Authentication-and-Authorization-V4-Google-Docs-4.png

apiToken: create API token on Okta

Authentication-and-Authorization-V4-Google-Docs-6.png

globalAdminGroup: group name, which will be the global admin of Countly and which needs these group permissions to access the user management and create groups inside Countly.

baseUrl: Countly domain for your organization.

Using Okta in Countly

  1. Go to Management > User Management.
  2. Choose a user who is a member of the group which has been set up as a Global Admin Group and who can manage the Users section and create Groups. The group name of Okta and the group name of Countly should be the same.

Authentication-and-Authorization-V4-Google-Docs-7.png

   3. The Okta feature does not have user-level permissions; instead, it has group-level permissions. The members of the Okta groups should match those of the Countly groups for the members of the Okta group to access the Countly. Permissions will depend on the group permission setup inside Countly to manage the Groups or Users sections. Assign users to the groups in Okta in order to match between Countly groups and Okta groups.

Authentication-and-Authorization-V4-Google-Docs-8.png

 

LDAP and Active Directory (Lightweight Directory Access Protocol)

Availability

This feature is available as a paid add-on for Countly Enterprise.

 

This feature adds integration of Microsoft Active Directory (AD) or Azure AD to your Countly Enterprise instance. Regular user management of Countly is bypassed when enabled, and users are authenticated via their AD credentials.

 

What are LDAP and Active Directory?

LDAP (Lightweight Directory Access Protocol) is a software protocol that is used to enable anyone to locate data about organizations, individuals, and other resources, such as files and devices in a network.

Active Directory (AD) consists of a database and a set of services users use to connect with the network resources they need to get their work done. Active Directory follows the LDAP protocols.

Getting Started

To enable the feature, go to Management > Feature Management and enable the toggle button for Active Directory.

When Active Directory is enabled, Countly will bypass its regular authentication and it will use the Active Directory (AD) user credentials of the organization for authentication.

The Countly user of the organization needs to use the same credentials they login to their organization’s Active Directory server.

 

Active Directories Available

The Active Directory feature currently supports:

  1. Azure Active Directory 
  2. Microsoft Active Directory

Azure Active Directory

Azure Active Directory (Azure AD) is Microsoft's cloud-based identity and access management service.

Setting up Azure AD

  1. Create an app from App Registrations or use the existing app.

Authentication-and-Authorization-V4-Google-Docs-9.png

     2. Add a web platform and add the redirect URL /azure-ad-callback

Authentication-and-Authorization-V4-Google-Docs-10.png

Authentication-and-Authorization-V4-Google-Docs-12.png

     3. Enable the feature

countly feature enable active_directory

 

     4. Go inside the features directory in Countly in/features/active_directory and copy config.azure.sample.jsconfig.js and use your app ID and secret token. Then, select a group that the members of which should be global admin of Countly.

Countly-hosted installation
If your server is Countly-hosted, please contact Support and provide us with the information listed below.


const config = {
clientId: '8db7e011-a15f-4454-9472-2f475550c7a7',
clientSecret: 'c33wTBoBv@_1jPm.e1ENTLhpoB]IE@iC',
globalAdminGroup: 'countly-global-admins'
};

 

Using Azure AD

  1.  The first login should be done by an app administrator to allow the app.
  2. Use a user who is a member of the group which is set up as a global admin group inside the configuration as someone who can access the Manage Users section to create the groups. The group name of the Azure Active Directory and the group name of Countly should be the same in order to match.
  3. The AD feature does not have user-level permissions, but group-level permissions. Active Directory groups should match with any Countly group for the member of the AD group to access Countly and permissions will depend on the group permission setup inside User Management > Groups section.

Authentication-and-Authorization-V4-Google-Docs-13.png

 

Microsoft On-Prem Active Directory

Microsoft Active Directory is a collection of services that helps manage users and devices on a network.

Setting Up Microsoft AD

  1. You need to have a running Active Directory with an LDAP v3 server. 
  2. Go inside the features directory in Countly, in /features/active_directory and copy config.ldap.sample.js config.js and use your app ID and secret token. Then, select a group whose members should be global admins of Countly. 

If your server is Countly-hosted, please contact Support and provide us with the information listed below.

Authentication-and-Authorization-V4-Google-Docs-14.png

  1. Enable the feature 
countly feature enable active_directory

 

Using Microsoft AD [Default Countly Groups]:

  1. Use a user who is a member of the group which is set up as a global admin group inside config who can access the manage users section to create the groups. The group name of Azure Active Directory and the group name of Countly should be the same in order to match.
  2. AD feature does not have user-level permission instead it is group-level permissions. Active Directory groups should match with any countly group for the member of the AD group to access Countly and permissions will depend on the group permission setup inside the countly manage users/groups section.

Authentication-and-Authorization-V4-Google-Docs-15.png

Using Microsoft AD (Legacy Role Based Authentication ) 

Deprecated

This is not applicable for new versions of Countly.

 

Active Directory groups (Groups are Active Directory objects that can contain users, contacts, computers, and other groups) should contain the user to be authorized, which should match the possible roles that will be configured or generated in Countly as described below.

One direct AD group will be mapped to the Global Admin user role of Countly. This AD group should be configured in the AD feature config file using the command below:

globalAdminGroup: 'ad-global-admin'

For each application on Countly there will be three direct AD groups with the following name structure:

AppAnalytics-APPIDENTIFIER-ROLE

Authentication-and-Authorization-V4-Google-Docs-17.png

The possible roles can be any of the following:

  1. User, with Countly User level permissions for the app (no write access and only read access).
  2. Admin, with Countly Admin-level permissions for the app (admins of Countly can only view and administer their own applications).
  3. Marketing, new Countly user level with permissions to create a funnel, view Messaging and Attribution sections and can create new Attribution and push notifications campaigns, and all other rights Countly users have been assigned.
  4. The custom role can be implemented based on customer requirements.

The AD Group can be set up on an app basis, which is defined on the Countly platform.

Authentication-and-Authorization-V4-Google-Docs-18.png

Amazon Cognito

Availability

This feature is available as a paid add-on for Countly Enterprise.

 

What is Amazon Cognito?

Amazon Cognito can add user sign-up and sign-in features and control access to your web and mobile applications. Amazon Cognito provides functionalities that scale to millions of users, and offers advanced security features to protect your customers and business. Amazon Cognito also supports various compliance regulations.

 

Getting Started with Amazon Cognito

Step 1: Configuration file changes

After you upload and extract the AWS Cognito feature to the feature directory in all Countly servers, you need to copy config.sample.js into config.js within the Cognito directory.

Afterwards, modify the following values inside the config.js file. All the values are of string type.

  • baseUrl, the URL that you access Countly from
  • globalAdminGroup, global admin group id for Countly
  • encryptionKey,random encryption key, will be used to encrypt the redirection URL payload 

Step 2: Enable AWS Cognito feature

In order to enable the feature go to Management > Feature Management and click on the enable switch for AWS Cognito feature. Then apply your changes. 

If your deployment includes multiple Countly servers remember to turn on “Sync feature states” from Management > Settings > API or manually enable the feature from the command line on each server. Also, note that configuration in Step 1 needs to be done for all instances regardless of enabling “Sync feature states” configuration.

When the AWS Cognito feature is enabled, Countly will bypass its regular authentication and user management, and authentication can only be done via the new API endpoint the AWS Cognito feature exposes.

Step 3: Using the new login path

Once you enable the AWS Cognito feature and make the configuration changes, you are ready to use the new login path /cognito-login.

This new path accepts the following headers via a GET request.

  • sub, will be used as an internal Countly user identifier (required).
  • email, will be used as user email (required).
  • custom-role, needs to contain group id that the user should belong to (required).
  • name, full name of the user (optional).
  • username, the user name of the user, if not present email will be used instead (optional).

In the success case (HTTP 200), this new path returns a URL parameter inside a JSON object. You need to redirect the user to the given URL value in order to log her into the dashboard. 

In order to get a successful response, you need to send a valid custom-role header value to this path (either the global admin group id you configured in Step 1 or a group id for a group you created via Management > Users) together with the other required headers.

In the error case, this new path will return an HTTP 400 or 422 error code.



Looking for help?