privacyIDEA REST API

privacyIDEA provides a great and simple REST API which lets you automate and integrate all tasks into other workflows. In fact the privacyIDEA Web UI as a single page application uses this REST API. Thus you could easily open the developer tools of your browser and monitor the HTTP requests that are sent.

Authenticating a user

A user needs to authenticate at the Web UI and also at the REST API. This is done by issuing the request

POST /auth

The auth request takes the username and the users password. Which password the user needs to provide, depends on the login_mode policy in the WebUI scope. The auth request returns an authorization token which needs to be added to each subsequent request.

You can also issue a test request using httpie from the command line like this:

% http --verify no --pretty all --json POST https://localhost/auth username=secureuser password=test
/usr/lib/python2.7/dist-packages/urllib3/connectionpool.py:794: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.org/en/latest/security.html
 InsecureRequestWarning)
HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 843
Content-Type: application/json
Date: Tue, 01 Nov 2016 07:28:55 GMT
Server: nginx/1.10.0 (Ubuntu)

{
 "id": 1, 
 "jsonrpc": "2.0", 
 "result": {
 "status": true, 
 "value": {
 "default_tokentype": "totp", 
 "log_level": 30, 
 "logout_time": 120, 
 "menus": [], 
 "policy_template_url": "https://raw.githubusercontent.com/privacyidea/policy-templates/master/templates/", 
 "realm": "secure", 
 "rights": [], 
 "role": "user", 
 "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InNlY3VyZXVzZXIiLCJub25jZSI6IjQyYjhhMWIzNDEzYTA5ZmQzMDljMDI3NzY3Mjc4N2I5MmFiNWI2ZWUiLCJhdXRodHlwZSI6InBhc3N3b3JkIiwicmVhbG0iOiJzZWN1cmUiLCJyaWdodHMiOltdLCJyb2xlIjoidXNlciIsImV4cCI6MTQ3Nzk4ODkzNX0.vCXNNV4Bmt2UuC0FMuc2qMbr8i_8zweROadvfLYcJzU", 
 "token_page_size": 15, 
 "token_wizard": false, 
 "token_wizard_2nd": false, 
 "user_details": false, 
 "user_page_size": 15, 
 "username": "secureuser"
 }
 }, 
 "time": 1477985335.376939, 
 "version": "privacyIDEA 2.16.dev3", 
 "versionnumber": "2.16.dev3"
}

Using the authorization token

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InNlY3VyZXVzZXIiLCJub25jZSI6IjQyYjhhMWIzNDEzYTA5ZmQzMDljMDI3NzY3Mjc4N2I5MmFiNWI2ZWUiLCJhdXRodHlwZSI6InBhc3N3b3JkIiwicmVhbG0iOiJzZWN1cmUiLCJyaWdodHMiOltdLCJyb2xlIjoidXNlciIsImV4cCI6MTQ3Nzk4ODkzNX0.vCXNNV4Bmt2UuC0FMuc2qMbr8i_8zweROadvfLYcJzU

for subsequent call.

Enrolling a token

Now the user can enroll a token using the token endpoints. You need to issue a /token/init request.

To enroll an TOTP token the user would have to issue such a request:

http --verify no --pretty all --json POST https://localhost/token/init \
     PI-Authorization:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InNlY3VyZXVzZXIiLCJub25jZSI6IjQyYjhhMWIzNDEzYTA5ZmQzMDljMDI3NzY3Mjc4N2I5MmFiNWI2ZWUiLCJhdXRodHlwZSI6InBhc3N3b3JkIiwicmVhbG0iOiJzZWN1cmUiLCJyaWdodHMiOltdLCJyb2xlIjoidXNlciIsImV4cCI6MTQ3Nzk4ODkzNX0.vCXNNV4Bmt2UuC0FMuc2qMbr8i_8zweROadvfLYcJzU \
     type=totp genkey=1 otplen=6

