NetIQ 5.3 Advanced Authentication Developer Guide

PDF

เอกสาร

โฆษณา

Developer Guide

Advanced Authentication

Version 5.3

Legal Notices

For information about legal notices, trademarks, disclaimers, warranties, export and other use restrictions, U.S. Government rights, patent policy, and FIPS compliance, see https://www.netiq.com/company/legal/ .

About NetIQ Corporation

About this Book

1 Advanced Authentication Overview

9

1.1

About Advanced Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.2

Advanced Authentication Server Appliance Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.3

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.3.1

Basic Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3.2

Enterprise Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3.3

Enterprise Architecture with Load Balancer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.3.4

How to Configure Load Balancer for Advanced Authentication Cluster . . . . . . . . . . . . . . . 12

1.4

Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4.1

Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4.2

Authentication Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4.3

Authentication Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

5

7 2 About the API

17

2.1

Logon Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.2

Enrollment Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3 API Documentation

21

3.1

Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.2

Working With Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.2.1

About Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.2.2

Create Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.2.3

Delete Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3.3

Working With Endpoint Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.3.1

About Endpoint Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.3.2

Create Endpoint Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3.3.3

Read Information About Endpoint Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.3.4

Delete Endpoint Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

3.4

Provide Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

3.4.1

About Login Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

3.4.2

Provide Simple Authentication Using One Method In A Chain . . . . . . . . . . . . . . . . . . . . . . 31

3.4.3

Provide Chained Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3.4.4

1:N Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.4.5

Read Available Chains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.4.6

Priority of the Authentication Chains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3.4.7

Delete Logon Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3.5

Working With Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.5.1

About Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.5.2

Getting Information About User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.6

Working With User's Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.6.1

About User's Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.6.2

Read User's Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.6.3

Modifying User's Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.6.4

Delete User's Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3.7

Working With Login Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Contents

3.7.1

About Login Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3.7.2

Read Information About Login Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3.7.3

Delete Login Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3.8

Working With Enrollment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.8.1

About Enroll Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.8.2

Start Enroll Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.8.3

Providing Data Into Enroll Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

3.8.4

Delete Enroll Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

3.9

Working With User's Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

3.9.1

About User's Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

3.9.2

Get User's Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

3.9.3

Create User's Templates From Enroll Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

3.9.4

Assign User's Template To Another User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

3.9.5

Updating User's Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

3.9.6

Delete User's Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3.10

Working With Authentication Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

3.10.1

Card Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

3.10.2

Email Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

3.10.3

Emergency Password Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

3.10.4

FIDO U2F Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

3.10.5

Fingerprint Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

3.10.6

HOTP Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

3.10.7

LDAP Password Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

3.10.8

Password Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

3.10.9

RADIUS Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

3.10.10 Security Questions Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

3.10.11 Smartphone Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

3.10.12 SMS Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

3.10.13 TOTP Authentication Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

3.10.14 Voice Call Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

3.10.15 NotarisID Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

3.10.16 PKI Authentication Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

3.11

Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

3.12

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

4 Usage of Device Services

129

4.1

Card Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

4.2

FIDO U2F Plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

4.3

Fingerprint Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

4.4

PKI Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Advanced Authentication

About NetIQ Corporation

We are a global, enterprise software company, with a focus on the three persistent challenges in your environment: Change, complexity and risk—and how we can help you control them.

Our Viewpoint

Adapting to change and managing complexity and risk are nothing new

In fact, of all the challenges you face, these are perhaps the most prominent variables that deny you the control you need to securely measure, monitor, and manage your physical, virtual, and cloud computing environments.

Enabling critical business services, better and faster

We believe that providing as much control as possible to IT organizations is the only way to enable timelier and cost effective delivery of services. Persistent pressures like change and complexity will only continue to increase as organizations continue to change and the technologies needed to manage them become inherently more complex.

Our Philosophy

Selling intelligent solutions, not just software

In order to provide reliable control, we first make sure we understand the real-world scenarios in which IT organizations like yours operate—day in and day out. That's the only way we can develop practical, intelligent IT solutions that successfully yield proven, measurable results. And that's so much more rewarding than simply selling software.

Driving your success is our passion

We place your success at the heart of how we do business. From product inception to deployment, we understand that you need IT solutions that work well and integrate seamlessly with your existing investments; you need ongoing support and training post-deployment; and you need someone that is truly easy to work with—for a change. Ultimately, when you succeed, we all succeed.

Our Solutions

Identity & Access Governance

Access Management

Security Management

Systems & Application Management

Workload Management

Service Management

About NetIQ Corporation

Contacting Sales Support

For questions about products, pricing, and capabilities, contact your local partner. If you cannot contact your partner, contact our Sales Support team.

Worldwide:

United States and Canada:

Email:

Web Site:

www.netiq.com/about_netiq/officelocations.asp

1-888-323-6768 [email protected]

www.netiq.com

Contacting Technical Support

For specific product issues, contact our Technical Support team.

Worldwide:

North and South America:

Europe, Middle East, and Africa:

Email:

Web Site:

www.netiq.com/support/contactinfo.asp

1-713-418-5555

+353 (0) 91-782 677 [email protected]

www.netiq.com/support

Contacting Documentation Support

Our goal is to provide documentation that meets your needs. The documentation for this product is available on the NetIQ Web site in HTML and PDF formats on a page that does not require you to log in. If you have suggestions for documentation improvements, click Add Comment at the bottom of any page in the HTML version of the documentation posted at

www.netiq.com/documentation

. You can also email

[email protected]

. We value your input and look forward to hearing from you.

Contacting the Online User Community

NetIQ Communities, the NetIQ online community, is a collaborative network connecting you to your peers and NetIQ experts. By providing more immediate information, useful links to helpful resources, and access to NetIQ experts, NetIQ Communities helps ensure you are mastering the knowledge you need to realize the full potential of IT investments upon which you rely. For more information, visit

community.netiq.com

Advanced Authentication

About this Book

This document describes the HTTP REST API for Advanced Authentication Server v5.2. The document is intended for developers and contains information on how to integrate strong authentication into the applications.

Intended Audience

This book provides information for individuals responsible for understanding administration concepts and implementing a secure, distributed administration model.

About this Book

Advanced Authentication

Advanced Authentication Overview

In this chapter:

About Advanced Authentication

Advanced Authentication Server Appliance Functionality

Architecture

Terms

1.1 About Advanced Authentication

Advanced Authentication

is a software solution that enhances the standard user authentication process by providing an opportunity to logon with various types of authenticators.

Why choose Advanced Authentication

Advanced Authentication

...

...makes the authentication process easy and secure (no complex passwords, “secret words”, etc.)

...prevents unauthorized use of your computer

...protects you from fraud, phishing and similar illegal actions online

...can be used to provide secure access to your office

1.2 Advanced Authentication Server Appliance

Functionality

Benefits of using Advanced Authentication Server appliance are evident. Advanced Authentication

Server appliance...

...is cross-platform

...contains an inbuilt RADIUS server

...supports integration with Advanced Authentication Access Manager

...does not require scheme extending

...provides administrators with a capability of editing the configured settings through web-based

Advanced Authentication Administrative Portal

1.3 Architecture

In this chapter:

Basic Architecture

Advanced Authentication Overview

Enterprise Architecture

Enterprise Architecture with Load Balancer

1.3.1 Basic Architecture

The basic architecture of the Advanced Authentication is simple and requires only one Advanced

Authentication Server. You can use it for testing and proof of concepts.

Advanced Authentication Server is connected to a Directory that can be an Active Directory Domain

Services, NetIQ eDirectory, Active Directory Lightweight Directory Service or other compliant LDAP directories. An Event Endpoint can be Windows, Linux or Mac OS X machine, NetIQ Access

Manager, NetIQ CloudAccess, or RADIUS Client to authenticate through the RADIUS Server that is built-in the Advanced Authentication Server. For a complete list of supported events, see“

Configuring

Events

” in the

Advanced Authentication Server Administration Guide

1.3.2 Enterprise Architecture

The Enterprise architecture of the Advanced Authentication contains sites that can be created for different geographical locations. For example, the following illustration displays two Advanced

Authentication sites. Site A is the first site created for headquarters in New York. Site A’s first

Advanced Authentication Server contains the

Global Master

and

Registrar

roles. This server contains a master database and it can be used to register new sites and servers.

Site B is created for the office in London and it contains the identical structure. The master server in another site has

DB Master

role. DB Masters interacts with the Global Master.

DB Server

provides a DB Slave database that is used for backup and fail-over. You can create a maximum of two DB Slave Servers per site that can be DB Server 1 and DB Server 2. When the DB

Master is unavailable, the DB Slave node responds to the database requests. When the DB Master becomes available again, the DB Slave node synchronizes with the DB Master and the DB Master becomes the primary point of contact for database requests again.

Endpoints can interact with every server that contain a database.

Advanced Authentication

1.3.3 Enterprise Architecture with Load Balancer

The Enterprise architecture with Load balancer contains a more complicated architecture in

comparison with the

Enterprise Architecture

. The architecture contains the following components:

Web Servers

: Web Server does not contain a database. It responds to the authentication requests and connects to the DB Master database. You need more Web Servers to serve more workload. There is no limitation for Web Servers.

Load Balancer

: It provides an ability to serve authentication requests from the

External

Endpoints

. Load Balancer is a third-party component. It is located in DMZ and can be configured to interact with all the Advanced Authentication Servers.

Advanced Authentication Overview

1.3.4 How to Configure Load Balancer for Advanced

Authentication Cluster

Load balancer can be installed and configured via third party software. Below is an example of how to install and configure nginx as load balancer on Ubuntu 14.

Target configuration:

Domain controller

NAAF 5.1 master

Hostname

win-dc naafmaster

IP address

192.168.1.42

192.168.1.43

Role Operation System

AD DS, DNS Windows Server 2008

NAAF Master server NAAF 5.1.2

Advanced Authentication

NAAF 5.1 slave

Load balancer

Hostname

naafslave loadbalancer

IP address

192.168.1.41

192.168.1.40

Role Operation System

NAAF Slave server NAAF 5.1.2

Nginx load balancer Ubuntu 14

Before starting the configuration, please make sure that the following requirements are fulfilled:

Repository is configured in Advanced Authentication appliance.

Both Advanced Authentication servers are installed and configured as Master and Slave.

Appropriate entries are added to DNS.

Ubuntu 14 is installed.

To configure Load Balancer for Advanced Authentication cluster, it is required to install nginx on

Ubuntu 14 and configure it.

Installing nginx on Ubuntu 14

To install nginx on Ubuntu 14, follow the steps:

1. Open the following source list:

sudo nano /etc/apt/sources.list

2. Add necessary entries:

deb http://nginx.org/packages/ubuntu/ trusty nginx

deb-src http://nginx.org/packages/ubuntu/ trusty nginx

