Introduction

Overview

The robust and versatile mPass Single Sign-On (SSO) solution streamlines and secures the authentication and authorization processes for modern applications and services. Serving as a single sign-on (SSO) solution, mPass SSO enables organizations to enable strong authentication via MFA, manage user identities, define access policies, and protect sensitive resources efficiently. 

Purpose

A product guide document serves as a comprehensive reference manual designed to assist users in understanding, utilizing, and troubleshooting a particular product effectively. Its primary purpose is to provide users with clear and concise instructions, information, and guidance related to the product's features, functionalities, installation, maintenance, and support.

Getting Started

Dependencies

1. Active Directory: To authenticate, read, and write (if required) user information to the directory server.
2. mPass Authentication Server: To read user MFA options and validate OTP or send push authentication notification.
3. SQL Database: To store mPass SSO configuration.
4. Reverse Proxy: Acts as a layer of defense from bad actors.

Hardware and Software Requirements

 Other Requirements

1. Credentials & Technical Information: Domain Service Account with administrative privileges to install the mPass application on the Windows server and for authentication between mPass authentication nodes and DB servers
2. Network Access Requirements (Firewall Rules):
1. Environment: Primary DC
2. Source: mPass SSO Server
3. Destination: Enterprise Domain Controller AD and SQL Server
4. Protocol:
1. LDAPs
2. TCP/IP
5. Ports:
1. 389/636
2. 1433
6. Purpose:
1. To validate credentials of users during mPass user portal authentication requests
2. To read and write data to the DB server
3. Security Requirements: Trusted SSL Certificate for the mPass SSO host

Product Features

1. Single-Sign On and Single-Sign Out for browser-based applications
2. Authentication and Authorization via SAML 2.0, OAuth 2.0, and OIDC
3. Support for WebAuthn W3C Standard
4. Passwordless Authentication via WebAuthn Standard
5. Identity Brokering
6. User Self-Reset AD Password via MFA 
7. Multi-Factor Authentication
8. Arabic language support for user authentication pages
9. Organization branding support: customizable user-facing pages 
10. Controlled login flows
11. Security defenses

System Functions

User directory integration

mPass SSO includes an LDAP/AD provider. You can federate multiple different LDAP servers into one mPass SSO realm and map LDAP user attributes into the mPass SSO common user model.

By default, mPass SSO maps the username, email, first name, and last name of the user account, but you can also configure additional mappings. mPass SSO’s LDAP/AD provider supports password validation using LDAP/AD protocols and storage, edit, and synchronization modes.

Integration procedure

1. Click User Federation from the left menu.
   
2. Click Add New Provider and select LDAP.
   