The secret and also the image of the QR code to be scanned with a smartphone app is contained in the response:

 "googleurl": {
 "description": "URL for google Authenticator", 
 "img": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAeoAAAHqAQAAAADjFjCXAAAD90lEQVR4nO2dTY6jSBBGXwxItQSpD+Cj4JuN6khzAziKbwBLS6CYRWaQ6epZGUaW218sEJR5SqUUiv+kzDkg019HaBAuXLhw4cKFCxd+Lm5ZWuzKZkw9MKVHsOtS7uLV63mrC/80HHd3Z3B397lx9xmgc2fwNd/Rxd0wN14R41vvXfir8SWbL7t2Kz4CTH3jDDczoHGGeTMAzKw9eXXhn4W3P559MrDh1q4M49Y6rC3DCA6Nw3Lq6sKFAzDMjee4rm/crkuLf/cAi9n/vrrwj8I7dx8JD+t+txzh7c41KSHg7uvJqwv/SHwyM7MeYGmx6/KVzBxAfvx7BmBLKeypqwv/MDwpVmmL+XTJhsxZNvPpsuKwpkfoHjtob7134a/Co3ISRZNUFxkBH2myig0zJIc7+Ir73KhyIvwMfDOzy4pdSSbNk66N3Yp/X1ZySWX5cqZ+k4cVfkCictKtLcM/X85kjdtwM5zubs7y5ZZeW3qM7m4++BbYW+9d+Kvw7GEh27XsTZObbTzZurHbXwEgpbnysMKflRLIAdERG2bIHTEeumSlVaa4TvjzEtkElGZsJBeNl/ShqKMXkdYJfx7374t71X2YerArAMuXA1tqxuYGrfqwwo9JMVwM1SVGAKqSyhxhXlVheeu9C38V/pA5QK7I5fQh+9pcQ2FXPVSvE35IstZ1/ptUypWS26yYOcyT1gl/WrL+zECaZeo8HGlys8XDQsk1ZOuEH5Bi61Idboy54VC9ukFWzJy0TvgBiSrx7j4jrsuXsH/p5fyoep3wQ1JZsxLN7XoVZeH9h4j1pHXCD0j4y1wRybLnsLA7170jIQ8r/Bj+0Gno9kkTGi9tsTrh6B7t31vvXfir8Lpysg/UVWU5Qv8i4Nt7s9I64U9LZBNF/1bKVEnKZpNznR9eka0T/rwU9xljTLuvjZmT/N4M+Tw26ogJPyRVbpD1L8py46P+7YlsXch7670LfxX+4EjnaLf+R4RXXdyldcIPSVYf4pzr8Gjr9kDuR29CWif8gFS2rrT7PSadqiGn6qJZYuEn4O63Frt2ax7ZzHObUTnJh8I2g+5umuoUfl4fNs8yVVavLtDlBhmgcxPCD+LV2X+HNX/Oaf9byGbO8mtlGMGmfo4f33rvwl+Ll291Ml3u9WfqhqpLAbC0MNzkYYWfgA+lVBzHc1JZeOqhfDAxVYmn/uTVhX8Y/nAyMc7j1DMnUTQpbYmCKa4Tfh4eZ1/zecQ8bjdDjKU0iuuEH5Eftq7MDVcTxOkzieWT2MphhR+Tug9bHfFv6t7sGKNN0TnTpJPwQxL1OmAvC5ejiOzzdWHhVnRGTPhB3PTf64QLFy5cuHDhwv8I/F/uK4F3xSCgRwAAAABJRU5ErkJggg==", 
 "value": "otpauth://totp/TOTP0008C54E?secret=ND2QFT6LIMFXCEARWIMTBT456NY6K7H5&counter=1&digits=6&issuer=privacyIDEA"
 },

In the same way you could let the user manage his tokens, delete them, reset PINs etc…

For more information see the complete REST API documentation.

This is a cheap way to establish two-factor authentication with something you know and something you have.

Several attack vectors for Two-Factor Authentication with SMS OTP

But lateley there are again some news about the vularability of OTP values sent via SMS. There are different attack vectors. In one scenario the attacker can reroute or “steal” the SIM card by doing social engineering at the telephone provider. In another scenario a malicious software is installed on the smartphone, that can sniff the OTP value.

Yes, privacyIDEA also supports sending OTP values via SMS and privacyIDEA is also vulnarable to these attacks – since it is the basic concept that lacks the necessary security.

Security is shades of grey — or white

But you might have heard that “there is no 100% security”. And that “security is a process”. And now I add to these idioms “Security is Shades of Grey”.

You gain security by using a password on your account to lock the desktop. But are you secure? You gain further security by adding a second factor during authentication. But is your data secure, now? You gain further security by encrypting the harddisk (a.k.a. your data) of your desktop. But is it secure?

Yes, it is good to use a password. You should not use none.

And yes, it is goot to use SMS OTP. It is better than to not use it. In certain cases it might be OK to use SMS OTP being aware of the possible risks.