3. Update repository and install nginx:

apt-get update

apt-get install nginx

4. Start nginx and make sure that web server is working:

sudo service nginx restart

5. Open your browser and go to web server http://192.168.1.40 or http://loadbalancer.

Configuring nginx

The following load balancing mechanisms/methods are supported in nginx:

round-robin

- requests to the application servers that are distributed in a round-robin fashion

least-connected

- next request assigned to the server with the least number of active connections

ip-hash

- a hash-function that is used to determine what server should be selected for the next request (based on the client’s IP address)

This article describes only round-robin configuration. To configure nginx, follow the steps:

1. Backup original configuration file: sudo cp /etc/nginx/nginx.conf /etc/nginx/ nginx.conf_original

2. Open the nginx.conf file and replace with following:

Advanced Authentication Overview

user nginx; error_log /var/log/nginx/error.log warn; # error log location pid /var/run/nginx.pid; # process id file

# limit number of open sockets. Debian default max is 1024, ensure nginx not open all the sockets.

worker_processes 1; events { worker_connections 900; # 512 is default

}

# worker_processes auto; # ssl needs CPU http { include /etc/nginx/mime.types; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] "$request" '

'$status $body_bytes_sent "$http_referer" '

'"$http_user_agent" "$http_x_forwarded_for"'; access_log /var/log/nginx/access.log main; # access log location sendfile on;

# keepalive default is 75

# keepalive_timeout 10; gzip on; gzip_static on; gzip_comp_level 5; gzip_disable msie6; gzip_min_length 1000; gzip_proxied expired no-cache no-store private auth; gzip_vary on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/rss+xml application/atom+xml; ssl_certificate /etc/nginx/cert.pem; ssl_certificate_key /etc/nginx/cert.pem; ssl_session_cache shared:SSL:2m; # 1m stores 4000 sessions, default expire 5 min ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # disable TLSv3 - POODLE vulnerability resolver 192.168.1.42 valid=300s ipv6=off; # ip address of DNS resolver_timeout 10s; upstream web {

#server naafmaster.company.local:443 resolve;

#server naafslave.company.local:443 resolve; server 192.168.1.43:443; server 192.168.1.41:443;

} server {

#listen 80; listen 443 ssl; location / { proxy_pass https://web;

}

} proxy_set_header HOST $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

3. Copy certificate from any Advanced Authentication server in cluster from the directory /etc/nginx/

cert.pem to the same directory on load balancer.

4. Go to https://loadbalancer/admin page and make sure that connection was redirected to

Advanced Authentication cluster.

Advanced Authentication

IMPORTANT: Nginx can be installed and configured on any Linux supported by nginx.

Additional information on nginx configuration can be found at

http://nginx.org/en/docs/

1.4 Terms

In this chapter:

Authentication Method

Authentication Chain

Authentication Event

1.4.1 Authentication Method

Authentication Method verifies the identity of someone who wants to access data, resources, or applications. Validating that identity establishes a trust relationship for further interactions.

1.4.2 Authentication Chain

Authentication Chain is a combination of authentication methods. User needs to pass all methods in order to be successfully authenticated. E.g., if you create a chain which has LDAP Password and

SMS in it, the user will first need to enter his/her LDAP Password. If the password is correct, the system will send SMS with an One-Time-Password to the mobile of the user. The user needs to enter the correct OTP in order to be authenticated.

It is possible to create any chain. So for high secure environments it is possible to assign multiple methods to one chain to achieve better security.

Authentication can consist of 3 different factors. These are:

Something you know: password, PIN, security questions

Something you have: smartcard, token, telephone

Something you are: biometrics like fingerprint or iris

Multi-Factor or Strong Authentication is when 2 out of the 3 factors are used. A password with a token, or a smartcard with a fingerprint are considered to be multi-factor authentication. A password and a PIN is not consideed to be multi-factor as they are in the same area.

Authentication chains are linked to user groups in your repositories. So only a certain group can be allowed to use the specific authentication chain.

1.4.3 Authentication Event

Authentication Event is triggered by an external device or application which needs to perform authentication. It can be triggered by a RADIUS Client (Citrix Netscaler, Cisco VPN, Juniper VPN, etc) or API request. Each event can be configured with one or more authentication chains which will provide user with a capability to authenticate.

Within the Advanced Authentication framework, an authentication event is configured in the Events section. It is possible to enable or disable an event, and to add method-chains to the event. With specific events it is possible to assign clients to the event.

Advanced Authentication Overview

Advanced Authentication

About the API

The current API version is 1.0. Since API is based on REST principles, it is easy to write and test applications. The browser can be used to access URLs. Any HTTP client in any programming language can be also used to interact with the API.

API accepts and responds with JSON objects.

Base URL

The Base URL of the REST API is https://authserver.example.com/api/v1/

Replace authserver.example.com by hostname of your appliance.

Use the HTTPS protocol for more security with interaction with server’s REST API. The authentication server can return security information, e.g. Domain passwords. Note that some network libraries can block self-signed SSL certificate.

Main Processes

The Authentication Server has two main processes:

Logon Process

Enrollment Process

2.1 Logon Process

The logon process provides authentication and authorization, the enrollment process stores authentication information for new authentication methods. For enrollment, you should be authenticated before. The following picture describes the logon process.

About the API

Figure 2-1

Picture 1 - Logon process

The logon process includes several steps:

Create endpoint session

– Endpoints are devices which connect to the server. A valid endpoint session is needed in order to communicate with the server. This is a sub process. For more

information, check the

Working With Endpoint Sessions

chapter.

Do authentication

– The user can perform the actual authentication after creating the endpoint session. Authentication is a sub process. For more information, check the

Provide Authentication

chapter.

Working with user's data

– Information about a user like password or any other credential can be stored in the user data container and can be accessed after a successful authentication. For more information, check the

Working With User's Data

chapter. It is also possible to start an enrollment after successfully authenticating the user.

Delete login session

– After authentication the login session should be deleted. For more

information, check the

Delete Login Sessions

chapter.

Advanced Authentication

Does another user want to authenticate?

- after the login session is deleted, the system will wait for another user. If a new user wants to login, the process will be started from the second step because the endpoint is already created.

Delete endpoint session

- the logon process will delete endpoint session at the end. For more

information, check the

Delete Endpoint Session

chapter.

2.2 Enrollment Process

The following chart describes the enrollment process.

Figure 2-2

Picture 2. Enrollment process.

Enrollment process contains several steps.

Start enrollment process

- this step is the primary one in the enrollment process. For more

information, check the

Start Enroll Process

chapter.

Collect enroll data

- when the enrollment process is started, the user’s credentials will be collected. For more information, check the

Providing Data Into Enroll Process

chapter.

3. If this is a new enrollment the enrollment data will be saved. If the user already has an enrollment for this specific method the enrollment data will be updated:

Create new user authentication template

- For more information, check the

Create User's

Templates From Enroll Session

chapter.

Update user authentication template

- For more information, check the

Updating User's

Template

chapter.

Stop enrollment process

- after collecting enrollment data, enrollment process should be stopped. For more information, check the

Delete Enroll Process

chapter.

The

Working With Enrollment

chapter contains information of the enrollment process.

The

Working With User's Templates

chapter describes users’ templates .

About the API

Advanced Authentication

API Documentation

3.1 Localization

The appliance is supported in different languages and help users with their troubles and problems.

If you want to use the localized messages, specify locale in you requests. For this, use a special parameter.

Parameter Name

_LOCALE_

Parameter Description

The locale for messages in responses from server, you could use it in different formats: languages with territory, for example, en_US, nl_NL, or ru-RU, fr-FR, or just languages, for example, ru, nl, fr.

For GET request add this parameter as a URL parameter, for POST, PUT and PATCH add this parameter as a JSON parameter in request body. If for some reasons, you couldn't change a request URI or body, you could specify a cookie with the parameter name and value and server will automatically read it and change locale, or you could add the header "Accept-Language" with locale value in your request.

There are the list of supported locales

Locale Locale Value Language

If you could not find your locale in table above, you could use a messages identifier for your custom localization. In responses you could find this parameter with identifier of message.

Parameter Name

msgid

Parameter Description

The identifier of the message for message customization.

This parameter could be used for additional messaging too, but do not use this parameter for checking status of an authentication process or other statuses, for this kind of checking API has special parameters.

On requests and response in examples below all messages in default English locale, message identifier was removed.

API Documentation

3.2 Working With Endpoints

3.2.1 About Endpoints

The appliance provide user’s authentication in different places, ex. Microsoft Windows, Apple MacOS

X or other custom applications and systems. The final destination of user’s authentication is endpoint.

The endpoint could be a physical workstation or an application. The endpoints are combined in the events, the event is a logical separation for the endpoints. The Windows logon and Mac OS logon are different events, each event could had some set of the endpoints, and endpoints are Mac or Windows workstations. System has the following standard events.

Table 3-1

Supported Events List

Event name

Windows logon

Template management

Endpoint management

NAM

NCA

Admin user interface

Radius Server

Helpdesk

MacOS logon

Event identifier

WINDOWS

TEMPLATES

ENDPOINTS

NAM

NCA

ADMIN

RADIUS

HELPDESK

MACOS

Description

Event for log on in Microsoft Windows, used for authentication on Windows based operation system.

Template (authenticator) management event, this event is used for the enrollment process, collecting authentication data and updating user’s template.

Endpoint management event, for management endpoints use this event.

Event for Advanced Authentication Access Manager.

Event for Advanced Authentication Cloud Access.

The event for logon into Advanced Authentication

Administrative Portal.

The event for logon by RADIUS server.

The event for logon into Advanced Authentication

Helpdesk Portal.

The event for log on in Apple MacOS.

3.2.2 Create Endpoint

For creating endpoint, you could use the following resource with URI:

/endpoints

Resource provided by HTTP POST and has these parameters as JSON-object.

Table 3-2

URI Parameters for creating endpoint.

URI parameter name

name typ desc

Description

A name for the new endpoint.

A type identifier of the new endpoint.

A description of the new endpoint

Advanced Authentication

The appliance supports this list of the endpoints types:

Table 3-3

Supported endpoint types

Type value

TYP_UNKNOWN

TYP_WINDOWS_CLIENT

TYP_NAM

TYP_MACOS_CLIENT

TYP_LINUX_CLIENT

TYP_NCA

Type identifier Description

The unknown type for the endpoint, use this value if you couldn’t use other identifier.

The identifier for the Windows Clients.

The identifier for the Advanced Authentication Access

Manager.

The identifier for the Mac OS Clients.

The identifier for the Linux Clients.

The identifier for the Advanced Authentication

CloudAccess.

The identifier for the RADIUS client.

TYP_RADIUS