3. A new form will be displayed to the user. Following are the various parameters and their descriptions arranged in various sections.
1. Add LDAP providers
2. General Options
1. UI display name: Display name of provider when linked in the Admin UI.
2. Vendor: LDAP vendor (provider).
3. Connection and authentication settings
1. Connection URL: Connection URL to your LDAP server.
2. Enable StartTLS: Encrypts the connection to LDAP using STARTTLS, which will disable connection pooling.
3. Use Truststore SPI: Specifies whether the LDAP connection will use the Truststore SPI with the truststore configured in standalone.xml/domain.sml. 'Always' means that it will always use it. 'Never' means that it will not use it. 'Only for LDAPs' means that it will use it if your connection URL uses LDAPs. Note that even if standalone.xml/domain.xml is not configured, the default Java certificates or certificates specified by the 'javax.net.ssl.trustStore' property will be used.
4. Connection pooling: Determines if MPass SSO should use connection pooling for accessing the LDAP server.
5. Connection timeout: LDAP connection timeout in milliseconds.
6. Bind type: type of the authentication method used during the LDAP bind operation. It is used in most of the requests sent to the LDAP server. Currently only 'none' (anonymous LDAP authentication) or'simple' (bind credential + bind password authentication) mechanisms are available.
7. Bind DN: DN of the LDAP admin, which will be used by MPass SSO to access the LDAP server.
8. Bind credentials: password of LDAP admin. This field is able to obtain its value from vault; use ${vault.ID} format.
4. LDAP searching and updating.
1. Edit mode: READ_ONLY is a read-only LDAP store. WRITABLE means data will be synced back to LDAP on demand. UNSYNCED means user data will be imported but not synced back to LDAP.
2. Users DN: Full DN of LDAP tree where your users are. This DN is the parent of LDAP users. It could be, for example, 'ou=users,dc=example,dc=com' assuming that your typical user will have DN like 'uid='john',ou=users,dc=example,dc=com'.
3. Username LDAP attribute: Name of the LDAP attribute, which is mapped as MPass SSO username. For many LDAP server vendors, it can be 'uid'. For Active Directory, it can be'sAMAccountName' or 'cn'. The attribute should be filled for all LDAP user records you want to import from LDAP to MPass SSO.
4. RDN LDAP attribute: Name of the LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it's the same as the Username LDAP attribute; however, it is not required. For example, for Active Directory, it is common to use 'cn' as an RDN attribute when the username attribute might be'sAMAccountName'.
5. UUID LDAP attribute: Name of the LDAP attribute, which is used as a unique object identifier (UUID) for objects in LDAP. For many LDAP server vendors, it is 'entryUUID'; however, some are different. For example, for Active Directory, it should be 'objectGUID'. If your LDAP server does not support the notion of UUID, you can use any other attribute that is supposed to be unique among LDAP users in the tree. For example, 'uid' or 'entryDN'.
6. User object classes: All values of the LDAP objectClass attribute for users in LDAP, divided by commas. For example: 'inetOrgPerson, organizationalPerson'. Newly created MPass SSO users will be written to LDAP with all those object classes, and existing LDAP user records are found just if they contain all those object classes.
7. User LDAP filter: Additional LDAP filter for filtering searched users. Leave this empty if you don't need an additional filter. Make sure that it starts with '(' and ends with ')'.
8. Search scope: For one level, the search applies only for users in the DNs specified by user DNs. For subtree, the search applies to the whole subtree. See LDAP documentation for more details.
9. Read timeout: LDAP read timeout in milliseconds. This timeout applies for LDAP read operations.
10. Pagination: Whether the LDAP server supports pagination.
5. Synchronization setting.
1. Import users: If true, LDAP users will be imported into the MPass SSO DB and synced by the configured sync policies.
2. Sync Registrations: Should newly created users be created within the LDAP store? Priority effects which provider is chosen to sync the new user. This setting is effectively applied only with WRITABLE edit mode.
3. Batch size: Count of LDAP users to be imported from LDAP to MPass SSO within a single transaction.
4. Periodic full sync: Whether periodic full synchronization of LDAP users to MPass SSO should be enabled or not.
5. Periodic changed users sync: Whether periodic synchronization of changed or newly created LDAP users to MPass SSO should be enabled or not.

After entering the required parameters in the form, please click the save button to define the LDAP backend.

Defining mPass Integration Configuration

1. Administrators need to define mPass => integration configuration to retrieve user information and invoke various MFA functions inside mPass Authentication Server.
2. Administrators should navigate to the respective realm settings from the left menu options and click the mpass tab to view the settings required for integration.

 Following are the required configurations for integration:

1. mPass Service URL: mPass AS service URL to send requests.
2. mPass Client key: API key for authentication.
3. mPass Private Key: Private Key for Authenticity of Data Transfer

Defining roles and groups

Roles and groups have a similar purpose, which is to give users access and permissions to use applications. Groups are a collection of users to which you apply roles and attributes. Roles define specific application permissions and access control.

A role typically applies to one type of user. For example, an organization may include admin, user, manager, and employee roles. An application can assign access and permissions to a role and then assign multiple users to that role so the users have the same access and permissions. For example, the Admin Console has roles that give permission to users to access different parts of the Admin Console.