But there are further steps or other possiblities to increase security.

Choice of Security Level

With privacyIDEA you have the choice, which security level you are going to use. And this may even depend on the application and the client.

You may use SMS OTP, Email OTP, Smartphone Apps like the Google Authenticator, hardware key fobs and seedable tokens like the Yubikey. Using privacyIDEA’s policy definitions, you can define which token type is allowed to be used for authentication at which application. This way you can accept the risk of using e.g. SMS OTP for low security applications and hardware devices like the yubikey for applications requiring higher confidentiality.

See the online documentation on policies for more information or come to the Google Group mailing list.

If you require any professional assistance you may contact the maintainer of privacyIDEA.

I am really puzzled and scared by many modern “security” consultants who claim the smartphone to be the next security device or even my identification object. Knowing that

• the smartphone has more cores than most desktop computers,
• is connected faster to the internet (thanks to LTE) than most land line bound computers
• and most older smartphones get no software updates fixing security issues,

this is a really scary scenario.

And the scariest thing of all is, that most users are not aware of this and are installing third party applications (belittling it as “App”) by a blink of an eye or the touch of a finger tip. Waving through all rights and access grants such an “App” wants to get.

Knowing this I am getting sick reading sentences like that on a daily basis:

We can achieve the same level of security as from a physical token using a simple app and a public algorithm to generate Time-based One-Time Passwords (TOTP), for example.

http://www.businesscomputingworld.co.uk/the-end-of-the-password-as-we-know-it/

This in fact is not true. A hardware token has NOT far as many attack vectors like a smartphone, from which you can steal the secret key, that is used to calculate the OTP values. TOTP (RFC6238) is based on HOTP (RFC4226) which relies on a secret shared key. This secret key is used to generate the OTP value. If the secret key is stolen from the smartphone either by

• physical access to the smartphone or
• by remote access via a trojan

the key is also known to the attacker.

And now comes the nasty part with TOTP: As TOTP only relies on the secret key and the time (which is known to everyone), an attacker can impersonate the user WITHOUT him NOTICING it. The OTP value an attacker generates will be a valid OTP value. The OTP value, the user generates a few minutes later, will also be a valid OTP value. The user will only experience a small “hickup” if he would try to authenticate within 29 seconds after the attacker did. Would the user care? Or would he just try a second time?

Don’t get me wrong. The smartphone with a Google Authenticator or FreeOTP is a great device to increase security in an easy and CHEAP! way. But it has those problems a hardware token does not.

A preseeded hardware token of course has the problem, that the secret key was installed at the vendors site and I do not ask you to trust the vendor.

But there are also hardware tokens that you can initialize yourself. Then you are the only one who knows the secret key and the secret key can not get extracted from the hardware remotely.

So it is important to know what you are doing and decide which level of security you want to achieve. But it is a sham telling that a smartphone will get you the same level of security as a hardware token does!

Luckily you can choose what level of security you want to achieve, when using privacyIDEA.

Today I will show you, how you can setup a scenario, where users can authenticate with Yubikey and/or Google Authenticator and you can define centrally, for which server the users need a Yubikey to authenticate and for which other server a Google Authenticator would be sufficient. Thus you can enforce security levels, meaning servers carrying more sensitive data can only be accessed with a hardware device like the Yubikey while others are ok to be accessed with a software token like the Google Authenticator.

Unique user, two tokens, many machines

You should already have read about enrolling yubikeys and how to use privacyIDEA for  two factor authentication to your server farm. So I assume, that you have a running installation.

You should have enrolled two tokens to the user root as depicted below:

The user root has a Google Authenticator (serial OATH…, OTP PIN “google”) and a Yubikey (serial UBOM…, OTP PIN “yubi”) token.

Both tokens can be used to authenticate from all configured clients. From localhost (172.16.200.41):

[root@centos6 ~]# echo "User-Name=root, Password=google977398" | radclient -sx localhost auth testing123
Sending Access-Request of id 167 to 127.0.0.1 port 1812
 User-Name = "root"
 Password = "google977398"
rad_recv: Access-Accept packet from host 127.0.0.1 port 1812, id=167, length=48
 Reply-Message = "privacyIDEA access granted"
Total approved auths: 1
 Total denied auths: 0
 Total lost auths: 0

[root@centos6 ~]# echo "User-Name=root, Password=yubi899739" | radclient -sx localhost auth testing123
Sending Access-Request of id 100 to 127.0.0.1 port 1812
 User-Name = "root"
 Password = "yubi899739"