The resource returns a JSON-object, which contain the identifier and the secret of the created endpoint.

Table 3-4

Object with created endpoint.

Parameter name

id secret

Description

The identifier of the created endpoint.

The secret of the created endpoint.

Example

The following example demonstrates how to create a new endpoint.

HTTP POST https://authserver.example.com/api/v1/endpoints equest

{

"name":"nam.company.local",

"typ":3,

"desc":"NAM endpoint"

}

Response

{

"id":"885f71c85b8711e5b507000c2951aca4",

"secret":"Mxy4NJLHEGYicviRqrPqdaxRo0RAQtYn"

}

3.2.3 Delete Endpoint

For deleting endpoint, you could use the following resource with URI:

/endpoints/{endpoint_id}?secret={endpoint_secret}

API Documentation

Resource is provided by HTTP DELETE. It has the following parameters.

URI Parameter Name

endpoint_id secret

Parameter Description

Endpoint identifier. Identifier of endpoint for deleting.

The secret of the endpoint for deleting

Resource does not return any data. If the deletion is successful, the HTTP 200 status will be returned.

Example

Endpoint with identifier “42424242424242424242424242424242” and secret “1234567890” will be deleted in the following example.

HTTP DELETE https://authserver.example.com/api/v1/endpoints/

42424242424242424242424242424242?secret=1234567890

Response

HTTP 200

3.3 Working With Endpoint Sessions

3.3.1 About Endpoint Sessions

Endpoint is any logical or physical unit which interacts with the authentication server. E.g., client computer, tablet device, smartphone, any software or system is an endpoint. Endpoint should create endpoint session on the server to start working. The appliance use endpoints’ sessions for checking what PC wants to get access, the appliance supports endpoint’s white lists for events, also the appliance can check the owner for an endpoint. The whitelist for events can restrict access to the endpoints, for example, if a workstation (as endpoint) is not added to the whitelist for the Windows or

Mac OS event, the workstation cannot use advanced authentication. Each endpoint has an identifier and secret. Secret is a security value that is used for generating endpoint security hash. Security hash is used to start endpoint session. The algorithm for generating the secret hash is represented on the following picture.

Advanced Authentication

Figure 3-1

Algorithm for generating the secret hash

After SHA-256 function, you should transform result to a HEX-value string. All parameters are string.

All concatenation functions are string concatenation functions. The salt should be generated on the client side. It is advised to use a strong algorithm for generating the salt.

The following example shows how to generate secret hash.

Endpoint id = 42424242424242424242424242424242

Salt = e26eaecba7cbe186c08469f6ddbf6f6c0321651b53f80d8eb2c3b0d4e1c19c4c

Endpoint secret = 12345678

Middle result = e53e75ec3d48171abff1e4d2f0a5066e64fdbe11a4d3fd7c45810d7d93c26956 =

SHA256(endpoint id + salt)

Result 3b5dac383282df6936f9350a01ad079096f777f5c44eda8e0c2e66bfc443ee26 =

SHA256(endpoint secret + middle result)

The endpoint identifier and endpoint secret need to be very secure. This information should be kept in a secure place and parameters should be changed every time the information is compromised.

Endpoints can work with the server and provide user authentication after the endpoint session creation. The endpoint session has a lifetime, after this, the endpoint session will be deleted and the session will need to be renewed. All users can work with one endpoint session on one endpoint.

API Documentation

3.3.2 Create Endpoint Session

To create the endpoint session, use the following resource with URI:

/endpoints/{endpoint_id}/sessions

Resource is provided by HTTP POST. It has the following parameter.

Table 3-5

URI parameters for creating endpoint session.

URI Parameter

endpoint_id

Description

Endpoint identifier. Identifier of endpoint that creates endpoint session.

Resource accept JSON-object with these parameters.

Table 3-6

Parameters for creating endpoint session.

Parameter name

salt endpoint_secret_hash session_data

Description

Client generated salt. This salt is used in secret hash generated algorithm.

Generated secret hash by algorithm.

Any session data. This is a JSON-object with any parameters and structure.

The resource returns JSON-object with the following endpoint session identifier.

Table 3-7

JSON-object with created endpoint session.

Parameter name

endpoint_session_id

Parameter description

Endpoint session identifier. This is an identifier of the created endpoint session. It should be used for other methods.

Example

Endpoint with identifier “42424242424242424242424242424242” creates endpoint session. Endpoint has already generated salt and endpoint secret hash.

HTTP POST https://authserver.example.com/api/v1/endpoints/42424242424242424242424242424242/ sessions

Request

{

"salt":"2615c070937935246c6a91df70a8eb672b21d842a225621c9797a83bedf00a7b",

"endpoint_secret_hash":"38d55fb7a899dcef6cbec053df8f7673cb05068b9ee9d6a23ee759232b

25cf4e",

"session_data":{}

}

Response

{

"endpoint_session_id":"IRx7UXwenytMn5B7fgRSH4k1s6PAAs0I"

}

Advanced Authentication

3.3.3 Read Information About Endpoint Sessions

To read information about endpoint session, use the following resource with URI:

/endpoints/{endpoint_id}/sessions/

{session_id}?salt={salt}&endpoint_secret_hash={endpoint_secret_hash}

Resource is provided by HTTP GET. It has the following parameters.

Table 3-8

URI parameters for reading information about endpoint session.

URI parameter name

endpoint_id session_id salt Salt endpoint_secret_hash

Description

Endpoint identifier. Identifier of endpoint which session will be read.

Session identifier. Identifier of endpoint session for reading.

It is used for generated endpoint secret hash

Endpoint secret hash.

Resource returns JSON-object which contains the following information about endpoint session.

Table 3-9

JSON-object with information about endpoint session.

Parameter name

sid endpoint_id session_data

Description

Endpoint session identifier, identifier of endpoint session

Endpoint identifier

Session data, this data can be added on creating session, this is any JSON-object with any structure.

Example

We read the endpoint session information for endpoint with identifier

“42424242424242424242424242424242”. Session identifier is

”T2Fv3FOvWojyBOZBlsik1d9RBDjDr9Rq”. Endpoint has already prepared secret hash and salt.

HTTP GET https://authserver.example.com/api/v1/endpoints/42424242424242424242424242424242/ sessions/

T2Fv3FOvWojyBOZBlsik1d9RBDjDr9Rq?salt=279bc0da2a9da8afcfda50c2bc3f418218354020d73c

00a6a088dea704ece3f9&endpoint_secret_hash=bfe7b1e1cad57525a9695f39eb5cff4d4dd7a42e

039122c732adb151d097835c

Response

{

"sid":"T2Fv3FOvWojyBOZBlsik1d9RBDjDr9Rq",

"endpoint_id":"42424242424242424242424242424242",

"session_data":null

}

API Documentation

3.3.4 Delete Endpoint Session

To delete an endpoint session, use the following resource with URI:

/endpoints/{endpoint_id}/sessions/

{session_id}?salt={salt}&endpoint_secret_hash={endpoint_secret_hash}

Resource is provided by HTTP DELETE. It has the following parameters.

Table 3-10

URI parameters for deleting endpoint session.

URI parameter name

endpoint_id session_id salt Salt endpoint_secret_hash

Description

Endpoint identifier. Identifier of endpoint which session will be deleted.

Session identifier. Identifier of endpoint session to be deteled.

It is used for generated endpoint secret hash.

Endpoint secret hash.

Resource does not return any data. If the deletion is successful, the HTTP 200 status will be returned.

Example

Endpoint with identifier “42424242424242424242424242424242” deletes session with identifier

“9Ml1ByqdIsCr3re5C0aivXR6ap20fNW8”.

HTTP

DELETE https://authserver.example.com/api/v1/endpoints/42424242424242424242424242424242/ sessions/

9Ml1ByqdIsCr3re5C0aivXR6ap20fNW8?salt=4b470b4ee96630ced049a78d6488ee127b9d419f4635

30c63f3e1ee27226f721&endpoint_secret_hash=c2bf7b8288aa55de22baa9d077150d83b3460d59

51a57d6e7ccf2a01f61bc9ec

Response

HTTP 200

3.4 Provide Authentication

3.4.1 About Login Process

The server provides strong user authentication by using the chain-login concept. Each chain is a challenge-response login. The following chart describes chain logic. To get a successful authentication, the entire chain should be completed. A chain can consist of one or several authentication method(s).

Advanced Authentication

Figure 3-2

Chain logic.

The user should start the logon process and pass all authentication methods. If all of them are successful, the user will login. If not, he/she will fail and should start the logon process once again.

API has the following standard responses for authentication status description.

Table 3-11

Response statuses.

Status name

More data

Failed

Status value Description

MORE_DATA This status is used to indicate that authentication method requests for additional data for authentication. Each authentication method requests different data.

NEXT This status indicate that current method finished, you should check completed_methods parameter from server response to be sure that current method was really finished.

FAILED

This status is used to describe success result of logon process. Server has created the login session.

This status is used for unsuccessful result of logon process description. It indicates that the logon process should be started once again.

API Documentation

For additional information the server also returns the authentication reasons, the server has standard reasons for all authentication methods and specific reasons for each authentication method. Please check authentication method description for more information about supported authentication reasons.

Table 3-12

Common authentication reasons

Reason value

METHOD_COMPLETED

METHOD_NOT_NEEDED

METHOD_RETRY

ENDPOINT_DISABLED

ENDPOINT_NO_ACCESS

CHAIN_DISABLED

CHAIN_COMPLETED

PROCESS_STARTED

PROCESS_NOT_FOUND_OR_EXPIRED

Description

The authentication method was completed

The authentication method not needed. The event does not work with this method

The authentication method was retried

The endpoint is disabled

The endpoint has no access

The authentication chain is disabled

The authentication chain was completed

The authentication process was started

The authentication process was not found or process is expired, you should start a new logon process

User is locked USER_LOCKED

Once the chain is completed, user’s data associated with event can be accessed. Event is the logical final destination for login process. Each event is a security point of the system and the login process provides authentication and authorization to this event. Organizations can create their own login chains with different authentication method. Currently the following authentication methods are supported.

Table 3-13

Authentication methods.

Authentication method name

Authentication method identifier

Description

LDAP password

One-time password based on hash algorithm

HOTP:1

One-time password based on time algorithm

LDAP_PASSWORD:1 Authentication by LDAP password, system uses different LDAP users repository and provide authentication by LDAP password, check the

LDAP

Password Authentication Method chapter

TOTP:1

Authentication by OTP with hash algorithm, check the

HOTP Authentication Method chapter

Authentication by OTP with time based algorithm, check

the TOTP Authentication Method chapter

One-time password sending by e-mail

EMAIL_OTP:1

