Sometimes it is important to add user self service functionalities to your own portal or create a stripped down version of the privacyIDEA user selfservice. You can strip down the rights for users in a very detailed manner using policies. You can also define an enrollment wizard policy, so that enrolling tokens gets even more simpler. But sometimes even this is not enough.
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.