rad_recv: Access-Accept packet from host 127.0.0.1 port 1812, id=100, length=48
 Reply-Message = "privacyIDEA access granted"
Total approved auths: 1
 Total denied auths: 0
 Total lost auths: 0

Or from a remote host (172.16.200.106):

cornelius@puckel ~ % echo "User-Name=root, Password=google308786" | radclient -sx 172.16.200.41 auth testing123
Sending Access-Request of id 11 to 172.16.200.41 port 1812
    User-Name = "root"
    Password = "google308786"
rad_recv: Access-Accept packet from host 172.16.200.41 port 1812, id=11, length=48
    Reply-Message = "privacyIDEA access granted"

       Total approved auths:  1
       Total denied auths:  0
       Total lost auths:  0

cornelius@puckel ~ % echo "User-Name=root, Password=yubi867011" | radclient -sx 172.16.200.41 auth testing123
Sending Access-Request of id 47 to 172.16.200.41 port 1812
    User-Name = "root"
    Password = "yubi867011"
rad_recv: Access-Accept packet from host 172.16.200.41 port 1812, id=47, length=48
    Reply-Message = "privacyIDEA access granted"

       Total approved auths:  1
       Total denied auths:  0
       Total lost auths:  0

The idea

The idea is to allow access on the machine 172.16.200.106 only with yubikeys. This is the machine that carries tons of sensitive data and we do not want users to authenticate with their Google Authenticator.

The host with the higher security level

To accomplish this privacyIDEA provides a special authorization policy that will only grant access, if the the authentication was performed with the correct token.

So lets configure a policy:

This policy tells the system, that if the client 172.16.200.106 issues an authentication request, it should only be approved, if the serial number of the authenticating token contains the string “UBOM”.

Note: As we are using RADIUS the client 172.16.200.106 issues a radius request to the RADIUS server 172.16.200.41 and the RADIUS server issues the request to the privacyIDEA server 172.16.200.41/127.0.01. Thus the request that arrives at the privacyIDEA server will always be issued by the RADIUS server. So we need to allow the RADIUS server to overwrite the client information – thus the RADIUS server will tell the privacyIDEA server, what the calling RADIUS client was.

We can set this in the system config.

We set the localhost and the eth0 IP of the RADIUS server in a comma seperated list: 127.0.0.1, 172.16.200.41.

The yubikey now can successfully authenticate at the sensitive host:

cornelius@puckel ~ % echo "User-Name=root, Password=yubi773998" | radclient -sx 172.16.200.41 auth testing123
Sending Access-Request of id 88 to 172.16.200.41 port 1812
 User-Name = "root"
 Password = "yubi773998"
rad_recv: Access-Accept packet from host 172.16.200.41 port 1812, id=88, length=48
 Reply-Message = "privacyIDEA access granted"
 Total approved auths: 1
 Total denied auths: 0
 Total lost auths: 0

while the Google Authenticator fails to do so:

cornelius@puckel ~ % echo "User-Name=root, Password=google850707" | radclient -sx 172.16.200.41 auth testing123
Sending Access-Request of id 24 to 172.16.200.41 port 1812
 User-Name = "root"
 Password = "google850707"
rad_recv: Access-Reject packet from host 172.16.200.41 port 1812, id=24, length=55
 Reply-Message = "privacyIDEA server denied access!"
 Total approved auths: 0
 Total denied auths: 1
 Total lost auths: 0

We can see this in the privacyIDEA audit log:

Google Authenticator is still good for default servers

But we can still use the Google Authenticator for the default server with lower security level:

[root@centos6 ~]# echo "User-Name=root, Password=google069728" | radclient -sx 172.16.200.41 auth testing123
Sending Access-Request of id 162 to 172.16.200.41 port 1812
    User-Name = "root"
    Password = "google069728"
rad_recv: Access-Accept packet from host 172.16.200.41 port 1812, id=162, length=48
    Reply-Message = "privacyIDEA access granted"

       Total approved auths:  1
         Total denied auths:  0
           Total lost auths:  0

We can check this in the audit log, again:

Conclusion

privacyIDEA can be used to enroll many different authenticators to your users and mange these devices centrally.

In a second step you can decide who authenticates where with which device without bothering to reenroll any device.

Thus you can enforce your security policies easily. Additionally the audit log keeps track of all events that do not comply to your security policy.