One time password sending by SMS

SMS_OTP:1

RADIUS password RADIUS:1

Authentication by OTP sending by e-mail, check the

Email Authentication Method

Authentication Method

chapter

Authentication by OTP sending by SMS, check the

chapter

Authentication by RADIUS server, check the

Authentication Method chapter

SMS

RADIUS

Advanced Authentication

Authentication method name

Authentication method identifier

Description

Security question

Smartphone authentication

Virtual password

Voice call

Cards

FIDO U2F

Emergency password

NotarisID

PKI

SECQUEST:1

SMARTPHONE:1

PASSWORD:1

VOICE:1

Authentication by security question, check the

Security

Questions Authentication Method

chapter

Authentication by smartphone application, check the

Smartphone Authentication Method chapter

Authentication by password assign to user, check the

Password Authentication Method chapter

Authentication by voice call, check the Voice Call

Authentication Method chapter

CARD:1

U2F:1

Authentication by cards, check the

Card Authentication

Method chapter

Authentication by FIDO U2F tokens, check the

FIDO

U2F Authentication Method chapter

EMERG_PASSWORD:

Authentication by emergency password, check the

Emergency Password Authentication Method chapter

NOTARIS_ID:1

PKI:1

Authentication by NorarisID, see the “NotarisID authentication method” capter.

The authentication by PKI (Public key infrastructure), see the “PKI authentication method” chapter.

Combining different authentication methods into authentication chains provides strong protection for different applications.

Before you start the logon process, you should create an endpoint session. The endpoint is the final destination for the login process. E.g., a client PC is an endpoint. One endpoint session can provide many logon processes. Endpoint session should be created once and used for all logon processes.

For more information on endpoint session, check the

Create Endpoint Session

chapter.

3.4.2 Provide Simple Authentication Using One Method In A

Chain

API has two resources for providing login:

for starting the login session

for providing data to the authentication provider

This chapter describes how to provide a simple logon with one authentication method in the chain.

To start the logon process, the request should be sent to the following resource with URI:

/logon

Resource is provided by HTTP POST. It accepts JSON-object which describes the new logon process.

API Documentation

Table 3-14

Parameters for staring new login process.

Parameter name

endpoint_session_id method_id user_name event is_1N unit_id

Description

Endpoint session identifier. Identifier of endpoint which creates logon session.

Authentication method identifier. Identifier of method from authentication methods list that is supported by the server. This parameter defines which method will be used for

authentication. To view the list of the supported methods, check the Authentication methods.

User name for login. User name should be provided in format repo_name/user_name, where repo_name is user’s repository name from server, user_name is user name.

Event identifier. Event from list of events supported by server.

The boolean flag identify is authentication will be 1:N or not, if true, that authentication will be 1:N, if false – not 1:N

The unit identifier, use this value with is_1N flag, if you use this parameter you should not provide user name for the authentication

Table 3-15

Created login session.

Parameter name

chains completed_methods current_method msg logon_process_id plugins status event_name reason

Description

JSON-object, which describe available chains for login.

JSON-array, which contain list of completed authentication methods supported by the server.

Current authentication method, which is used for authentication.

Message about process, contains more information about authentication process or about errors.

Logon process identifier, identifier of current logon process, this identifier is constant in the authentication process and is used in next steps.

JSON-array, that contain list of available plugins.

Current status of logon process, check the

Response statuses.

for more

information.

The event name for started logon process

The authentication reasons, please check the

Common authentication reasons

The event data identifier for started logon process event_data_id

Chains JSON-object has these parameters.

Advanced Authentication

Table 3-16

Chain JSON-object.

Parameter name

methods is_trusted name image_name apply_for_ep_owner position is_enabled short_name

Description

JSON-array of authentication methods represented into chain. All of these methods should be successful for login.

Boolean flag which determinate is it trusted chain or not.

Name of authentication chain.

The image name for this chain

This is a boolean flag, if true – this is an authentication chain for the endpoints owner and this chain will have priority over other chains

The position of this chain in an authentication chains list

The boolean flag, if it true chain is enabled, if false – disabled

The short name of the chain

After starting the logon process, authentication data for the current authentication method in the chain should be sent. To send authentication data, use the following resource with URI:

/logon/{logon_process_id}/do_logon

Resource is provided by HTTP POST. It has the following parameters.

Table 3-17

URI parameters for sending authentication data.

URI parameter name

logon_process_id

Description

Logon process identifier. Identifier of started logon process.

Resource accepts data as JSON-object with these parameters.

Table 3-18

Parameters for providing authentication data.

Parameter name

response endpoint_session_id

Description

JSON-object with authentication data for method. This object is different for all authentication methods.

Endpoint session identifier. Identifier of endpoint, which works with logon session.

Resource return JSON-object with data of authentication result.

Table 3-19

JSON-object with authentication result.

Parameter name

chains current_method

Description

JSON-object, which describes available chains for login, check the Table 3-16

Chain JSON-object for more information.

Current authentication method, which is used for authentication.

API Documentation

Parameter name

logon_process_id completed_methods status repo_id user_name user_id msg login_session_id plugins reason event_name repo_obj_id user_sid user_name user_mobile_phone user_dn event_data_id user_sid_hex user_email user_cn data_id user_name_netbios user_upn

Description

Logon process identifier, identifier of current logon process, this identifier is constant in the authentication process and is used in next steps.

JSON-array, which contains list of completed authentication methods supported by server.

Current status of logon process. Check the

About Login Process

for more information.

Repository identifier, server identifier of users’ repository.

User name.

User server identifier.

Message about process, contains more information about authentication process or about errors.

JSON-array, that contain list of available plugins.

The authentication reasons, please check the

Common authentication reasons

The event name

The identifier of the repository object

The user’s SID

The user name, e.g. COMPANY\JSmith

The user’s mobile phone if it presents.

The user FQDN-name

The event data identifier

The user’s SID as hex-string

The user’s email if it presents

The user canonical domain name

The data identifier

The user’s NETBIOS name, if user came from Active Directory

The user principal name, if user came from Active Directory

Each authentication method has a different number of challenge-response steps, check method description for more information.

Example

On the following example, user “JSmith” from repository “COMPANY” tries to login to the NAM endpoint with session identifier “46kGFB3MUUebkcqosO9t4pVAVURsCMyz”.

Advanced Authentication

HTTP POST https://authserver.example.com/api/v1/logon

Request

{

"method_id":"LDAP_PASSWORD:1",

"user_name":"COMPANY\\JSmith",

"event":"NAM",

"endpoint_session_id":"46kGFB3MUUebkcqosO9t4pVAVURsCMyz"

}

Response

{

"plugins": [],

"event_name":"NAM",

"msg":"Process started",

"status":"MORE_DATA",

"reason":"PROCESS_STARTED",

"current_method":"LDAP_PASSWORD:1",

"completed_methods":[],

"chains":[

{

"is_enabled":true,

"apply_for_ep_owner":false,

"is_trusted":null,

"image_name":"default",

"name":"LDAP password",

"position":0,

"methods":["LDAP_PASSWORD:1"],

"short_name": ""

}],

"logon_process_id":"zGjcx3Kbh3scIbTXXCefo1lR86BZ5V0k",

"event_data_id":"OSLogon"

}

HTTP POST https://authserver.example.com/api/v1/logon/zGjcx3Kbh3scIbTXXCefo1lR86BZ5V0k/ do_logon

Request