There is a global namespace for roles, and each client also has its own dedicated namespace where roles can be defined.

Creating a realm role

Realm-level roles are a namespace for defining your roles. 

To view the list of already defined roles, do the following:

1. Click Realm Roles from the left menu, as shown below.
   
2. Click the Create role button as shown below.
   
   
3. The following form will be displayed.
   
4. Enter the required details and click the save button. Once the role is created, the following screen should be displayed.
   

About Client Roles

Client roles are namespaces dedicated to clients. Each client gets its own namespace. Client roles are managed under the Roles tab for each client. You interact with this UI the same way you do for realm-level roles.

To define and manage roles specific to a client. Navigate to the Clients menu item from the left menu and click the required client and click the Roles tab.

Following is a sample of the same.

Creating and managing user groups

Groups in mPass SSO manage a common set of attributes and role mappings for each user. Users can be members of any number of groups and inherit the attributes and role mappings assigned to each group.

To manage groups, click Groups from the left menu, as shown below.

 The following screen should be displayed to the user.
 

Creating new group

To create a new group, do the following:

1. Click the Create group button to define a new group. A pop-up window should be displayed as below.
   
2. Enter the required group name and click Create. The following screen should be displayed once created successfully.
   
3. Click the group name link to view the details of the group. The administrator should be able to view the following screen.
   
   
4. Now, the administrator can define a new child group, add new members (users) / add attributes specific to the group, and also add roles to the group.

SSO Clients Management

Clients are entities that can request authentication of a user. Clients come in two forms. The first type of client is an application that wants to participate in single-sign-on. These clients just want Keycloak to provide security for them. The other type of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user. 

 mPass SSO supports two types of authentications and authorization protocols for clients.

1. OpenID connect
   
2. SAML protocol.
   

 This section discusses various aspects around configuring clients and various ways to do it.

Viewing defined clients

To view existing clients, click Clients.
 

The following list of existing clients should be displayed as follows:
 

Defining a new OpenID Connect client

To create a new client, do the following:

1. Click the Create client button. The following form should be displayed to the user.
   
2. Fill in the required fields and click Next. The following form should be displayed to the administrator.
   
3. Select the type of required authentication flows and click Next. The following form should be displayed to the administrator.
   
4. Now, enter the required URLs for the relying party and click Save.
5. Now, the client details form should be displayed to the administrator as shown below.
6. Administrators can further define the required options for the client.
   

Authentication workflows

An authentication flow is a container of authentications, screens, and actions during log-in, registration, and other mPass SSO authentication workflows.

To view the authentication workflows, click the authentication item from the left menu as shown below.
 

The existing authentication workflows should be displayed as follows:
 

Testing the Integration with MFA

Following is a service provider (SP) initiated SSO for a demo application.

Access the SP Application login page.

Below is a sample of a service provider login page.
 

You should be redirected to the login page of the mPass SSO as below.

Provide Domain User Credentials

The user should enter his/her domain credentials in the form displayed below.

MFA verification

The user is displayed the MFA login page as follows (it can be different based on the policy and user MFA options of the user).

 The user can select any MFA of his/her choice or directly enter OTP from his/her mobile authenticator app. Except Push Auth, others require One Time Password (OTP).

 If the user clicks Push Auth, the user receives notification on his registered device, and the screen will display the time left to accept the notification.

Conclusion

In conclusion, mPass SSO offers a comprehensive solution for enterprise SSO and MFA, catering to a diverse range of users with its authentication workflows and integration and user management capabilities. Its user-friendly interface, coupled with robust functionality, ensures seamless integration into various workflows. Whether you're a seasoned professional or a novice, mPass SSO empowers you to achieve SSO and MFA effectively. With ongoing updates and dedicated support, it stands as a reliable choice in the realm of information security. Choose mPass SSO for a transformative experience that elevates your productivity and enhances your overall experience.