{

"response":

{

"answer":"123"

"endpoint_session_id":"46kGFB3MUUebkcqosO9t4pVAVURsCMyz"

}

Response

{

"msg":"Welcome!",

"user_mobile_phone":"+16086783619",

"event_name":"NAM",

"repo_id":"d3fba00652d211e5a19a000c2951aca4",

"user_email":"[email protected]",

"user_name": "COMPANY\\JSmith",

"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",

"completed_methods":["LDAP_PASSWORD:1"],

"chains":[

{

"is_enabled":true,

"apply_for_ep_owner":false,

"is_trusted":null,

"image_name":"default",

"name":"LDAP password",

API Documentation

"position":0,

"methods":["LDAP_PASSWORD:1"],

"short_name": ""

}],

"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",

"user_name_netbios":"COMPANY\\JSmith",

"user_cn":"JSmith",

"user_id":"ab2b845652d311e5a19a000c2951aca4",

"login_session_id":"BF7xjPVyO9wSqFj9UY0II1qzsemfcVqD",

"plugins":["LdapRules"],

"data_id":"OSLogon",

"status":"OK",

"reason":"CHAIN_COMPLETED",

"current_method":"LDAP_PASSWORD:1",

"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",

"logon_process_id":"zGjcx3Kbh3scIbTXXCefo1lR86BZ5V0k",

"event_data_id":"OSLogon",

"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450"

}

3.4.3 Provide Chained Authentication

Chained authentication is like a simple authentication, it uses from the same logic as the simple authentication process and has the same JSON-object and other parameters. The differences are in step count, chained authentication combines many authentication methods and all of them should be passed successfully.

The logic of the chained authentication is displayed on the following chart. In this login, you should start next authentication method until you get successful or unsuccessful result. When the logon process is started, it will be required to choose authentication method and provide data for this authentication method at first iteration of logon process.

Advanced Authentication

Figure 3-3

Picture 5. Chained authentication.

API for chained login has an additional resource for starting next authentication method, this resource has the following URI:

/logon/{logon_process_id}/next

Resource is provided by HTTP POST. It has the following URI parameter.

Table 3-20

URI parameters for starting next authentication method.

URI Parameter name

logon_process_id

Description

Logon process identifier, identifier of started logon process.

Resource accepts JSON-object which contains information about the next authentication method.

API Documentation

Table 3-21

Parameters for starting next authentication method.

Parameter name Description

endpoint_session_id Endpoint session identifier. Identifier of endpoint, which will create logon session, check the

Create Endpoint Session chapter for more information.

method_id Authentication method identifier. Identifier of next method from authentication methods list that is supported by server. This parameter defines which method will be used for authentication, check

Authentication methods.

for more information.

Resource return JSON-object equal to JSON-object returned form resource for starting logon

process, check the

Created login session.

for more information. Other requests to resources used for

chained login described in the same chapter.

Example

In the following example, user with username “JSmith” from users’ repository “COMPANY”, tries to logon from endpoint with session identifier “LTcnApseCzyFQCnDbxdid3rEvkgWk2f2”, user use chain with LDAP password and counter based one-time password, user authenticates to the NAM event.

HTTP POST https://authserver.example.com/api/v1/logon

Request

{

"method_id":"LDAP_PASSWORD:1",

"user_name":"COMPANY\\JSmith",

"event":"NAM",

"endpoint_session_id":"LTcnApseCzyFQCnDbxdid3rEvkgWk2f2"

}

Response

{

"event_name":"NAM",

"reason":"PROCESS_STARTED",

"completed_methods":[],

"chains":[

{

"position":0,

"methods":["LDAP_PASSWORD:1", "HOTP:1"],

"is_enabled":true,

"name":"Password & HOTP",

"image_name":"default",

"apply_for_ep_owner":false,

"short_name":"",

"is_trusted":null

}],

"current_method":"LDAP_PASSWORD:1",

"status":"MORE_DATA",

"event_data_id":"OSLogon",

"plugins":[],

"msg":"Process started",

"logon_process_id":"cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB"

}

HTTP POST https://authserver.example.com/api/v1/logon/cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB/ do_logon

Request

{

"response":

Advanced Authentication

{

"answer":"P@$sW0rd"

"endpoint_session_id":"LTcnApseCzyFQCnDbxdid3rEvkgWk2f2"

}

Response

{

"event_name":"NAM",

4fa243fe48d6a13b9b50555fd1dcba273327398e9f665a945a73559"user_dn":"CN=John

Smith,CN=Users,DC=company,DC=local",

"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-1602",

"user_upn":"[email protected]",

"user_id":"395e14fc65ec11e58f04000c2951aca4",

"plugins":["LdapRules"],

"repo_id":"cd2ce1fa65eb11e58f04000c2951aca4",

"completed_methods":["LDAP_PASSWORD:1"],

"msg":"Continue with next login method",

"user_name_netbios":"COMPANY\\JSmith",

"reason":"METHOD_COMPLETED",

"repo_obj_id":"373bf00f9421394ab36c69f9d82283e4",

"chains":[

{

"position":0,

"methods":["LDAP_PASSWORD:1", "HOTP:1"],

"is_enabled":true,

"name":"Password & HOTP",

"image_name":"default",

"apply_for_ep_owner":false,

"short_name":"",

"is_trusted":null

}],

"current_method":"LDAP_PASSWORD:1",

"status":"NEXT",

"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768420600",

"event_data_id":"OSLogon",

"user_cn":"John Smith",

"logon_process_id":"cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB",

"user_name":"COMPANY\\John Smith"

}

HTTP POST https://authserver.example.com/api/v1/logon/cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB/next

Request

{

"method_id":"HOTP:1",

"endpoint_session_id":"LTcnApseCzyFQCnDbxdid3rEvkgWk2f2"

}

Response

{

"event_name":"NAM",

"reason":"PROCESS_STARTED",

"completed_methods":["LDAP_PASSWORD:1"],

"chains":[

{

"position":0,

"methods":["LDAP_PASSWORD:1", "HOTP:1"],

"is_enabled":true,

"name":"Password & HOTP",

"image_name":"default",

"apply_for_ep_owner":false,

"short_name": "",

API Documentation

"is_trusted":null

}],

"current_method":"HOTP:1",

"status":"MORE_DATA",

"event_data_id":"OSLogon",

"plugins":[],

"msg":"Process started",

"logon_process_id":"cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB"

}

HTTP POST https://authserver.example.com/api/v1/logon/cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB/ do_logon

Request

{

"response":

{

"answer":"150522"

"endpoint_session_id":"LTcnApseCzyFQCnDbxdid3rEvkgWk2f2"

}

Response

{

"event_name":"NAM",

"user_email":"[email protected]",

"user_dn":"CN=John Smith,CN=Users,DC=company,DC=local",

"plugins":["LdapRules"],

"repo_id":"cd2ce1fa65eb11e58f04000c2951aca4",

"msg":"Welcome!",

"logon_process_id":"cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB",

"reason":"CHAIN_COMPLETED",

"repo_obj_id":"373bf00f9421394ab36c69f9d82283e4",

"user_cn":"John Smith",

"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-1602",

"event_data_id":"OSLogon",

"user_id":"395e14fc65ec11e58f04000c2951aca4",

"user_upn":"[email protected]",

"login_session_id":"NjHg8gVLMwYI84BDzlgFxNn5HI53ioI2",

"user_name_netbios":"COMPANY\\JSmith",

"completed_methods":["LDAP_PASSWORD:1", "HOTP:1"],

"chains":[

{

"position":0,

"methods":["LDAP_PASSWORD:1", "HOTP:1"],

"is_enabled":true,

"name":"Password & HOTP",

"image_name":"default",

"apply_for_ep_owner":false,

"short_name":"",

"is_trusted":null

}],

"current_method":"HOTP:1",

"status":"OK",

"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768420600",

"data_id":"OSLogon",

"user_name":"COMPANY\\John Smith"

}

Advanced Authentication

3.4.4 1:N Authentication

The 1:N authentication could contain one or more chains and it equals non 1:N authentication. For starting 1:N authentication you should at first provide the unit identifier and set the 1:N flag to true and you should exclude user name from first request. The 1:N logon process is absolutely the same as non 1:N logon process, provide authentication data to the method and work with methods as you work with non 1:N logon process.

3.4.5 Read Available Chains

Before you start the logon process, you should get available authentication chains for this endpoint and user. The API has the following resource for this with URI.

/logon/ chains?user_name={user_name}&event={event}&endpoint_session_id={endpoint_session_i d}

Resource provided by HTTP GET and has these parameters.

Table 3-22

Parameters for getting available chains.

URI parameter name Description

user_name event endpoint_session_id

User name, this parameter is optional, if you use this parameter, server return chain only for this user, if not – chains for all users.

Event identifier from server supported events list. Check “Supported events list” for getting events list.

Endpoint session identifier, identifier of endpoint session, which want to get the chains. Check the

Create Endpoint Session chapter for more information.

Resource return JSON-object, which contain list of available chains.

Table 3-23

Object with available chains.

Parameter name Description

chains Chain, this parameter using for wrapping of chains JSON-object array, chain object described in

Chain JSON-object.

, check for more information about chain object.

Example

On the following example, endpoint with session “2NC69uuu0r63fYpqamMSJfYEVjIkSsbv” tries to get all trusted chains available for NAM event.

API Documentation

HTTP GET https://authserver.example.com/api/v1/logon/ chains?event=NAM&endpoint_session_id=2NC69uuu0r63fYpqamMSJfYEVjIkSsbv&is_trusted=t rue

Response

{

"chains":[

{

"methods":["LDAP_PASSWORD:1", "RADIUS:1"],

"is_trusted":true,

"name":"RADIUS and LDAP",

"position":0,

"is_enabled":true,

"image_name":"default",

"apply_for_ep_owner":false,

"short_name":""

{

"methods":["LDAP_PASSWORD:1", "TOTP:1"],

"is_trusted":true,

"name":"TOTP and LDAP",

"position":1,

"is_enabled":true,

"image_name":"default",

"apply_for_ep_owner":false,

"short_name":""

{

"methods":["LDAP_PASSWORD:1", "HOTP:1"],

"is_trusted":true,

"name":"HOTP and LDAP",

"position":2,

"is_enabled":true,

"image_name":"default",

"apply_for_ep_owner":false,

"short_name":""

}]

}

3.4.6 Priority of the Authentication Chains

The administrator of the Advanced Authentication appliance can manage the authentication chains priority and appliance will return chains in defined priority. You should use chain as it returned from the appliance. The chain which is highest on the priority list should be used first. For example, event has chain with LDAP authentication and chain with LDAP authentication and authentication by smartphone, and chain with LDAP authentication is higher, in this case for success authentication user should do LDAP authentication, it will be enough, but user also could add smartphone authentication after LDAP as additional authentication, appliance will allow this. If user not enroll method appliance will not return chains with this method. Same logic appears if the user could not use some of the method, for example, user have not phone number in user’s repository.

3.4.7 Delete Logon Process

You can delete the logon process, you can use the following resource with URI

/logon/{logon_process_id}?endpoint_session_id={endpoint_session_id}

Resource provided by HTTP DELETE and has these URI parameters.

Advanced Authentication

Table 3-24

URI parameters for deleting logon process.

URI parameter name

logon_process_id endpoint_session_id

Description

Logon process identifier, identifier of process for deleting.

Endpoint session identifier, identifier of endpoint session, which wants to delete the

chapter for more information.

The resource does not return any data, if deleting was successful the method return HTTP 200 status.

Example

On the following example, endpoint with session identifier

“Sm7hACXcyvfl4ApoQ17g5QntE0q1ZW1K” deletes logon process with identifier

“wLlxiBUCDDiTRJtL0xJPOeZpWfNcWfoH”.

HTTP DELETE https://authserver.example.com/api/v1/logon/ wLlxiBUCDDiTRJtL0xJPOeZpWfNcWfoH?endpoint_session_id=Sm7hACXcyvfl4ApoQ17g5QntE0q1Z

W1K

Response

HTTP 200

3.5 Working With Users

3.5.1 About Users

Appliance can provide information about stored users; you can get information about all users from all repository. You can not get this information only about one user, not as users’ list. This information available only for full administrators.

3.5.2 Getting Information About User

To get user information use the resource with URI:

/users?user_name={user_name}&login_session_id={login_session_id}

The resource has URI parameters

Table 3-25

The parameter for get information about user

URI parameter

user_name login_session_id

Description

The user name, appliance will return information about this user

The login session identifier, the identifier of login session for user with administrative role

The resource will return JSON object with user information.

API Documentation

Table 3-26

The object with information about user

Parameter name

id repo_id obj_id repo_name loginame user_name

Description

The user identifier

The repository identifier

The user identifier in repository

The repository name

The user name in repository

The user name with repository, repo\user_name

Example

On the following example, administrator with login session identifier

“cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB” will try to get information about user JSmith from

COMPANY repository.

HTTP GET https://authserver.example.com/api/v1/ users?user_name=COMPANY\JSmith&login_session_id=cdlsXhjaEHOaPiwTlOck5p0xGaqgkNJB

Response

{

"repo_id":"cd2ce1fa65eb11e58f04000c2951aca4",

"obj_id":"373bf00f9421394ab36c69f9d82283e4",

"id":"395e14fc65ec11e58f04000c2951aca4",

"user_name":"COMPANY\\John Smith",

"loginame":"JSmith",

"repo_name":"COMPANY",

}

3.6 Working With User's Data

3.6.1 About User's Data

Users’ data – data that is stored for a specific event for a user. After logon, you can get access to the user’s data. Users’ data is a JSON-object with a custom structure and parameter names. Each event has different users’ data, check event’s description for more information.

Appliance supports this list of users’ data storage.

Table 3-27

The list of users’ data storage

Data storage identifier

OSLogon

PasswordStore

Description

The data storage for operation systems logon processes and information

The data storage for user’s passwords

3.6.2 Read User's Data

For reading user’s data use resource with URI

Advanced Authentication

/users/{user_id}/data/{data_id}/

{data_parameter}?login_session_id={login_session_id}

Resource provided by HTTP GET and has these parameters.

Table 3-28

URI parameters for reading user’s data.

URI parameter name

user_id data_id data_parameter login_session_id

Description

User identifier, identifier of user, which wants to get assigned application data.

The data storage identifier, identifier of the storage which data will be read.

User’s data parameter, optional parameter. If you use this parameter, resource return only this parameter from user’s data.

Authentication

chapter for more information.

Resource return user’s data as JSON-object, each event has different data format, check description for more information.

Table 3-29

JSON-object for user’s data.

Parameter name

data

Description

Container for application data JSON-object, if method uses application data parameter, then this container will contain only application data parameter.

Example

On the following examples, user with identifier “6f4db9228c2711e4bb4100155d62a8b3” with login session identifier “cHIIvvAS4KteAG6MnVzJXx1I7TjVtnxP” gets data for storage “OSLogon” and then get only “test1” parameter from application data.

HTTP GET https://authserver.example.com/api/v1/users/6f4db9228c2711e4bb4100155d62a8b3/data/

OSLogon?login_session_id=cHIIvvAS4KteAG6MnVzJXx1I7TjVtnxP

Response

{

"data":

{

"test1":"value 1",

"test3": "value 3",

"test2": "value 2"

}

HTTP GET https://authserver.example.com/api/v1/users/6f4db9228c2711e4bb4100155d62a8b3/data/

OSLogon/test1?login_session_id=cHIIvvAS4KteAG6MnVzJXx1I7TjVtnxP

Response

{

"data":

{

"test1":"value 1"

}

API Documentation

3.6.3 Modifying User's Data

For modifying user’s data use resource with URI.

/users/{user_id}/data/{data_id}

Resource provided by HTTP PATCH and has these parameters.

Table 3-30

URI parameters for modifying user’s data.

URI parameter name

user_id data_id

Description

User identifier, method will add application data to this user.

The data storage identifier, resource will add data for this storage, user should be logged on to this event.

Resource accept JSON-object with user’s data.

Table 3-31

Parameters for modifying user’s data.

Parameter name

data login_session_id

Description

User’s data container, this parameter contains all user’s data, each event has different data format, check description for more information.

Resource does not returns any data, if the method is successful then it will return HTTP 200 status.

This resource has a flexible behavior, resource can update or modify data, for example, if user has no data, then resource add data for user for this event, if user has some data, then resource update parameters represented in request, add new parameters, if these parameters are not represented into current user’s data, and delete parameters, which set to null into request.

Example

On the following example, user with identifier “6f4db9228c2711e4bb4100155d62a8b3” and login session with identifier “BFldNh3rLx39gjmun65gwJpLETjGF5fO” add user’s data to storage

“OSLogon”.

HTTP PATCH https://authserver.example.com/api/v1/users/6f4db9228c2711e4bb4100155d62a8b3/data/

OSLogon

Request

{

"data":

{

"test1":"value 1",

"test2":"value 2",

"test3":"value 3"

"login_session_id":"BFldNh3rLx39gjmun65gwJpLETjGF5fO"

}

Response

HTTP 200

Advanced Authentication

3.6.4 Delete User's Data

For deleting user’s data use resource with URI

/users/{user_id}/data/{data_id}/

{data_parameter}?login_session_id={login_session_id}

Resource provided by HTTP DELETE and has these parameters.

Table 3-32

URI parameters for deleting user’s data.

URI parameter name

user_id data_id data_parameter login_session_id

Description

User identifier, identifier of user, which wants to delete application data.

The data storage identifier, identifier of storage where data will be deleted.

User’s data parameter, optional parameter. If you use this parameter, resource deletes only this parameter from user’s data. If you do not use this parameter, resource deletes all application data.

Resource does not return data, if method was success, then return HTTP 200 status.

Example

On the following example, user with identifier “6f4db9228c2711e4bb4100155d62a8b3” with login session identifier “H0u1NPOpPs6foZonfAxoRRDxgTsSYuVM” deletes data parameter “test1” for storage “OSLogon” and then deletes all data for “OSLogon”.

HTTP

DELETE https://authserver.example.com/api/v1/users/6f4db9228c2711e4bb4100155d62a8b3/data/

OSLogon/test1?login_session_id=H0u1NPOpPs6foZonfAxoRRDxgTsSYuVM

Response

HTTP 200

HTTP DELETE https://authserver.example.com/api/v1/users/6f4db9228c2711e4bb4100155d62a8b3/data/

OSLogon?login_session_id=H0u1NPOpPs6foZonfAxoRRDxgTsSYuVM

Response

HTTP 200

3.7 Working With Login Sessions

3.7.1 About Login Sessions

After a user logon, the system creates a login session, to access protected information from the server use this session. For example, reading event data requires a login session identifier. The API allows reading the login session information and deleting the session.

3.7.2 Read Information About Login Sessions

For reading information about login session use resource with URI

API Documentation

/logon/sessions/{logon_session_id}?endpoint_session_id={endpoint_session_id}

Resource provided by HTTP GET and has these parameters.

Table 3-33

URI parameters for reading information about login session.

URI parameter name

logon_session_id endpoint_session_id

Description

Logon session identifier, identifier of session for reading.

Endpoint session identifier, identifier of endpoint session.

Resource returns JSON-object, which contain information about login session.

Table 3-34

JSON-object with information about login session.

Parameter name

event_name repo_id user_id repo_obj_id

Description

Event name, name of event, which linked to this logon session.

Users’ repository identifier, identifier of users’ repository which used for user logon.

User identifier, identifier of user which create this logon session.

For later usage.

user_name data_id

User name, user name who create logon session.

Event data’s identifier, identifier of event which creates this session.

Example

On the following example, we try to get information about the session with identifier

“9hGUd3xuKE6VX0I8bVMWNeX1zNm0QfNd” from endpoint with session identifier

“Wpeg2ek8IvsNF1hFZTXqYjPYvhCdUsZd”.

HTTP GET https://authserver.example.com/api/v1/logon/sessions/

9hGUd3xuKE6VX0I8bVMWNeX1zNm0QfNd?endpoint_session_id=Wpeg2ek8IvsNF1hFZTXqYjPYvhCdU sZd

Response

{

"event_name":"NAM",

"repo_id":"6e0b696e8c2711e4bd9600155d62a8b3",

"user_id":"6f4db9228c2711e4bb4100155d62a8b3",

"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",

"sid":"9hGUd3xuKE6VX0I8bVMWNeX1zNm0QfNd",

"user_name":"COMPANY\\JSmith",

"data_id":"OSLogon"

}

3.7.3 Delete Login Sessions

For deleting login session use resource with URI

/logon/sessions/{logon_session_id}?endpoint_session_id={endpoint_session_id}

Advanced Authentication

Resource provided by HTTP DELETE and has these parameters.

Table 3-35

URI parameters for deleting login session.

URI parameter name

logon_session_id endpoint_session_id

Description

Logon session identifier, identifier of session for deleting.

Endpoint session identifier, identifier of endpoint session.

Method does not return any data, if the method was success method return HTTP 200 status.

Example

On the following example we will delete the logon session with identifier

“4Keuv7THWdSMR1H7mPc34O4mGoxTP0TP” with endpoint session identifier

“Ex3hqCoF5A2ARWGv221AmPtEkWQDUi0U”.

HTTP

DELETE https://authserver.example.com/api/v1/logon/sessions/

4Keuv7THWdSMR1H7mPc34O4mGoxTP0TP?endpoint_session_id=Ex3hqCoF5A2ARWGv221AmPtEkWQDU i0U

Response

HTTP 200

3.8 Working With Enrollment

3.8.1 About Enroll Process

The enrollment process collects information for creating of user templates. User templates can be created by several steps with the enroll process. The enroll process is wizard to user templates. Each user can create user templates into enroll process, administrator can assign enroll process results to another users. For starting the enrollment process the user should be authenticated in the

“TemplatesManagement” event. Enroll process can be described by the following chart; it has several steps for collection information from user and saving the user template.

API Documentation

Figure 3-4

Detailed enrollment process chart.

3.8.2 Start Enroll Process

For starting enroll process you should make request to create process to resource with URI:

/enroll

Resource provided by HTTP POST and accepted JSON object with this parameters:

Table 3-36

Parameters for starting enroll process.

Parameter name

login_session_id

Description

Advanced Authentication

Parameter name

method_id

Description

Authentication method identifier. Identifier of method form authentication methods list that supports by server.

Resource returns enroll process identifier, it is represented as JSON object with this parameter.

Table 3-37

JSON-object for started enroll process.

Parameter name

enroll_process_id

Description

Enroll process identifier, this identifier will be used in next enroll process step.

Example

On the following example user with login session identifier “Iz4awDMiRYcZh55SYt8awBz3Fcl1vikJ” starts the enroll process for the security question authentication method.

HTTP POST https://authserver.example.com/api/v1/enroll

Request

{

"method_id":"SECQUEST:1",

"login_session_id":"Iz4awDMiRYcZh55SYt8awBz3Fcl1vikJ"

}

Response

{

"enroll_process_id":"WqQd4TwxPCz7q1tAKrWGzCtajg7Iav14"

}

3.8.3 Providing Data Into Enroll Process

You should provide data into enroll process after this process is started. Resource for providing data has URI: enroll/{enroll_process_id}/do_enroll

Resource provided by HTTP POST and has this parameter.

Table 3-38

URI parameter for providing data into enroll process.

URI parameter

enroll_process_id

Description

Enroll process identifier, identifier of current enroll process. Start enroll process to get this identifier.

Resource accepts JSON object.

API Documentation

Table 3-39

Parameter for providing data into enroll process.

Parameter name

login_session_id response

Description

Object with specific data for method. Data varies for each authentication method.

Check method description for more information.

Resource returns the result for accepting the enroll data. Result can be different for each authentication method, for more information check description for authentication methods, but all responses contain some parameters which are the same for all authentication methods.

Table 3-40

JSON-object with result for accepting the enroll data.

Parameter name

method_id status msg reason

Description

Authentication method identifier. Identifier of method from authentication methods list that is supported by the server. This parameter shows which authentication method currently works with enroll data.

Current status of enroll process, see status description for more information.

Message from enroll process, this parameter is used for providing more information about enroll process.

The detailed status of the enrollment process, please check authentication method description for more information.

Enroll process has the following status

Table 3-41

Enroll process status.

Status name

MORE_DATA

FAILED

Description

This status indicates that the enroll process has collected all necessary data and you can create or update the user template.

This status indicates that enroll process is waiting for more data from user, you should provide specific data to enroll process, for more information about data see description of authentication methods.

This status indicate that the enroll process failed, for more information check message parameter from response. With this status you should start enroll process again.

Each enroll process is one or more steps for collecting all necessary data for the authentication method, each authentication method has a different number of steps and data, for more information see authentication method description.

Example

On the following example we provide data for security question authentication method, this method has two steps: first step is getting security question list from server, second step is providing answers for each security question. On example we have enroll process with identifier

Advanced Authentication

“WqQd4TwxPCz7q1tAKrWGzCtajg7Iav14”, user logged to “TemplatesManagement” application with session identifier “7Ge4BCGDLKPyG5b6Mp7PBcKUsQouhpdX”. On the first step, we will get security question list.

HTTP POST https://authserver.example.com/api/v1/enroll/WqQd4TwxPCz7q1tAKrWGzCtajg7Iav14/ do_enroll

Request

{

"response":{},

"login_session_id":"7Ge4BCGDLKPyG5b6Mp7PBcKUsQouhpdX"

}

Response

{

"questions":

{

"1":"What is your dog name?",

"0": "What is your favorite song?"

"method_id":"SECQUEST:1",

"msg":"Waiting for answers...",

"status":"MORE_DATA",

"reason":"SECQUEST_WAITING_ANSWERS"

}

We got question and servers change status to “MORE_DATA”, this means that the server is waiting for the answers to the questions. Now we will send answers, it will be the second step.

HTTP POST https://authserver.example.com/api/v1/enroll/WqQd4TwxPCz7q1tAKrWGzCtajg7Iav14/ do_enroll

Request

{

"response":

{

"answers":

{

"1":"Spotty",

"0":"Yesterday"

}

"login_session_id":"7Ge4BCGDLKPyG5b6Mp7PBcKUsQouhpdX"

}

Response

{

"method_id":"SECQUEST:1",

"status":"OK",

"msg":"",

"reason":""

}

After the second step server accepted our data and return status “OK” it means that enrollment was successful.

3.8.4 Delete Enroll Process

You can stop enroll process by resource with URI:

/enroll/{enroll_process_id}?login_session_id={login_session_id}

API Documentation

Resource provided by HTTP DELETE and has these URI parameters.

Table 3-42

URI parameters for stop enroll process.

URI parameter name

enroll_process_id login_session_id

Description

Enroll process identifier, identifier of enroll process, which will be stop.

This resource does not return any data, if deleting enroll session was successful method return HTTP

200 status.

Example

On the following example a user with login session, identifier

“4T1WEpCKumaIonjDBhoXbWkHhGg5Tk7Z” deletes enroll process with identifier

“AfAXRqxrI1K2jgeJzrarD0NxllhpY9UW”.

HTTP DELETE https://authserver.example.com/api/v1/enroll/

AfAXRqxrI1K2jgeJzrarD0NxllhpY9UW?login_session_id=4T1WEpCKumaIonjDBhoXbWkHhGg5Tk7Z

Response

HTTP 200

3.9 Working With User's Templates

3.9.1 About User's Templates

The user's templates contain authentication information associated with users. Each template is linked to a user and to an authentication method. When users try to logon using a specific authentication method, the server finds the associated user template and provide authentication.

Users cannot use authentication methods without associated user templates. The Enrollment

process creates user templates, check the

Working With Enrollment

chapter for more information.

Each authentication method stores different information in the templates. The Authentication method can update a user’s template in the authentication process, also users or administrator can change templates manually, a user can edit only his own templates.

The API provide resources for working with user’s templates: creating, updating, reading and deleting.

3.9.2 Get User's Templates

This resource provide reading user templates. Resource has URI:

/users/{user_id}/templates?login_session_id={login_session_id}

Resource provided by HTTP GET.

Advanced Authentication

Table 3-43

URI parameters for get user’s template.

URI parameter name

user_id login_session_id

Description

User identifier, this identifier will be used for getting associated user templates. Administrator can use any user identifier, user should use only his own identifier.

Login session identifier, user’s login session identifier used for checking user access. User should be logged to “TemplatesManagement” for getting access to user template.

Resource return list of user templates. List present as array of JSON object.

Table 3-44

JSON-object with user templates.

Parameter name

templates id method_id is_enrolled

Description

This parameter is used for wrapping array of JSON object with user templates.

Identifier of user template.

Identifier of authentication method

Boolean flag, when flag is true, then the template is enrolled and can be used for authentication, if flag is false, than the template is not enrolled and cannot be used for authentication.

Authentication method title

Comment for user template method_title comment

Example

On the following example a user with identifier “958ca11a7fa511e4b6ab00155d62a8b3” and session identifier “TBsifFiE4UJCyMnIyTkmY21kFctSxdwe” gets his own list of two user templates:

HTTP GET https://authserver.example.com/api/v1/users/958ca11a7fa511e4b6ab00155d62a8b3/ templates?login_session_id=TBsifFiE4UJCyMnIyTkmY21kFctSxdwe

Response

{

"templates":[

{

"id":"958ca11b7fa511e4a32200155d62a8b3",

"method_id":"LDAP_PASSWORD:1",

"is_enrolled":true,

"method_title":"LDAP password",

"comment": "LDAP password template"

{

"id":"959165a47fa511e4bd1500155d62a8b3",

]

}

"method_id":"HOTP:1",

"is_enrolled":true,

"method_title":"HOTP",

"comment": "OATH HTOP template"}

API Documentation

3.9.3 Create User's Templates From Enroll Session

After a successful enroll process, you can assign enrolled data to the user template. This is provided by resource with URI:

/users/{user_id}/templates

Resource provided by HTTP POST and has this parameter:

Table 3-45

URI parameter for assigning enrolled data.

URI parameter name

user_id

Description

User identifier, identifier user who will be assign to new template.

An administrator can assign enrolled data and create user templates for any user.

Resource accept JSON-object with these parameters:

Table 3-46

Parameters for assigning enrolled data.

URI parameter

enroll_process_id login_session_id

Description

Enroll process identifier, identifier of success enroll process, method will use data from this enroll process.

Comment for created user template.

comment

Resource return JSON-object with identifier of new user template.

Table 3-47

JSON-object for new user template.

Parameter name

auth_t_id

Description

Authentication template identifier, identifier of created user template

Example

On the following example, a user with identifier “e08c6b48810611e4b79300155d62a8b3” and login session identifier “33ebFAQBW1e1kTkKVzIRz5rf5dhv4OoE” creates a user template with enroll process identifier “nrXwfyy0l4QcXxYZNebzjs33rqS9UkG5”.

Advanced Authentication

HTTP POST https://authserver.example.com/api/v1/users/e08c6b48810611e4b79300155d62a8b3/ templates

Request

{

"enroll_process_id":"nrXwfyy0l4QcXxYZNebzjs33rqS9UkG5",

"comment":"Authentication template comment",

"login_session_id":"33ebFAQBW1e1kTkKVzIRz5rf5dhv4OoE"

}

Response

{

"auth_t_id":"9df84602842f11e4817e00155d62a8b3"

}

3.9.4 Assign User's Template To Another User

You can assign created user template to another user. This way a user can impersonate another user using his own authentication method. An example would be a user having 2 accounts, an admin account and a normal user account. He will only enroll authentication methods for his normal user account but will link his methods to his admin account. Now he can logon using the username of the admin account and the method of the normal account and this will be logged in the audit log.

Another use case would be group accounts where multiple users are linked too.

To link a template to another user use the resource with URI:

/users/{user_id}/templates

Resource provided by HTTP POST and has this parameter:

Table 3-48

URI parameter for assign user template to another user.

URI parameter name

user_id

Description

User identifier, identifier user who will be assign to template.

Resource accept JSON-object with these parameters:

Table 3-49

Parameters for assign user template to another user.

Parameter name

auth_t_id login_session_id

Description

Authentication user template identifier, identifier of user template which will be assign to another user.

Resource return JSON-object with identifier of user’s template.

Table 3-50

JSON-object for assigned template.

Parameter name

auth_t_id

Description

Authentication template identifier, identifier of user template

API Documentation

This resource just links the user template to another user, new user can’t modify template, user can only read assigned template.

Example

On the following example, user with login session “sC7PfOjvHt7OMgIccEHjK7b9XGlGNSoj” assign template with identifier “ba3cf01e845311e4841900155d62a8b3” to user with identifier

“76cc2a62845411e4bd6c00155d62a8b3”.

HTTP POST https://authserver.example.com/api/v1/users/76cc2a62845411e4bd6c00155d62a8b3/ templates

Request

{

"auth_t_id":"ba3cf01e845311e4841900155d62a8b3",

"login_session_id":"sC7PfOjvHt7OMgIccEHjK7b9XGlGNSoj"}

Response

{ "auth_t_id":"ba3cf01e845311e4841900155d62a8b3" }

3.9.5 Updating User's Template

You can update existing user template, this is provided by resource with URI:

/users/{user_id}/templates/{auth_template_id}

Resource provided by HTTP PUT and has this parameter:

Table 3-51

URI parameter for updating user template.

URI parameter name

user_id auth_template_id

Description

User identifier, identifier user which template will be update.

Authentication template identifier, identifier of template which will be update.

Administrator can update user template for all users, other users can update own templates.

Resource accept JSON-object with these parameters:

Table 3-52

Parameters for updating user template.

Parameter name

enroll_process_id login_session_id

Description

Enroll process identifier, identifier of success enroll process, method will use data from this enroll process for updating data in current user template.

New comment for user template.

comment

You can use one or both parameters for method, if you use enroll process identifier for method you will change user’s template authentication data. When an template is updated all linked users will need to use the updated template

Resource does not return data, if operation was success method returns HTTP 200 status.

Advanced Authentication

Example

On the following example, user with identifier “e08c6b48810611e4b79300155d62a8b3” update user template with identifier “ba3cf01e845311e4841900155d62a8b3” with new enrolled data form enroll process with identifier “l4rh0HvzJxNFBaO9d7PC4Uyq9YRc8EMY”.

HTTP PUT https://authserver.example.com/api/v1/users/e08c6b48810611e4b79300155d62a8b3/ templates/ba3cf01e845311e4841900155d62a8b3

Request

{

"enroll_process_id":"l4rh0HvzJxNFBaO9d7PC4Uyq9YRc8EMY",

"comment":"Updated comment",

"login_session_id":"86oe9ebDvJ08UJvlG0O14ZARm3wIYNTB"

}

Response

HTTP 200

3.9.6 Delete User's Template

This resource provide deleting of user templates. Resource has URI

/users/{user_id}/templates/{template_id}?login_session_id={login_session_id}

Resource providing by HTTP DELETE and has this parameters:

Table 3-53

URI parameters for deleting user template.

URI parameter name

user_id template_id login_session_id

Description

User identifier, identifier of user which template will be deleted.

Template identifier, identifier of template for deleting.

Login session identifier, user’s login session identifier used for checking user access. User should be logged to “TemplatesManagement” for getting access to user template deleting.

Administrator can delete any user templates, other users can delete only their own templates.

This method doesn’t return any data, if deleting was successful method returns HTTP 200 status, if an error occurs, method returns error description.

Example

On the following example, user with the user identifier “e08c6b48810611e4b79300155d62a8b3” and login session identifier “GsnGHDvqOiEdPR3KUhKqy2kZq7l4RCcC” tries to delete his own template with identifier “9df84602842f11e4817e00155d62a8b3”.

HTTP DELETE https://authserver.example.com/api/v1/users/e08c6b48810611e4b79300155d62a8b3/ templates/

9df84602842f11e4817e00155d62a8b3?login_session_id=GsnGHDvqOiEdPR3KUhKqy2kZq7l4RCcC

Response

HTTP 200

API Documentation

3.10 Working With Authentication Methods

The chapter will describe the authentication and the enrollment processes for each authentication method provided by appliance.

Before authentication, you should start a logon process and then provide data required by the authentication method. The data differs from method to method. For getting more information about

authentication process, please check the

Provide Authentication

chapter.

For the enrollment, you should be authenticated at the appliance and have a login session identifier, then you should start enrollment process and provide the enrollment data, the enrollment data is different from method to method. If a method has optional parameter and default value was not present in parameter’s description, that means – appliance will use default values from the authentication method’s policy. For more information about enrollment process, please check the

Working With Enrollment

chapter.

3.10.1 Card Authentication Method

The card authentication method provide users’ authentication by card. At the moment the method could work with the contactless cards (UID) and the certificate-based (PKI) cards. The card authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.

Authentication

For the authentication, you should create a logon process with the card authentication method or continue with the card authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with card’s data by POST request.

This authentication method supports 1:N logon and you could start a logon process without user name, you can define the card UID in unit_id parameter on a logon process creation. If you will use a chain with many authentication methods, you should get card identifier before you start 1:N logon process, and you should provide a card identifier at second time if your chain has the card authentication method. This method also work in non 1:N logon.

Table 3-54

The authentication data for the card authentication method

Parameter name

card_uid card_cert

Parameter value

The card's UID

The hex-string with certificate in DER format, optional parameter used for PKIbased smartcards

Resource will return a JSON-object with information about current state of the authentication.

Example

On the following example, the user JSmith from the COMPANY repository will try to authenticate with this own PKI-based smartcard, user already has an endpoint session with the identifier

“P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u”.

Advanced Authentication

HTTP POST https://authserver.example.com/api/v1/logon

Request

{

"method_id":"CARD:1",

"user_name":"COMPANY\\JSmith",

"event":"NAM",

"endpoint_session_id":"P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u"

}

Response

{

"current_method":"CARD:1",

"chains":[

{

"name":"Smartcard",

"methods":["CARD:1"],

"image_name":"default",

"apply_for_ep_owner":false,

"position": 0,

"is_enabled":true,

"is_trusted":true,

"short_name": ""

}],

"completed_methods":[],

"msg": "Process started",

"logon_process_id":"t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi",

"plugins":[],

"event_data_id":"OSLogon",

"event_name":"NAM",

"status":"MORE_DATA",

"reason":"PROCESS_STARTED"

}

HTTP POST https://authserver.example.com/api/v1/logon/t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi/ do_logon

Request

{

"response":

{

"card_uid":"0e00000000005c9e1e3a2d7532c30e00000046",

"card_cert":"3082070d308204f5a0030201020213460000000ec332752d3a1e9e5c00000000000e3

00d06092a864886f70d01010d0500304531133011060a0992268993f22c6401191603636f6d3118301

6060a0992268993f22c64011916086175746861736173311430120603550403130b617574686173617

32d6361301e170d3135303930383135353432365a170d3136303930373135353432365a30818131133

011060a0992268993f22c6401191603636f6d31183016060a0992268993f22c6401191608617574686

17361733111300f060355040b13084141415573657273311730150603550403130e446d69747279204

76f6c756265763124302206092a864886f70d010901161564676f6c756265764061757468617361732 e636f6d30819f300d06092a864886f70d010101050003818d0030818902818100df8ebdf44a7e6dd1e

4c64c2b2a96865c42410f73504f90b73836d31f4942beb44957af89d503f09c5c0fc9e3b44e96b3bd2 dbdd7235e63090e23051f657c575c18c22a3edebb3264b6d7cabc28eebc7227156c1b5c795c959587a

5a82afb22849125af3f2699030de7c2fe44cbb75097c2d123561360d9bc993073088db1b03d0203010

001a382033b30820337301706092b0601040182371402040a1e080055007300650072301d0603551d0 e041604144d18c67db47d1e4cd23f273864d8412d6f0493a9300e0603551d0f0101ff0404030205a03

01f0603551d230418301680148876d728949259f5462a224099af4cd41bc973523081fb0603551d1f0

481f33081f03081eda081eaa081e78681b26c6461703a2f2f2f434e3d61757468617361732d63612c4

34e3d4141415244532c434e3d4344502c434e3d5075626c69632532304b65792532305365727669636

5732c434e3d53657276696365732c434e3d436f6e66696775726174696f6e2c44433d6175746861736

1732c44433d636f6d3f63657274696669636174655265766f636174696f6e4c6973743f626173653f6 f626a656374436c6173733d63524c446973747269627574696f6e506f696e748630687474703a2f2f6

465762e61757468617361732e636f6d2f43657274446174612f61757468617361732d63612e63726c3

API Documentation

082011206082b0601050507010104820104308201003081ab06082b0601050507300286819e6c64617

03a2f2f2f434e3d61757468617361732d63612c434e3d4149412c434e3d5075626c69632532304b657

925323053657276696365732c434e3d53657276696365732c434e3d436f6e66696775726174696f6e2 c44433d61757468617361732c44433d636f6d3f634143657274696669636174653f626173653f6f626 a656374436c6173733d63657274696669636174696f6e417574686f72697479305006082b060105050

730028644687474703a2f2f6465762e61757468617361732e636f6d2f43657274446174612f4141415

244532e61757468617361732e636f6d5f61757468617361732d63612e63727430290603551d2504223

020060a2b0601040182370a030406082b0601050507030406082b0601050507030230470603551d110

440303ea025060a2b060104018237140203a0170c1564676f6c756265764061757468617361732e636 f6d811564676f6c756265764061757468617361732e636f6d304406092a864886f70d01090f0437303

5300e06082a864886f70d030202020080300e06082a864886f70d030402020080300706052b0e03020

7300a06082a864886f70d0307300d06092a864886f70d01010d0500038202010056fd6f97f650c150f

3116a838f1ccf6856532e4dfe8d60a662804d120fe6ae116ed8ce76445da7375f75b6ee7827a6d5f33

011401edbda3262b6689fdda820ee66b5c3c0584424b249716682c45a4ffd6ff34e650f52061e59527 ea44fe624e86057a384f70d7393af19ec282435d3859fbe60c2ed4114df963a92e4df97e906da74ff6

082edfca0ae18b6610915890c4983d84f49ddc899ed2e46f007841d88f775236dc3b7ff0d0de3ddc98

0ebc0cf2cb5cf80b59f8d409d4a3d161704db4a2a6a69a15ef953564c24fea005b68a59056abf5dd33

4b50375e17c84f9bf8f6e81428d50f6b63c0d101f433412871142de893376103c277a0f1b4c68c3ae0

87fcbff3c1feed85289f156c6c092176a885fce5320d14cee1b696a1d65fc6b0a84b4bb068fc93388a

173824f2c6f9af0fb509670405d56e4ecfbace31f4095bc63d0c13df1487eb60ebd3276014374e35d6 be4b0e8149e7495cefb8a9b0e1425226211e676882b48893aec8b24895e6b2f96f8bf34ca715df0435 e94a3562940c08cfedf2ac2a966cdd104197fc37391d0fa9d5cacd39931d1b55641d58e2dde8029b36

3c7d494cb9d88c4d55ee408954752f112095a3f04adc6cfd9fdb7fa23e9d33d3d1c84e539b93fa3939 daa696a70da203307de5923156380c9a827c1d63ca4ca9d0114fa243fe48d6a13b9b50555fd1dcba27

3327398e9f665a945a73559"

"endpoint_session_id":"P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u"

}

Response

{

"event_data_id":"OSLogon",

"user_mobile_phone":"+16086783619",

"msg":"Welcome!",

"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",

"data_id":"OSLogon",

"user_email":"[email protected]",

"repo_id":"d3fba00652d211e5a19a000c2951aca4",

"chains":[

{

"name":"Smartcard",

"methods":["CARD:1"],

"image_name":"default",

"apply_for_ep_owner":false,

"position": 0,

"is_enabled":true,

"is_trusted":true,

"short_name": ""

}],

"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",

"user_cn":"JSmith",

Advanced Authentication

"completed_methods":["CARD:1"],

"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",

"logon_process_id":"t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi ",

"current_method":"CARD:1",

"user_name":"COMPANY\\JSmith",

"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",

"login_session_id":"DirIO8s41TbT1lm7Dh5BNfK6gRTHhXTl",

"event_name":"NAM",

"status":"OK",

"user_name_netbios":"COMPANY\\JSmith",

"plugins":["LdapRules"],

"user_id":"ab2b845652d311e5a19a000c2951aca4",

"reason": "CHAIN_COMPLETED"

}

Enrollment

For the enrollment, the card authentication method you should start an enrollment process and provide an enrollment data as a JSON container.

Table 3-55

The enrollment data for the card authentication method

Parameter name

card_uid card_cert

Parameter value

The card's UID

The hex-string with certificate in DER format, optional parameter used for PKIbased smartcards

Resource will return a JSON object with status of the enrollment process.

Example

On the following example, the user JSmith from the COMPANY repository will try to enroll the smartcard authentication method for PKI-based smartcard, user has a login session with the identifier

“mDclxFuBrCNAHddXazdAeu06bsxlyfqY”.

HTTP POST https://authserver.example.com/api/v1/enroll

Request

{

"method_id":"CARD:1",

"login_session_id":"mDclxFuBrCNAHddXazdAeu06bsxlyfqY"

}

Response

{

"enroll_process_id":"23AEHu4uoISJBZ3KEjUo3Y7s2MN7MQe2"

}

HTTP POST https://authserver.example.com/api/v1/enroll/23AEHu4uoISJBZ3KEjUo3Y7s2MN7MQe2 / do_enroll