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.
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.
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 |
Parameter value |
|---|---|
|
card_uid |
The card's UID |
|
card_cert |
The hex-string with certificate in DER format, optional parameter used for PKI-based smartcards |
Resource will return a JSON-object with information about current state of the authentication.
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”.
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":"3082070d308204f5a0030201020213460000000ec332752d3a1e9e5c00000000000e300d06092a864886f70d01010d0500304531133011060a0992268993f22c6401191603636f6d31183016060a0992268993f22c64011916086175746861736173311430120603550403130b61757468617361732d6361301e170d3135303930383135353432365a170d3136303930373135353432365a30818131133011060a0992268993f22c6401191603636f6d31183016060a0992268993f22c640119160861757468617361733111300f060355040b13084141415573657273311730150603550403130e446d6974727920476f6c756265763124302206092a864886f70d010901161564676f6c756265764061757468617361732e636f6d30819f300d06092a864886f70d010101050003818d0030818902818100df8ebdf44a7e6dd1e4c64c2b2a96865c42410f73504f90b73836d31f4942beb44957af89d503f09c5c0fc9e3b44e96b3bd2dbdd7235e63090e23051f657c575c18c22a3edebb3264b6d7cabc28eebc7227156c1b5c795c959587a5a82afb22849125af3f2699030de7c2fe44cbb75097c2d123561360d9bc993073088db1b03d0203010001a382033b30820337301706092b0601040182371402040a1e080055007300650072301d0603551d0e041604144d18c67db47d1e4cd23f273864d8412d6f0493a9300e0603551d0f0101ff0404030205a0301f0603551d230418301680148876d728949259f5462a224099af4cd41bc973523081fb0603551d1f0481f33081f03081eda081eaa081e78681b26c6461703a2f2f2f434e3d61757468617361732d63612c434e3d4141415244532c434e3d4344502c434e3d5075626c69632532304b657925323053657276696365732c434e3d53657276696365732c434e3d436f6e66696775726174696f6e2c44433d61757468617361732c44433d636f6d3f63657274696669636174655265766f636174696f6e4c6973743f626173653f6f626a656374436c6173733d63524c446973747269627574696f6e506f696e748630687474703a2f2f6465762e61757468617361732e636f6d2f43657274446174612f61757468617361732d63612e63726c3082011206082b0601050507010104820104308201003081ab06082b0601050507300286819e6c6461703a2f2f2f434e3d61757468617361732d63612c434e3d4149412c434e3d5075626c69632532304b657925323053657276696365732c434e3d53657276696365732c434e3d436f6e66696775726174696f6e2c44433d61757468617361732c44433d636f6d3f634143657274696669636174653f626173653f6f626a656374436c6173733d63657274696669636174696f6e417574686f72697479305006082b060105050730028644687474703a2f2f6465762e61757468617361732e636f6d2f43657274446174612f4141415244532e61757468617361732e636f6d5f61757468617361732d63612e63727430290603551d2504223020060a2b0601040182370a030406082b0601050507030406082b0601050507030230470603551d110440303ea025060a2b060104018237140203a0170c1564676f6c756265764061757468617361732e636f6d811564676f6c756265764061757468617361732e636f6d304406092a864886f70d01090f04373035300e06082a864886f70d030202020080300e06082a864886f70d030402020080300706052b0e030207300a06082a864886f70d0307300d06092a864886f70d01010d0500038202010056fd6f97f650c150f3116a838f1ccf6856532e4dfe8d60a662804d120fe6ae116ed8ce76445da7375f75b6ee7827a6d5f33011401edbda3262b6689fdda820ee66b5c3c0584424b249716682c45a4ffd6ff34e650f52061e59527ea44fe624e86057a384f70d7393af19ec282435d3859fbe60c2ed4114df963a92e4df97e906da74ff6082edfca0ae18b6610915890c4983d84f49ddc899ed2e46f007841d88f775236dc3b7ff0d0de3ddc980ebc0cf2cb5cf80b59f8d409d4a3d161704db4a2a6a69a15ef953564c24fea005b68a59056abf5dd334b50375e17c84f9bf8f6e81428d50f6b63c0d101f433412871142de893376103c277a0f1b4c68c3ae087fcbff3c1feed85289f156c6c092176a885fce5320d14cee1b696a1d65fc6b0a84b4bb068fc93388a173824f2c6f9af0fb509670405d56e4ecfbace31f4095bc63d0c13df1487eb60ebd3276014374e35d6be4b0e8149e7495cefb8a9b0e1425226211e676882b48893aec8b24895e6b2f96f8bf34ca715df0435e94a3562940c08cfedf2ac2a966cdd104197fc37391d0fa9d5cacd39931d1b55641d58e2dde8029b363c7d494cb9d88c4d55ee408954752f112095a3f04adc6cfd9fdb7fa23e9d33d3d1c84e539b93fa3939daa696a70da203307de5923156380c9a827c1d63ca4ca9d0114fa243fe48d6a13b9b50555fd1dcba273327398e9f665a945a73559"
},
"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":"jsmith@company.com",
"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",
"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"
}
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 |
Parameter value |
|---|---|
|
card_uid |
The card's UID |
|
card_cert |
The hex-string with certificate in DER format, optional parameter used for PKI-based smartcards |
Resource will return a JSON object with status of the enrollment process.
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
Request
{
"response":
{
"card_uid":"0e00000000005c9e1e3a2d7532c30e00000046",
"card_cert":"3082070d308204f5a0030201020213460000000ec332752d3a1e9e5c00000000000e300d06092a864886f70d01010d0500304531133011060a0992268993f22c6401191603636f6d31183016060a0992268993f22c64011916086175746861736173311430120603550403130b61757468617361732d6361301e170d3135303930383135353432365a170d3136303930373135353432365a30818131133011060a0992268993f22c6401191603636f6d31183016060a0992268993f22c640119160861757468617361733111300f060355040b13084141415573657273311730150603550403130e446d6974727920476f6c756265763124302206092a864886f70d010901161564676f6c756265764061757468617361732e636f6d30819f300d06092a864886f70d010101050003818d0030818902818100df8ebdf44a7e6dd1e4c64c2b2a96865c42410f73504f90b73836d31f4942beb44957af89d503f09c5c0fc9e3b44e96b3bd2dbdd7235e63090e23051f657c575c18c22a3edebb3264b6d7cabc28eebc7227156c1b5c795c959587a5a82afb22849125af3f2699030de7c2fe44cbb75097c2d123561360d9bc993073088db1b03d0203010001a382033b30820337301706092b0601040182371402040a1e080055007300650072301d0603551d0e041604144d18c67db47d1e4cd23f273864d8412d6f0493a9300e0603551d0f0101ff0404030205a0301f0603551d230418301680148876d728949259f5462a224099af4cd41bc973523081fb0603551d1f0481f33081f03081eda081eaa081e78681b26c6461703a2f2f2f434e3d61757468617361732d63612c434e3d4141415244532c434e3d4344502c434e3d5075626c69632532304b657925323053657276696365732c434e3d53657276696365732c434e3d436f6e66696775726174696f6e2c44433d61757468617361732c44433d636f6d3f63657274696669636174655265766f636174696f6e4c6973743f626173653f6f626a656374436c6173733d63524c446973747269627574696f6e506f696e748630687474703a2f2f6465762e61757468617361732e636f6d2f43657274446174612f61757468617361732d63612e63726c3082011206082b0601050507010104820104308201003081ab06082b0601050507300286819e6c6461703a2f2f2f434e3d61757468617361732d63612c434e3d4149412c434e3d5075626c69632532304b657925323053657276696365732c434e3d53657276696365732c434e3d436f6e66696775726174696f6e2c44433d61757468617361732c44433d636f6d3f634143657274696669636174653f626173653f6f626a656374436c6173733d63657274696669636174696f6e417574686f72697479305006082b060105050730028644687474703a2f2f6465762e61757468617361732e636f6d2f43657274446174612f4141415244532e61757468617361732e636f6d5f61757468617361732d63612e63727430290603551d2504223020060a2b0601040182370a030406082b0601050507030406082b0601050507030230470603551d110440303ea025060a2b060104018237140203a0170c1564676f6c756265764061757468617361732e636f6d811564676f6c756265764061757468617361732e636f6d304406092a864886f70d01090f04373035300e06082a864886f70d030202020080300e06082a864886f70d030402020080300706052b0e030207300a06082a864886f70d0307300d06092a864886f70d01010d0500038202010056fd6f97f650c150f3116a838f1ccf6856532e4dfe8d60a662804d120fe6ae116ed8ce76445da7375f75b6ee7827a6d5f33011401edbda3262b6689fdda820ee66b5c3c0584424b249716682c45a4ffd6ff34e650f52061e59527ea44fe624e86057a384f70d7393af19ec282435d3859fbe60c2ed4114df963a92e4df97e906da74ff6082edfca0ae18b6610915890c4983d84f49ddc899ed2e46f007841d88f775236dc3b7ff0d0de3ddc980ebc0cf2cb5cf80b59f8d409d4a3d161704db4a2a6a69a15ef953564c24fea005b68a59056abf5dd334b50375e17c84f9bf8f6e81428d50f6b63c0d101f433412871142de893376103c277a0f1b4c68c3ae087fcbff3c1feed85289f156c6c092176a885fce5320d14cee1b696a1d65fc6b0a84b4bb068fc93388a173824f2c6f9af0fb509670405d56e4ecfbace31f4095bc63d0c13df1487eb60ebd3276014374e35d6be4b0e8149e7495cefb8a9b0e1425226211e676882b48893aec8b24895e6b2f96f8bf34ca715df0435e94a3562940c08cfedf2ac2a966cdd104197fc37391d0fa9d5cacd39931d1b55641d58e2dde8029b363c7d494cb9d88c4d55ee408954752f112095a3f04adc6cfd9fdb7fa23e9d33d3d1c84e539b93fa3939daa696a70da203307de5923156380c9a827c1d63ca4ca9d0114fa243fe48d6a13b9b50555fd1dcba273327398e9f665a945a73559"
},
"login_session_id":"mDclxFuBrCNAHddXazdAeu06bsxlyfqY"
}
Response
{
"reason":"",
"msg":"",
"status":"OK",
"method_id":"CARD:1"
}
The email one-time password authentication method provide authentication by one-time password that will send to user’s email. The appliance use an email address from LDAP repository, if user have not email address in repository, he could not use this authentication method. The email one-time password authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the email one-time password authentication method or continue with the email one-time password authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with user’s one-time password by POST request. This method have two step for authentication, on first step you should send empty data for sending email with one-time password to user, on second step you should provide one-time password.
Table 3-56 The authentication data for the email authentication method
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain user’s one-time password |
Resource will return a JSON-object with information about current state of the authentication.
The email one-time password authentication method supports the list of the authentication reasons.
Table 3-57 The email method’s authentication reasons
|
Reason value |
Description |
|---|---|
|
OTP_CANNOT_SEND |
The appliance cannot send by email one-time password |
|
OTP_TOO_MANY_SENT |
The appliance was sent too many one-time passwords |
|
OTP_WAITING_PASSWORD |
The authentication method waiting for one-time password |
|
OTP_NO_PASSWORD |
The password provided for the authentication was empty |
|
OTP_PASSWORD_EXPIRED |
The one-time password was expired |
|
OTP_WRONG_PASSWORD |
The one-time password was wrong |
|
OTP_TOO_MANY_REQUESTS |
The appliance got too many requests |
On the following example, the user JSmith from the COMPANY repository will try to authenticate by the email one-time password authentication method, user already has an endpoint session with the identifier “P1npGvMizbs4HiFsiLX5h3FquTB5tfJj”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"EMAIL_OTP:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"P1npGvMizbs4HiFsiLX5h3FquTB5tfJj"
}
Response
{
"reason":"PROCESS_STARTED",
"current_method":"EMAIL_OTP:1",
"msg":"Process started",
"chains":[
{
"is_trusted":true,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["EMAIL_OTP:1"],
"name":"Email",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"Imyr6xEyKTsVCuvj0s2dRz6j6rtCqfFK",
"completed_methods":[],
"event_name":"NAM"
}
HTTP POST
https://authserver.example.com/api/v1/logon/Imyr6xEyKTsVCuvj0s2dRz6j6rtCqfFK/do_logon
Request
{
"response":{},
"endpoint_session_id":"P1npGvMizbs4HiFsiLX5h3FquTB5tfJj"
}
Response
{
"reason":"OTP_WAITING_PASSWORD",
"current_method":"EMAIL_OTP:1",
"msg":"OTP password sent, please enter",
"chains":[
{
"is_trusted":true,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["EMAIL_OTP:1"],
"name":"Email",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"Imyr6xEyKTsVCuvj0s2dRz6j6rtCqfFK",
"completed_methods":[],
"event_name": "NAM"
}
HTTP POST
https://authserver.example.com/api/v1/logon/Imyr6xEyKTsVCuvj0s2dRz6j6rtCqfFK/do_logon
Request
{
"response":
{
"answer":"12348765"
},
"endpoint_session_id":"P1npGvMizbs4HiFsiLX5h3FquTB5tfJj"
}
Response
{
"reason":"CHAIN_COMPLETED",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"event_name":"NAM",
"chains":[
{
"is_trusted":true,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["EMAIL_OTP:1"],
"name":"Email",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"data_id":"OSLogon",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"msg":"Welcome!",
"plugins":["LdapRules"],
"user_name":"COMPANY\\JSmith",
"user_email":"jsmith@company.com",
"current_method":"EMAIL_PASSWORD:1",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"status":"OK",
"logon_process_id":"Imyr6xEyKTsVCuvj0s2dRz6j6rtCqfFK",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"login_session_id":"ugn5m5Hm9ow5ejuvBUz7SQi3SWazoHS8",
"user_mobile_phone":"+16086783619",
"event_data_id":"OSLogon",
"completed_methods":["EMAIL_PASSWORD:1"],
"user_name_netbios":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"user_cn":"JSmith"
}
The email one-time password authentication method could not be enrolled, this method based on the user’s LDAP attribute and all users from repository with email addresses could authenticate by this method.
The emergency password authentication method is a method for the authentication by password with lifetime and usage counter. This method created for cases, when user should be authorized, but user could not use other method (smartphone or SMS authentication). The emergency password authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the emergency password authentication method or continue with the emergency password authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with user’s emergency password by POST request.
Table 3-58 The authentication data for the emergency password authentication method
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain user’s emergency password |
Resource will return a JSON-object with information about current state of the authentication.
The password authentication method supports the list of the authentication reasons.
Table 3-59 The emergency password method’s authentication reasons.
|
Reason value |
Description |
|---|---|
|
EMERG_PASSWORD_EXPIRED |
The emergency password was expired |
|
EMERG_PASSWORD_INEFFECTIVE |
The emergency password was ineffective |
|
EMERG_PASSWORD_EXHAUSTED |
The maximum login count was exhausted |
On the following example, the user JSmith form the COMPANY repository will try to authenticate by the emergency password, user has an endpoint session with the identifier “zQ9YQ1Txpax09iRBBTQJN71tSDgsMiuA”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"EMERG_PASSWORD:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"zQ9YQ1Txpax09iRBBTQJN71tSDgsMiuA"
}
Response
{
"reason":"PROCESS_STARTED",
"current_method":"EMERG_PASSWORD:1",
"msg":"Process started",
"chains":[
{
"is_trusted":null,
"is_enabled":true,
"short_name":"",
"position": 0,
"methods":["EMERG_PASSWORD:1"],
"name": "Emergency password",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"ULMzchEGWNPnutRROYDM18p24tTvQh2g",
"completed_methods":[],
"event_name":"NAM"
}
HTTP POST
https://authserver.example.com/api/v1/logon/ULMzchEGWNPnutRROYDM18p24tTvQh2g/do_logon
Request
{
"response":
{
"answer":"emgP@ssw0rD"
},
"endpoint_session_id":"zQ9YQ1Txpax09iRBBTQJN71tSDgsMiuA"
}
Response
{
"reason":"CHAIN_COMPLETED",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"event_name":"NAM",
"chains":[
{
"is_trusted":null,
"is_enabled":true,
"short_name":"",
"position": 0,
"methods":["EMERG_PASSWORD:1"],
"name": "Emergency password",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"data_id":"OSLogon",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"msg":"Welcome (CHAP)!",
"plugins":["LdapRules"],
"user_name":"COMPANY\\JSmith",
"user_email":"jsmith@company.com",
"current_method":"EMERG_PASSWORD:1",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"status":"OK",
"logon_process_id":"ULMzchEGWNPnutRROYDM18p24tTvQh2g",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"login_session_id":"6XFwPdePJ6y0pq9dBWFIcyerTVH2yMRJ",
"user_mobile_phone":"+16086783619",
"event_data_id":"OSLogon",
"completed_methods":["EMERG_PASSWORD:1"],
"user_name_netbios":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"user_cn":"JSmith"
}
For the enrollment, the emergency password authentication method you should start an enrollment process and provide an enrollment data as JSON container.
Table 3-60 The enrollment data for the emergency password method
|
Parameter name |
Description |
|---|---|
|
password |
The new emergency password value |
|
confirmation |
The confirmation of the new emergency password value, if password will not equals to the confirmation – enrollment will fail. |
|
max_logon_count |
The maximum login count, method will be disabled, when maximum count will reach. |
|
start_date |
The start date, from that date emergency password authentication method will begin work. Value should be a string with date. This is an optional parameter. |
|
end_date |
The end date, from that date emergency password authentication method will stop work. Value should be a string with date. This is an optional parameter. |
Resource will return a JSON object with status of the enrollment process.
The emergency password authentication method supports this set of the enrollment reasons.
Table 3-61 The emergency password method’s enrollment reasons
|
Reason value |
Description |
|---|---|
|
PASSWORD_BAD_CONFIRMATION |
The emergency password and the confirmation is not equals |
|
PASSWORD_EMPTY |
The provided emergency password or confirmation was empty |
|
PASSWORD_UNCHANGED |
The provided emergency password is equals to the current password |
|
PASSWORD_TOO_SHORT |
The provided emergency password is too small, please check password length in the policy values |
|
PASSWORD_TOO_SIMPLE |
The provided emergency password is too simple, user should use a stronger password |
On the following example, the user JSmith from the COMPANY repository will enroll the password authentication method, user has a login session with the identifier “wQabBzcnJTBqOqTdClHJTtrkpHFUzg40”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"EMERG_PASSWORD:1",
"login_session_id":"wQabBzcnJTBqOqTdClHJTtrkpHFUzg40"
}
Response
{
"enroll_process_id":"j7wpbJRTJ3LHIhSFSn2UWAEnTA15ldTK"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/j7wpbJRTJ3LHIhSFSn2UWAEnTA15ldTK/do_enroll
Request
{
"response":
{
"password":"new_EmgP@$sw0rd",
"confirmation":"new_EmgP@$sw0rd",
"max_logon_count":5
},
"login_session_id":"wQabBzcnJTBqOqTdClHJTtrkpHFUzg40"
}
Response
{
"reason":"",
"msg":"",
"status":"OK",
"method_id":"EMERG_PASSWORD:1"
}
The FIDO U2F authentication method provide authentication by FIDO U2F standard, please check this standard description. The FIDO U2F authentication method should always be used together with a second factor like a Password or PIN.
For the authentication, you should create a logon process with the FIDO U2F authentication method or continue with the FIDO U2F authentication method in case, when the authentication chain has more than one authentication methods. The FIDO U2F authentication method has two-step authentication process: on first step you should provide the application identifier and get the sign request from the appliance, on second step you should generate the sign response by FIDO U2F device and send it to the appliance.
Table 3-62 The authentication data for the FIDO U2F authentication method
|
Parameter name |
Description |
|---|---|
|
appId |
The application identifier for login |
|
signResponse |
The sign response from the FIDO U2F device, this is JSON container, check FIDO U2F description for more information |
Resource will return a JSON-object with information about current state of the authentication and the sign request.
Table 3-63 The response for the FIDO U2F authentication method
|
Response parameter name |
Description |
|---|---|
|
signRequests |
The JSON container for an array of the sign requests from the appliance. Each sign request is JSON container. |
The FIDO U2F authentication method supports the list of the authentication reasons.
Table 3-64 The FIDO U2F method’s authentication reasons
|
Reason value |
Description |
|---|---|
|
U2F_ALL_TOKENS_COMPROMISED |
The all tokens assigned to user was compromised |
|
U2F_NO_TOKENS |
The uses has not any assigned tokens. |
|
U2F_WAITING_AUTH_RESPONSE |
The FIDO U2F authentication method wait for the authentication request with the sign response data |
On the following example, the user JSmith from the COMPANY repository will try to authentication with the FIDO U2F authentication method, user already has an endpoint session with the identifier “eSFakgjm0o7eCb0hlUTVf1jzf2uGs9Y9”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"U2F:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"eSFakgjm0o7eCb0hlUTVf1jzf2uGs9Y9"
}
Response
{
"event_data_id":"OSLogon",
"current_method":"U2F:1",
"completed_methods":[],
"plugins":[],
"status":"MORE_DATA",
"logon_process_id":"kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
"chains":[
{
"image_name":"default",
"position":0,
"name":"FIDO U2F",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["U2F:1"]
}],
"reason":"PROCESS_STARTED",
"event_name":"NAM",
"msg":"Process started"
}
HTTP POST
https://authserver.example.com/api/v1/logon/kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp/do_logon
Request
{
"response":
{
"appId":"https://demo.yubico.com"
},
"endpoint_session_id":"eSFakgjm0o7eCb0hlUTVf1jzf2uGs9Y9"
}
Response
{
"event_data_id":"OSLogon",
"current_method":"U2F:1",
"completed_methods":[],
"plugins":[],
"status":"MORE_DATA",
"logon_process_id":"kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
"chains":[
{
"image_name":"default",
"position":0,
"name":"FIDO U2F",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["U2F:1"]
}],
"reason":"U2F_WAITING_AUTH_RESPONSE",
"event_name":"NAM",
"method_id":"U2F:1",
"msg":"Waiting authentication response",
"signRequests":[
{
"appId":"https://demo.yubico.com",
"challenge":"aU1A3-GQkcYDmgH78bGeO55dXN4fEyeTHGObhRr8GgI",
"keyHandle":"qF5EfdOTSEK4kP3hlEd_Q2SD4kOYs6K9qZJR5Ve9EloEs6ns36GHG-jGUKFD4JLMwOqsLsRnsipa-XsBzfF6Ow",
"version":"U2F_V2"
}],
}
HTTP POST
https://authserver.example.com/api/v1/logon/kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp/do_logon
Request
{
"response":
{
"signResponse":
{
"clientData":"eyJ0eXAiOiJuYXZpZ2F0b3IuaWQuZ2V0QXNzZXJ0aW9uIiwiY2hhbGxlbmdlIjoiZXYwd3dLR3l5bV9YamdZZkExd2tNT3Y4bGpsOHphS0F5WGdBV3gyUW91OCIsIm9yaWdpbiI6Imh0dHBzOi8vZGVtby55dWJpY28uY29tIiwiY2lkX3B1YmtleSI6IiJ9",
"keyHandle":"qF5EfdOTSEK4kP3hlEd_Q2SD4kOYs6K9qZJR5Ve9EloEs6ns36GHG-jGUKFD4JLMwOqsLsRnsipa-XsBzfF6Ow",
"signatureData":"AQAAAKowRAIgFrmzsrUHiUw2ixt20cXLjBRDo7-UoqWqZlNsFcXZL4ECIH45ALRE86ijsKPv_r3zmzhoE34N3NqzgvRJ1f49C1UA"
}
},
"endpoint_session_id":"eSFakgjm0o7eCb0hlUTVf1jzf2uGs9Y9"
}
Response
{
"user_name_netbios":"COMPANY\\JSmith",
"event_data_id":"OSLogon",
"login_session_id":"dkQsnIAMsCxQrcJP9AgIB2tSCkDDZQML",
"user_name":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"data_id":"OSLogon",
"user_cn":"JSmith",
"current_method":"U2F:1",
"status":"OK",
"chains":[
{
"image_name":"default",
"position":0,
"name":"FIDO U2F",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["U2F:1"]
}],
"reason":"CHAIN_COMPLETED",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"user_mobile_phone":"+16086783619",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"logon_process_id":"kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
"event_name":"NAM",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"completed_methods":["U2F:1"],
"plugins":["LdapRules"],
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"user_email":"jsmith@company.com",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"method_id":"U2F:1",
"msg":"Welcome!"
}
For the enrollment, the FIDO U2F authentication method you should start enrollment process and provide enrollment data. The FIDO U2F authentication method has two enrollment step: on first step you should get the registration request from the appliance, on second step you should provide the registration response from the device.
Table 3-65 The enrollment data for the FIDO U2F authentication method on first step
|
Parameter name |
Description |
|---|---|
|
userId |
The identifier of the enrolling user, you could skip this parameter if you will use “userName”. |
|
userName |
The user name of the enrolling user, you could skip this parameter if you will use “userId”. |
|
appId |
The application identifier, for more information about the application identifier please check FIDO U2F documentation. |
Table 3-66 The enrollment data for the FIDO U2F authentication method on second step
|
Parameter name |
Description |
|---|---|
|
registerResponse |
The registration response generated by device, this is JSON container. For more information about registration response, please check FIDO U2F documentation. |
Resource will return a JSON object with status of the enrollment process.
Table 3-67 The enrollment response for the FIDO U2F authentication method
|
Enrollment parameter |
Description |
|---|---|
|
registerRequests |
The registration request generated by the appliance, this is array of a JSON containers. The parameter will return only for new devices. |
|
signRequests |
The sign requests from the appliance, if user already has enrolled device the appliance will return the sign request and user could just validate it by device, this is array of a JSON containers. |
For more information about registration request, please check FIDO U2F documentation.
The FIDO U2F authentication method supports this set of the enrollment reasons.
Table 3-68 The FIDO U2F method’s enrollment reasons
|
Reason value |
Description |
|---|---|
|
U2F_WAITING_REG_RESPONSE |
The FIDO U2F authentication method waiting for the registration response |
|
U2F_NOT_ATTESTED |
The FIDO U2F authentication method was not attested, you should upload your token manufacturer attestation certificate. |
On the following example, the user JSmith from the COMPANY repository will try to enroll the FIDO U2F authentication method by his token, user already has a login session with the identifier “WXogCpZcHlsGsmmYiXkcxbg1qJMHJ4eD”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"U2F:1",
"login_session_id":"WXogCpZcHlsGsmmYiXkcxbg1qJMHJ4eD"
}
Response
{
"enroll_process_id":"hn0k1pTx1T6MQwOIbhBPUlLIopROig4Q"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/hn0k1pTx1T6MQwOIbhBPUlLIopROig4Q/do_enroll
Request
{
"response":
{
"userName":"COMPANY\\JSmith",
"appId":"https://demo.yubico.com"
},
"login_session_id":"WXogCpZcHlsGsmmYiXkcxbg1qJMHJ4eD"
}
Response
{
"signRequests":[],
"registerRequests":[
{
"appId":"https://demo.yubico.com",
"challenge":"Ij3TTvLi3H-oWNA18BDeIp_p1zN5bkzPipjQeuIbntQ",
"version":"U2F_V2"
}],
"msg":"Waiting register response ",
"reason":"U2F_WAITING_REG_RESPONSE",
"method_id":"U2F:1",
"status":"MORE_DATA"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/hn0k1pTx1T6MQwOIbhBPUlLIopROig4Q /do_enroll
Request
{
"response":
{
"registerResponse":
{
"clientData":"eyJ0eXAiOiJuYXZpZ2F0b3IuaWQuZmluaXNoRW5yb2xsbWVudCIsImNoYWxsZW5nZSI6IjFNX2hrbkxka0Ixb1hySFQxWUZqSHA5NDRpT2w4N2kwd1B5UUV0MW5DYzQiLCJvcmlnaW4iOiJodHRwczovL2RlbW8ueXViaWNvLmNvbSIsImNpZF9wdWJrZXkiOiIifQ",
"registrationData":"BQQ_jNAqemWkTfI9uL4CVo3eQSNIMe66u-pasr8BMuu9maA764C7jDPqXMUWhw8_4tDxeUbM72VJH5fssT6F2vT5QKheRH3Tk0hCuJD94ZRHf0Nkg-JDmLOivamSUeVXvRJaBLOp7N-hhxvoxlChQ-CSzMDqrC7EZ7IqWvl7Ac3xejswggIcMIIBBqADAgECAgRyWMLqMAsGCSqGSIb3DQEBCzAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowKzEpMCcGA1UEAwwgWXViaWNvIFUyRiBFRSBTZXJpYWwgMTQ4MDMzMjE1NzgwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASisDmTIlQxnUH6SFTVfKGN62nMmz5Nga45nzI-gRZDme8qlRRnPRV87L-18LzHiQhT7lXPPxogZvTVE5uTizELoxIwEDAOBgorBgEEAYLECgECBAAwCwYJKoZIhvcNAQELA4IBAQG8zBr5C3uVeBjVVaQzcWpgFqztyzEyw0EPNmFkEGwj2SqwbF0cLLaSmtQhSKoqOvOuU4k6aqFAyukyZZMVPZKqAP0Vh0sCMpRMzpDvEZjO3v6gh5Z8bIDmtQAJ5B2nnILyVpc7DA7taj3dUrZzNMD8v-bYjKdTsZJ_QzQstsewIPkoFOIRRtqta0iwkEFiX_cwR11IF-USGcQHKUBoMX65JP9nY6DzQ3XHplOD3bHUOHsCi2MqBZU-1fKOrQJpNP0w8cBQpSk_hsVTm7UiGW_FGrxrIKXfpGfCGICKDxCMfuWKIshu0HjP0pEhowAX1Ls1pie2SoK3-VEhYtkOFRLqMEUCIFnX5ZcO8ZWOKyF6R-tAse3rYdzwFBq4LZzEeXUwn6oMAiEAwNuC4mkjobmeyilaLM4twOAicm-R_x_YKzcQcXIx5cU"
}
},
"login_session_id":"WXogCpZcHlsGsmmYiXkcxbg1qJMHJ4eD"
}
Response
{
"reason":"",
"msg":"Enroll complete",
"status":"OK",
"method_id":"U2F:1"
}
The fingerprint authentication method provide users’ authentication by a fingerprint. The fingerprint authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the fingerprint authentication method or continue with the fingerprint authentication method in case, when the authentication chain has more than one authentication methods. This method accepts fingerprint data from user.
Table 3-69 The authentication data for the fingerprint authentication method
|
Parameter name |
Description |
|---|---|
|
capture |
The capture container with user’s finger data |
Table 3-70 The capture container
|
Parameter name |
Description |
|---|---|
|
captureStatus |
The one of the capture status |
|
Width |
The width of the fingerprint image in pixels |
|
Height |
The height of the fingerprint image in pixels |
|
Dpi |
The dot per inch of the fingerprint image |
|
BitsPerPixel |
The bits per pixel (usually 8 bits) |
|
BytesPerLine |
The bytes per one line in image (include align) |
|
Image |
The fingerprint image encoded using base-64 in gray scale |
|
ISO |
The data of fingerprint in ISO/IEC 19794-2:2005 format |
If you will work with ISO/IEC 19794-2:2005 standard, response to the appliance should contain only “ISO” parameter without others. You should use only image or ISO format, not both. Better authentication for fingerprint provided by ISO format, image of fingerprint could contain errors for many reasons, ISO format could avoid this problems. For generating fingerprint in ISO format, check your hardware vendor documentation.
Table 3-71 The capture statuses list
|
Status value |
Status description |
|---|---|
|
Ok |
The capture was successful |
|
Timeout |
The capture got timeout |
|
Error |
The capture got error |
|
NoReader |
There is no reader for the capture |
On the following example, the user JSmith for the COMPANY repository will try to authenticate by the fingerprint authentication method, user already has an endpoint session with the identifier “7XrFFQB28O6pod8Y5ElCs4K75TYBAffy”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"FINGER:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"7XrFFQB28O6pod8Y5ElCs4K75TYBAffy"
}
Response
{
"current_method":"FINGER:1",
"chains":[
{
"name":"Fingerprint",
"methods":["FINGER: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":"wZFkJ6kTvrbohSH6o5X5swGvZXDMoCQW",
"plugins":[],
"event_data_id":"OSLogon",
"event_name":"NAM",
"status":"MORE_DATA",
"reason":"PROCESS_STARTED"
}
HTTP POST
https://authserver.example.com/api/v1/logon/wZFkJ6kTvrbohSH6o5X5swGvZXDMoCQW/do_logon
Request
{
"response":
{
"capture":
{
"BitsPerPixel":8,
"BytesPerLine":300,
"Dpi":500,
"Height":300,
"Image":"The base64 encoded image",
"Width":300,
"captureStatus":"Ok"
}
},
"endpoint_session_id":"7XrFFQB28O6pod8Y5ElCs4K75TYBAffy"
}
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":"jsmith@company.com",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"chains":[
{
"name":"Fingerprint",
"methods":["FINGER: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",
"completed_methods":["FINGER:1"],
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"logon_process_id":"wZFkJ6kTvrbohSH6o5X5swGvZXDMoCQW",
"current_method":"RADIUS:1",
"user_name":"COMPANY\\JSmith",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"login_session_id":"LN8WNzoregyveYy69igAAKA77p3GC0RB",
"event_name":"NAM",
"status":"OK",
"user_name_netbios":"COMPANY\\JSmith",
"plugins":["LdapRules"],
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"reason": "CHAIN_COMPLETED"
}
For the enrollment, the fingerprint authentication method you should start an enrollment process and provide the enrollment data as a JSON container. The enrollment data has same structure and names as authentication data
On the following example, the user JSmith from the COMPANY repository will enroll the fingerprint authentication method, user has a login session with identifier the “wQabBzcnJTBqOqTdClHJTtrkpHFUzg40”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"FINGER:1",
"login_session_id":"wQabBzcnJTBqOqTdClHJTtrkpHFUzg40"
}
Response
{
"enroll_process_id":"lHpM6G8Z8DiHBw0iFoAK8LfCMDxIu9hk"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/lHpM6G8Z8DiHBw0iFoAK8LfCMDxIu9hk/do_enroll
Request
{
"response":
{
"capture":
{
"BitsPerPixel":8,
"BytesPerLine":300,
"Dpi":500,
"Height":300,
"Image":"The base64 encoded image",
"Width":300,
"captureStatus":"Ok"
}
},
"login_session_id":"wQabBzcnJTBqOqTdClHJTtrkpHFUzg40"
}
Response
{
"reason":"",
"msg":"",
"status":"OK",
"method_id":"FINGER:1"
}
The OATH HOTP authentication method provide user authentication by counter based one-time password. This method can be used as a single method in the authentication chain or as a part of the authentication chain..
For the authentication, you should create a logon process with the HOTP authentication method or continue with the HOTP authentication method as next authentication method in case, when the chain has more than one methods. You should provide a JSON object, which contain user’s counter based one-time password, by POST request.
Table 3-72 The authentication data for the HOTP authentication method
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain user’s counter based one-time password |
Resource will return a JSON-object with information about current state of the authentication.
The HOTP authentication method supports the set of authentication reasons.
Table 3-73 The HOTP method’s authentication reasons.
|
Reason value |
Description |
|---|---|
|
HOTP_PASSWORD_WRONG |
The counter based one-time password providing on authentication was wrong |
|
HOTP_PASSWORD_UNDEFINED |
The counter based one-time password is undefined for user. |
On the following example, we provide HOTP authentication for the user JSmith from the COMPANY repository, user already create endpoint session with the identifier “5IUw6BzZEZ30d5AurQJbp7R9KLWhcHoC”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"HOTP:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"5IUw6BzZEZ30d5AurQJbp7R9KLWhcHoC"
}
Response
{
"event_name":"NAM",
"completed_methods":[],
"reason":"PROCESS_STARTED",
"event_data_id":"OSLogon",
"msg":"Process started",
"logon_process_id":"xYKEgMYGntELKvbD3KvfmNfvI8EljNLR",
"plugins": [],
"status": "MORE_DATA",
"current_method":"HOTP:1",
"chains":[
{
"name":"Counter based one time password",
"apply_for_ep_owner":false,
"is_enabled":true,
"is_trusted":true,
"short_name":"",
"image_name":"default",
"position":0,
"methods": ["HOTP:1"]
}]
}
HTTP POST
https://authserver.example.com/api/v1/logon/xYKEgMYGntELKvbD3KvfmNfvI8EljNLR/do_logon
Request
{
"response":
{
"answer":"573854"
},
"endpoint_session_id":"5IUw6BzZEZ30d5AurQJbp7R9KLWhcHoC"
}
Response
{
"reason":"CHAIN_COMPLETED",
"msg": "Welcome!",
"event_name":"NAM",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"user_name":"COMPANY\\JSmith",
"user_mobile_phone":"+16086783619",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"event_data_id":"OSLogon",
"user_name_netbios":"COMPANY\\Jsmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"logon_process_id":"xYKEgMYGntELKvbD3KvfmNfvI8EljNLR",
"status":"OK",
"current_method":"HOTP:1",
"chains":[
{
"name":"Counter based one time password",
"apply_for_ep_owner":false,
"is_enabled":true,
"is_trusted":true,
"short_name":"",
"image_name":"default",
"position":0,
"methods": ["HOTP:1"]
}],
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"user_email":"jsmith@company.com",
"completed_methods":["HOTP:1"],
"login_session_id":"1yljtKNxC37kZcMDTND7PrDPDjJ6Kv4D",
"user_cn":"JSmith",
"plugins":["LdapRules"],
"data_id":"OSLogon",
"user_id":"ab2b845652d311e5a19a000c2951aca4"
}
For the enrollment, the counter based one-time password authentication method you should start an enrollment process and provide the enrollment data as JSON container. You can enroll method with a counter or with a three consecutive generated passwords for case when user does not know a counter value.
Table 3-74 The HOTP method enrollment’s data.
|
Parameter name |
Description |
|---|---|
|
secret |
The secret for password generation, it should be a hex string with length more than 6 characters. |
|
counter |
The counter for password generation. This is optional parameter with default value 1. |
|
otp_format |
The password format from supporting password format list, this is optional parameter |
|
hash |
The name of hashing algorithm, this is optional parameter. List of the hashing algorithm provided in Python library hashlib.algorithms_guaranteed |
|
token_public_id |
The Yubikey token public identifier, this is optional parameter. You should use it when you work with Yubikey hardware tokens. |
|
hotp1 |
The 1st counter based one-time password, for enrollment without counter value |
|
hotp2 |
The 2nd counter based one-time password, for enrollment without counter value |
|
hotp3 |
The 3rd counter based one-time password, for enrollment without counter value |
Table 3-75 The HOTP one-time password’s formats.
|
One-time password format |
Description |
|---|---|
|
dec4 |
4 decimal digits |
|
dec6 |
6 decimal digits |
|
dec7 |
7 decimal digits |
|
dec8 |
8 decimal digits |
Resource will return a JSON object with status of the enrollment process.
The HOTP authentication method supports this list of the enrollment reasons.
Table 3-76 The HOTP method’s enrollment reasons.
|
Enrollment reason value |
Description |
|---|---|
|
CANT_FIND_COUNTER |
Method could not find a counter from the provided passwords list. |
On the following example, the user JSmith from the COMPANY repository will try to enroll the HOTP method, user already have a login session with the identifier “sz1bs8hCMNr2JOfDZJIhsCbAYwM2lHzN”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"HOTP:1",
"login_session_id":"sz1bs8hCMNr2JOfDZJIhsCbAYwM2lHzN"
}
Response
{
"enroll_process_id":"bweoSmHkB3FP17IOES4GtlReCmBxAEop"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/bweoSmHkB3FP17IOES4GtlReCmBxAEop/do_enroll
Request
{
"response":
{
"secret":"12345678901234567890",
"counter":"0"
},
"login_session_id":"sz1bs8hCMNr2JOfDZJIhsCbAYwM2lHzN"
}
Response
{
"status":"OK",
"method_id":"HOTP:1",
"msg": "",
"reason": ""
}
The LDAP password authentication method provide user authentication by LDAP password from internal or external user’s repository. This method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the LDAP password authentication method or continue with the LDAP password as next authentication method in case, when the chain has more than one method. You should provide a JSON object, which contain user’s password, by POST request.
Table 3-77 The authentication data for the LDAP password authentication method.
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain user’s LDAP password |
Resource will return JSON-object with information about current state of the authentication.
LDAP password authentication method supports list of authentication reasons.
Table 3-78 The LDAP method’s authentication reasons.
|
Reason value |
Description |
|---|---|
|
LDAP_PASSWORD_UNDEFINED |
The LDAP password undefined for user. |
|
LDAP_PASSWORD_WRONG |
LDAP password provided on authentication was wrong |
|
LDAP_PASSWORD_ACCOUNT_RESTRICTION |
LDAP account has restrictions |
|
LDAP_PASSWORD_INVALID_LOGON_HOURS |
User used invalid logon hours |
|
LDAP_PASSWORD_INVALID_WORKSTATION |
User used for logon invalid workstation |
|
LDAP_PASSWORD_EXPIRED |
LDAP password expired |
|
LDAP_PASSWORD_ACCOUNT_DISABLED |
LDAP account disabled |
|
LDAP_PASSWORD_TOO_MANY_CONTEXT_IDS |
Appliance has too many IDS context |
|
LDAP_PASSWORD_ACCOUNT_EXPIRED |
LDAP account expired |
|
LDAP_PASSWORD_MUST_CHANGE |
User must change password |
|
LDAP_PASSWORD_ACCOUNT_LOCKED_OUT |
LDAP account locked out |
On the following example, we provide LDAP password authentication for the user JSmith from the COMPANY repository, user already create endpoint session with the identifier “46kGFB3MUUebkcqosO9t4pVAVURsCMyz”.
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":"jsmith@company.com",
"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",
"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"
}
The LDAP password authentication method does not support enrollment – all user’s password provided by LDAP server.
The password authentication method provide authentication by password for users, this password is not LDAP user’s password, and it is a virtual password stored in the appliance, which user can enroll. The password authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the password authentication method or continue with the password authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with user’s password by POST request.
Table 3-79 The authentication data for the password authentication method.
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain user’s password |
Resource will return a JSON-object with information about current state of the authentication.
The password authentication method supports the list of the authentication reasons.
Table 3-80 The password method’s authentication reasons
|
Reason value |
Description |
|---|---|
|
PASSWORD_UNDEFINED |
The password undefined for user |
|
PASSWORD_EXPIRED |
The password was expired |
|
PASSWORD_WRONG |
The password provided at authentication was wrong |
On the following example, the user JSmith from the COMPANY repository will try to authenticate by the password method, user has an endpoint session with the identifier “TksW8P1T8nTee3LX2ZgAUCHEUPVCKOYC”.
POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"PASSWORD:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"TksW8P1T8nTee3LX2ZgAUCHEUPVCKOYC"
}
Response
{
"reason":"PROCESS_STARTED",
"current_method":"PASSWORD:1",
"msg":"Process started",
"chains":[
{
"is_trusted":null,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["PASSWORD:1"],
"name":"Password",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"jzZ5qMd9b4drh5chgcLk1KgHxtHh67Yo",
"completed_methods":[],
"event_name": "NAM"
}
HTTP POST
https://authserver.example.com/api/v1/logon/jzZ5qMd9b4drh5chgcLk1KgHxtHh67Yo/do_logon
Request
{
"response":
{
"answer":"P@$sw0rd"
},
"endpoint_session_id":"TksW8P1T8nTee3LX2ZgAUCHEUPVCKOYC"
}
Response
{
"reason":"CHAIN_COMPLETED",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"event_name":"NAM",
"chains":[
{
"is_trusted":null,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["PASSWORD:1"],
"name":"Password",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"data_id":"OSLogon",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"msg":"Welcome (CHAP)!",
"plugins":["LdapRules"],
"user_name":"COMPANY\\JSmith",
"user_email":"jsmith@company.com",
"current_method":"PASSWORD:1",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"status":"OK",
"logon_process_id":"jzZ5qMd9b4drh5chgcLk1KgHxtHh67Yo",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"login_session_id":"qgsrzukT8D2MjRq9exBcys0OaQnJcBUt",
"user_mobile_phone":"+16086783619",
"event_data_id":"OSLogon",
"completed_methods":["PASSWORD:1"],
"user_name_netbios":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"user_cn": "JSmith"
}
For the enrollment, the password authentication method you should start enrollment process and provide an enrollment data as a JSON container.
Table 3-81 The enrollment data for the password authentication method
|
Parameter name |
Description |
|---|---|
|
password |
The new password value |
|
confirmation |
The confirmation of the new password value, if password will not equals to the confirmation – enrollment will fail. |
Resource will return a JSON object with status of the enrollment process.
The password authentication method supports this set of the enrollment reasons.
Table 3-82 The password method’s enrollment reasons
|
Reason value |
Description |
|---|---|
|
PASSWORD_BAD_CONFIRMATION |
The password and the confirmation is not equals |
|
PASSWORD_EMPTY |
The provided password or confirmation was empty |
|
PASSWORD_UNCHANGED |
The provided password is equals to the current password |
|
PASSWORD_TOO_SHORT |
The provided password is too small, please check password length in the policy values |
|
PASSWORD_TOO_SIMPLE |
The provided password is too simple, user should use a stronger password |
On the following example, the user JSmith from the COMPANY repository will enroll the password authentication method, user has a login session with the identifier “QI98qz5PJazhpcFgI6HRbLeIGVSFOAOt”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"PASSWORD:1",
"login_session_id":"QI98qz5PJazhpcFgI6HRbLeIGVSFOAOt"
}
Response
{
"enroll_process_id":"SsKV3uOyJDskhqI6nUuqW0XYo4dJCtcP"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/SsKV3uOyJDskhqI6nUuqW0XYo4dJCtcP/do_enroll
Request
{
"response":
{
"password":"new_P@$sw0rd",
"confirmation":"new_P@$sw0rd"
},
"login_session_id":"QI98qz5PJazhpcFgI6HRbLeIGVSFOAOt"
}
Response
{
"reason":"",
"msg":"",
"status":"OK",
"method_id":"PASSWORD:1"
}
The RADIUS authentication method provide users’ authentication by password on external RADIUS server. The RADIUS authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the RADIUS authentication method or continue with the RADIUS authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with the user’s RADIUS password by POST request.
Table 3-83 The authentication data for the RADIUS authentication method
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain user’s RADIUS password |
Resource will return a JSON-object with information about current state of the authentication.
The RADIUS authentication method supports the set of the authentication reasons.
Table 3-84 The RADIUS method’s authentication reasons
|
Reason value |
Description |
|---|---|
|
RADIUS_WRONG_PASSWORD |
The RADIUS password provided for the authentication was wrong. |
On the following example, the user JSmith from the COMPANY repository will try to authenticate with the RADIUS authentication method, user already has an endpoint session with the identifier “7XrFFQB28O6pod8Y5ElCs4K75TYBAffy”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"RADIUS:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"7XrFFQB28O6pod8Y5ElCs4K75TYBAffy"
}
Response
{
"current_method":"RADIUS:1",
"chains":[
{
"name":"Radius Client",
"methods":["RADIUS: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":"wZFkJ6kTvrbohSH6o5X5swGvZXDMoCQW",
"plugins":[],
"event_data_id":"OSLogon",
"event_name":"NAM",
"status":"MORE_DATA",
"reason":"PROCESS_STARTED"
}
HTTP POST
https://authserver.example.com/api/v1/logon/wZFkJ6kTvrbohSH6o5X5swGvZXDMoCQW/do_logon
Request
{
"response":
{
"answer":"Str0nG_P@$WorD"
},
"endpoint_session_id":"7XrFFQB28O6pod8Y5ElCs4K75TYBAffy"
}
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":"jsmith@company.com",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"chains":[
{
"name":"Radius Client",
"methods":["RADIUS: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",
"completed_methods":["RADIUS:1"],
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"logon_process_id":"wZFkJ6kTvrbohSH6o5X5swGvZXDMoCQW",
"current_method":"RADIUS:1",
"user_name":"COMPANY\\JSmith",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"login_session_id":"LN8WNzoregyveYy69igAAKA77p3GC0RB",
"event_name":"NAM",
"status":"OK",
"user_name_netbios":"COMPANY\\JSmith",
"plugins":["LdapRules"],
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"reason": "CHAIN_COMPLETED"
}
For enrollment, RADIUS authentication method you should start an enrollment process and provide by POST request enrollment data as a JSON container.
Table 3-85 The enrollment data for the RADIUS authentication method
|
Parameter name |
Description |
|---|---|
|
user_name |
The user name that will be used for RADIUS authentication. This is optional parameter |
|
send_reponame |
The boolean flag – send or not repository name with user name, if it true – result will be “repo\username”, if false – “username”. Optional parameter |
Resource will return a JSON object with status of the enrollment process.
On the following example, the user JSmith from the COMPANY repository will enroll the RADIUS authentication method, user has a login session with the identifier “HJ6OZ6wBtfGAyEWTlO1BeGJOSOU5zwi3”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"RADIUS:1",
"login_session_id":"HJ6OZ6wBtfGAyEWTlO1BeGJOSOU5zwi3"
}
Response
{
"enroll_process_id":"FIOgJueuovKsGYrgHB6AKWO7cWXHFd6u"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/FIOgJueuovKsGYrgHB6AKWO7cWXHFd6u/do_enroll
Request
{
"response":
{
"user_name":"johnsmith"
},
"login_session_id":"HJ6OZ6wBtfGAyEWTlO1BeGJOSOU5zwi3"
}
Response
{
"method_id":"RADIUS:1",
"status":"OK",
"msg": "",
"reason": ""
}
The security questions authentication method provide users’ authentication by set of answers for a question. The security questions authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the security questions authentication method or continue with the security questions authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with the user’s answers by POST request. Method has two step for the authentication, on first step you should make an empty request for getting list of the security question from the appliance, on second step you should provide the user’s answers. The answer is a JSON-container with security question identifier and user’s answer.
Table 3-86 The authentication data for the security question authentication method
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain the set of user’s answers to the security questions. Each answer is a JSON object with “question identifier” and “user’s answer”. |
Resource will return a JSON-object with information about current state of the authentication.
The security questions authentication method supports the list of the authentication reasons.
Table 3-87 The security question method’s authentication reasons
|
Reason value |
Description |
|---|---|
|
SECQUEST_WRONG_ANSWERS |
The answers provided at the authentication was wrong |
|
SECQUEST_WAITING_ANSWERS |
The security questions authentication method wait for user’s answers. |
On the following example, the user JSmith form the COMPANY repository will try to authenticate by the security question authentication method, user already has an endpoint session with the identifier “nVVcBJ8GacuBfT7ur3tUKG2k54I6016T”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"SECQUEST:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"nVVcBJ8GacuBfT7ur3tUKG2k54I6016T"
}
Response
{
"current_method":"SECQUEST:1",
"chains":[
{
"name":"Security Questions",
"methods":["SECQUEST: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":"rqakRSR1pTxLsfxQy6UQRGXZBF4jLZC3",
"plugins":[],
"event_data_id":"OSLogon",
"event_name": "NAM",
"status":"MORE_DATA",
"reason":"PROCESS_STARTED"
}
HTTP POST
https://authserver.example.com/api/v1/logon/rqakRSR1pTxLsfxQy6UQRGXZBF4jLZC3/do_logon
Request
{
"response":{},
"endpoint_session_id":"nVVcBJ8GacuBfT7ur3tUKG2k54I6016T"
}
Response
{
"current_method":"SECQUEST:1",
"event_data_id":"OSLogon",
"msg":"Waiting for answers...",
"event_name":"NAM",
"completed_methods":[],
"chains":[
{
"name":"Security Questions",
"methods":["SECQUEST:1"],
"image_name":"default",
"apply_for_ep_owner":false,
"position":0,
"is_enabled":true,
"is_trusted":true,
"short_name":""
}],
"questions":
{
"0":"What is your dog name?",
"1":"What is your favorite band name?"
},
"status":"MORE_DATA",
"logon_process_id":"rqakRSR1pTxLsfxQy6UQRGXZBF4jLZC3",
"plugins":[],
"method_id":"SECQUEST:1",
"reason":"SECQUEST_WAITING_ANSWERS"
}
HTTP POST
https://authserver.example.com/api/v1/logon/rqakRSR1pTxLsfxQy6UQRGXZBF4jLZC3/do_logon
Request
{
"response":
{
"answers":
{
"0":"Spotty",
"1":"The Beatles"
}
},
"endpoint_session_id":"nVVcBJ8GacuBfT7ur3tUKG2k54I6016T"
}
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":"jsmith@company.com",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"chains":[
{
"name":"Security Questions",
"methods":["SECQUEST: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",
"completed_methods":["SECQUEST:1"],
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"logon_process_id":"rqakRSR1pTxLsfxQy6UQRGXZBF4jLZC3",
"current_method":"SECQUEST:1",
"user_name":"COMPANY\\JSmith",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"login_session_id":"C0rAfRFyPCALSK36eSXf56q7rQgmhle6",
"event_name":"NAM",
"status":"OK",
"user_name_netbios":"COMPANY\\JSmith",
"plugins":["LdapRules"],
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"reason":"CHAIN_COMPLETED"
}
For the enrollment , the security questions authentication method you should start an enrollment process and provide an enrollment data as a JSON container. The security question authentication method has two step on enrollment process: on first step you should make an empty response for getting set of the security questions, on second step you should provide the user’s answers.
Table 3-88 The enrollment data for the security question authentication method
|
Parameter name |
Description |
|---|---|
|
answers |
The set of the answers for the security questions, this is a JSON object with question identifier as key and answer as the value. |
Resource will return a JSON object with status of the enrollment process.
The security questions authentication method supports this set of the enrollment reasons.
|
Reason value |
Description |
|---|---|
|
SECQUEST_WAITING_ANSWERS |
The security question authentication method waiting for user’s answers set for enrollment. |
On the following example, the user JSmith from the COMPANY repository will try to enroll the security questions authentication method, user has a login session with the identifier “Lfz8BRaSBoGuYI8sVbCBp4bZEtEXL04h”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"SECQUEST:1",
"login_session_id":"Lfz8BRaSBoGuYI8sVbCBp4bZEtEXL04h"
}
Response
{
"enroll_process_id":"DVqM8pH4FC8cBgUG6wKvMlljU6Lhpi6d"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/DVqM8pH4FC8cBgUG6wKvMlljU6Lhpi6d/do_enroll
Request
{
"response":{},
"login_session_id":"Lfz8BRaSBoGuYI8sVbCBp4bZEtEXL04h"
}
Response
{
"method_id":"SECQUEST:1",
"questions":
{
"0":"What is your dog name?",
"1":"What is your favorite band name?"
},
"status":"MORE_DATA",
"msg":"Waiting for answers...",
"reason":"SECQUEST_WAITING_ANSWERS"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/DVqM8pH4FC8cBgUG6wKvMlljU6Lhpi6d/do_enroll
Request
{
"response":
{
"answers":
{
"0":"Spotty",
"1":"The Beatles"
}
},
"login_session_id":"Lfz8BRaSBoGuYI8sVbCBp4bZEtEXL04h"
}
Response
{
"method_id":"SECQUEST:1",
"status":"OK",
"msg":"",
"reason":""
}
The smartphone authentication method provide users’ authentication by their smartphone with special application (for iOS, Android). This method has two ways for the authentication: online and offline. For the online authentication users authenticate by application – accept or reject the authentication for their smartphone application. For the offline authentication users authenticate by application generated one-time password, this way provide authentication for cases without connection to the appliance. The smartphone authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the smartphone authentication method or continue with the smartphone authentication method in case, when the authentication chain has more than one authentication methods. You should provide an empty response for starting and checking status of the online authentication, or provide a JSON container with application generated one-time password for the offline authentication.
Table 3-89 The authentication data for the smartphone authentication method
|
Parameter name |
Description |
|---|---|
|
otp |
The application generated one-time password for the offline authentication by smartphone authentication method. |
Resource will return a JSON-object with information about current state of the authentication.
The smartphone authentication method supports the list of the authentication reasons.
Table 3-90 The smartphone method’s authentication reasons.
|
Reason value |
Reason description |
|---|---|
|
SMARTPHONE_SAME_TOTP |
The application generated one-time password provided for the authentication was same that last time |
|
SMARTPHONE_WRONG_TOTP |
The application generated one-time password provided for the authentication was wrong. |
|
SMARTPHONE_AUTH_CONFIRM_TIMEOUT |
The time for the authentication confirmation was out |
|
SMARTPHONE_AUTH_REJECTED |
The authentication was rejected from the smartphone application |
|
SMARTPHONE_LOGON_IN_PROGRESS |
The authentication by the smartphone authentication method in process |
|
SMARTPHONE_WAITING_DATA |
The smartphone authentication method wait for the authentication data from the user. |
On the following example, the user JSmith from the COMPANY repository will try to authenticate by the smartphone authentication method, he will use his smartphone with installed authentication application. User already has an endpoint session with the identifier “JTx5s5DW4HDCLvUfRG8W426etdgQ34uu”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"SMARTPHONE:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"JTx5s5DW4HDCLvUfRG8W426etdgQ34uu"
}
Response
{
"event_data_id":"OSLogon",
"current_method":"SMARTPHONE:1",
"completed_methods":[],
"plugins":[],
"status":"MORE_DATA",
"logon_process_id":"FSo7XFgzZU2X7186rQyUgac8KEajSwHP",
"chains":[
{
"image_name":"default",
"position":0,
"name":"Smartphone",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["SMARTPHONE:1"]
}],
"reason":"PROCESS_STARTED",
"event_name":"NAM",
"msg":"Process started"
}
With next request, the appliance will send the authentication request to the user's smartphone.
HTTP POST
https://authserver.example.com/api/v1/logon/FSo7XFgzZU2X7186rQyUgac8KEajSwHP/do_logon
Request
{
"response":{},
"endpoint_session_id":"JTx5s5DW4HDCLvUfRG8W426etdgQ34uu"
}
Response
{
"event_data_id":"OSLogon",
"current_method":"SMARTPHONE:1",
"completed_methods":[],
"plugins":[],
"status":"MORE_DATA",
"logon_process_id":"FSo7XFgzZU2X7186rQyUgac8KEajSwHP",
"chains":[
{
"image_name":"default",
"position":0,
"name":"Smartphone",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["SMARTPHONE:1"]
}],
"reason":"SMARTPHONE_WAITING_DATA",
"event_name":"NAM",
"method_id":"SMARTPHONE:1",
"msg":"Waiting for smartphone data..."
}
The user accepted the authentication request and status was changed.
HTTP POST
https://authserver.example.com/api/v1/logon/FSo7XFgzZU2X7186rQyUgac8KEajSwHP/do_logon
Request
{
"response":{},
"endpoint_session_id":"JTx5s5DW4HDCLvUfRG8W426etdgQ34uu"
}
Response
{
"user_name_netbios":"COMPANY\\JSmith",
"event_data_id":"OSLogon",
"login_session_id":"tbKNRLZnEPLeWRA53LRA3dPJ6fuYmT31",
"user_name":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"data_id":"OSLogon",
"user_cn":"JSmith",
"current_method":"SMARTPHONE:1",
"status":"OK",
"chains":[
{
"image_name":"default",
"position":0,
"name":"Smartphone",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["SMARTPHONE:1"]
}],
"reason":"CHAIN_COMPLETED",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"user_mobile_phone":"+16086783619",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"logon_process_id":"FSo7XFgzZU2X7186rQyUgac8KEajSwHP",
"event_name":"NAM",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"completed_methods":["SMARTPHONE:1"],
"plugins":["LdapRules"],
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"user_email":"jsmith@company.com",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"method_id":"SMARTPHONE:1",
"msg":"Auth accepted"
}
On the following example, the user JSmith from the COMPANY repository will try to authenticate by the smartphone authentication method with offline authentication and the application generated one-time password.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"SMARTPHONE:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"JTx5s5DW4HDCLvUfRG8W426etdgQ34uu"
}
Response
{
"event_data_id":"OSLogon",
"current_method":"SMARTPHONE:1",
"completed_methods":[],
"plugins":[],
"status":"MORE_DATA",
"logon_process_id":"9JoA6EPM7AFAh3WoK6kO2TIGQXc308qM",
"chains":[
{
"image_name":"default",
"position":0,
"name":"Smartphone",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["SMARTPHONE:1"]
}],
"reason":"PROCESS_STARTED",
"event_name":"NAM",
"msg":"Process started"
}
HTTP POST
https://authserver.example.com/api/v1/logon/9JoA6EPM7AFAh3WoK6kO2TIGQXc308qM/do_logon
Request
{
"response":
{
"totp":"263965"
},
"endpoint_session_id":"JTx5s5DW4HDCLvUfRG8W426etdgQ34uu"
}
Response
{
"user_name_netbios":"COMPANY\\JSmith",
"event_data_id":"OSLogon",
"login_session_id":"xGTHxdOd4FbKT5EyWQvtA4CGHSfdXawf",
"user_name":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"data_id":"OSLogon",
"user_cn":"JSmith",
"current_method":"SMARTPHONE:1",
"status":"OK",
"chains":[
{
"image_name":"default",
"position":0,
"name":"Smartphone",
"short_name":"",
"is_enabled":true,
"apply_for_ep_owner":false,
"is_trusted":true,
"methods":["SMARTPHONE:1"]
}],
"reason":"CHAIN_COMPLETED",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"user_mobile_phone":"+16086783619",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"logon_process_id":"9JoA6EPM7AFAh3WoK6kO2TIGQXc308qM",
"event_name":"NAM",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"completed_methods":["SMARTPHONE:1"],
"plugins":["LdapRules"],
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"user_email":"jsmith@company.com",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"method_id":"SMARTPHONE:1",
"msg":"Auth accepted"
}
For the enrollment, the smartphone authentication method you should start an enrollment process and provide an enrollment data by the smartphone application. For starting you should sent empty response by POST and send empty response for getting an enrollment status.
Resource will return a data for a QR code; you should create a QR code and scan it by the smartphone application. Users cannot start enrollment in offline mode.
Table 3-91 The enrollment response for the smartphone authentication method
|
Responce parameter name |
Description |
|---|---|
|
qrdata |
The data for a QR code, you should user this parameter for the QR code generation and then you should show this QR code to the user. |
Resource will return a JSON object with status of the enrollment process.
The smartphone authentication method supports this set of the enrollment reasons.
Table 3-92 The smartphone method’s enrollment reasons
|
Reason value |
Reason description |
|---|---|
|
SMARTPHONE_ENROLL_TIMEOUT |
The time for the enrollment was out. |
|
SMARTPHONE_WAITING_DATA |
The smartphone authentication method waiting enrollment data from the smartphone application. |
|
SMARTPHONE_SCAN_QR |
The smartphone authentication method provide data for the QR code. |
On the following example, the user JSmith from the COMPANY repository will try to enroll the smartphone authentication method by his smartphone application, user already has a login session with the identifier “4ZqmTy05KmwJ2ZbejUGUM5XypdcUpD4F”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"SMARTPHONE:1",
"login_session_id":"4ZqmTy05KmwJ2ZbejUGUM5XypdcUpD4F"
}
Response
{
"enroll_process_id":"U8emvI9mnKXTbwCWBJQBzu6SQMbwx2X7"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/U8emvI9mnKXTbwCWBJQBzu6SQMbwx2X7/do_enroll
Request
{
"response":{},
"login_session_id":"4ZqmTy05KmwJ2ZbejUGUM5XypdcUpD4F"
}
Response
{
"qrdata":"OOBDATAqhNL0wMaG/H64GoEFqqd3eJWmWkNI6JrDh+vRuo/mDvHJc/PhnpS4iOtqMz9OLG1ItO++ccCPciDOAO6Fhicvux9eWocZ91oI5W82yy+X3eht/V1JxGM2neihZVuxAol4nr5XhDUBXmx9PtLoUKl+HSncX9YUWkF/MbEX3XTlbvRtiXs/AFJTkZDkYLgm8mRM2I3z5sht+ToVM+SE8UFTInjZjqgg3MxTY3VqZOYR1Jsf/iC6dr+NJY1NdjAsP2ErEw8uBfR2AOX/Q/+oCbYFuxZKRr0+SM46eCQhtcmktyClKlyZtpbHResPNAtkaRl6SD2zHbUe48nk/R922Il+w==",
"msg":"Scan this QR with smartphone app",
"reason":"SMARTPHONE_SCAN_QR",
"method_id":"SMARTPHONE:1",
"status":"MORE_DATA"
}
On this step user does not scan QR code yet
HTTP POST
https://authserver.example.com/api/v1/enroll/U8emvI9mnKXTbwCWBJQBzu6SQMbwx2X/do_enroll
Request
{
"response":{},
"login_session_id":"4ZqmTy05KmwJ2ZbejUGUM5XypdcUpD4F"
}
Response
{
"msg":"Waiting for smartphone data...",
"reason":"SMARTPHONE_WAITING_DATA",
"method_id":"SMARTPHONE:1", "status": "MORE_DATA"
}
User successfully scanned a QR code and enrolled method
HTTP POST
https://authserver.example.com/api/v1/enroll/U8emvI9mnKXTbwCWBJQBzu6SQMbwx2X/do_enroll
Request
{
"response":{},
"login_session_id":"4ZqmTy05KmwJ2ZbejUGUM5XypdcUpD4F"
}
Response
{
"reason":"",
"msg":"",
"status":"OK",
"method_id":"SMARTPHONE:1"
}
The SMS one-time password authentication method provide authentication by one-time password that will send to the user’s phone in SMS. The appliance use a mobile phone numbers from LDAP repository, if user have not a mobile phone number in repository, he could not use this authentication method. The SMS one-time password authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the SMS one-time password authentication method or continue with the SMS one-time password authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with the user’s one-time password by POST request. This method has two step for authentication, on first step you should send empty data for sending SMS with one-time password to an user’s phone, on second step you should provide an one-time password.
Table 3-93 The authentication data for the SMS authentication method
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain user’s one-time password |
Resource will return a JSON-object with information about current state of the authentication.
The SMS one-time password authentication method supports the list of the authentication reasons.
Table 3-94 The SMS method’s authentication reasons.
|
Reason value |
Description |
|---|---|
|
OTP_CANNOT_SEND |
The appliance cannot send by SMS one-time password |
|
OTP_TOO_MANY_SENT |
The appliance was sent too many one-time passwords |
|
OTP_WAITING_PASSWORD |
The authentication method waiting for one-time password |
|
OTP_NO_PASSWORD |
The password provided for the authentication was empty |
|
OTP_PASSWORD_EXPIRED |
The one-time password was expired |
|
OTP_WRONG_PASSWORD |
The one-time password was wrong |
|
OTP_TOO_MANY_REQUESTS |
The appliance got too many requests |
On the following example, the user JSmith from the COMPANY repository will try to authenticate by the SMS one-time password authentication method, user already has an endpoint session with the identifier “Uho2sBV9AgIBUObuxrZYvKxw7ZKs84fV”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":" SMS_OTP:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"Uho2sBV9AgIBUObuxrZYvKxw7ZKs84fV"
}
Response
{
"reason":"PROCESS_STARTED",
"current_method":"SMS_OTP:1",
"msg":"Process started",
"chains":[
{
"is_trusted":true,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["SMS_OTP:1"],
"name":"SMS",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"RnWlothKg8kI4zO6pwMhsnT10PZ6dpSh",
"completed_methods":[],
"event_name":"NAM"
}
HTTP POST
https://authserver.example.com/api/v1/logon/RnWlothKg8kI4zO6pwMhsnT10PZ6dpSh/do_logon
Request
{
"response":{},
"endpoint_session_id":"Uho2sBV9AgIBUObuxrZYvKxw7ZKs84fV"
}
Response
{
"reason":"OTP_WAITING_PASSWORD",
"current_method":"SMS_OTP:1",
"msg":"OTP password sent, please enter",
"chains":[
{
"is_trusted":true,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["SMS_OTP:1"],
"name":"SMS",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"RnWlothKg8kI4zO6pwMhsnT10PZ6dpSh",
"completed_methods":[],
"event_name": "NAM"
}
HTTP POST
https://authserver.example.com/api/v1/logon/RnWlothKg8kI4zO6pwMhsnT10PZ6dpSh/do_logon
Request
{
"response":
{
"answer":"12345678"
},
"endpoint_session_id":"Uho2sBV9AgIBUObuxrZYvKxw7ZKs84fV"
}
Response
{
"reason":"CHAIN_COMPLETED",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"event_name":"NAM",
"chains":[
{
"is_trusted":true,
"is_enabled":true,
"short_name":"",
"position":0,
"methods":["SMS_OTP:1"],
"name":"SMS",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"data_id":"OSLogon",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"msg":"Welcome!",
"plugins":["LdapRules"],
"user_name":"COMPANY\\JSmith",
"user_email":"jsmith@company.com",
"current_method":"EMAIL_PASSWORD:1",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"status":"OK",
"logon_process_id":"RnWlothKg8kI4zO6pwMhsnT10PZ6dpSh",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"login_session_id":"nNSn6EepNQBk9hxD5X7lY3H064flsP1K",
"user_mobile_phone":"+16086783619",
"event_data_id":"OSLogon",
"completed_methods":["SMS_PASSWORD:1"],
"user_name_netbios":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"user_cn":"JSmith"
}
The SMS one-time password authentication method could not be enrolled, this method based on user’s LDAP attribute and all users from repository with mobile phone could authenticate by this method.
The OATH TOTP authentication method provide the users’ authentication by time based one-time password, this otp can be generated by any OATH TOTP compliant token. This method can be used as single method in an authentication chain or as a part of an authentication chain.
For the authentication, you should create a logon process with the TOTP method or continue with the TOTP as next authentication method in case, when the authentication chain has more than one authentication method. You should provide a JSON container with the user’s time based one-time password by POST request.
Table 3-95 The authentication data for the TOTP authentication method
|
Parameter name |
Description |
|---|---|
|
answer |
This parameter contain the user’s time based one-time password |
Resource will return a JSON-object with information about current state of the authentication.
The TOTP authentication method supports the list of the authentication reasons.
Table 3-96 The TOTP method’s authentication reasons
|
Reason value |
Description |
|---|---|
|
TOTP_PASSWORD_UNDEFINED |
The time based one-time password undefined for user |
|
TOTP_WAIT_MINUTE |
The time based one-time password was already used, please wait one minute and try again |
|
TOTP_PASSWORD_WRONG |
The time based one-time password provided at authentication was wrong |
On the following example, we provide authentication by the TOTP authentication method for the user JSmith from the COMPANY repository, user already created an endpoint session with the identifier “uaoVUar5v9hL3aRFFpAXCmhNTnpQg8L5”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"TOTP:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"uaoVUar5v9hL3aRFFpAXCmhNTnpQg8L5"
}
Response
{
"event_name":"NAM",
"completed_methods":[],
"reason":"PROCESS_STARTED",
"event_data_id":"OSLogon",
"msg":"Process started",
"logon_process_id": "5SkULTwh0CC6z4162wL7qGmBscJEUiM0", "plugins": [], "status":"MORE_DATA",
"current_method":"TOTP:1",
"chains":[
{
"name":"Time based one time password",
"apply_for_ep_owner":false,
"is_enabled":true,
"is_trusted":true,
"short_name":"",
"image_name":"default",
"position":0,
"methods":["TOTP:1"]
}]
}
HTTP POST
https://authserver.example.com/api/v1/logon/5SkULTwh0CC6z4162wL7qGmBscJEUiM0/do_logon
Request
{
"response":
{
"answer":"604630"
},
"endpoint_session_id":"uaoVUar5v9hL3aRFFpAXCmhNTnpQg8L5"
}
Response:
{
"reason":"CHAIN_COMPLETED",
"msg":"Welcome!",
"event_name":"NAM",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"user_name":"COMPANY\\JSmith",
"user_mobile_phone":"+16086783619",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"event_data_id":"OSLogon",
"user_name_netbios":"COMPANY\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"logon_process_id":"5SkULTwh0CC6z4162wL7qGmBscJEUiM0",
"status":"OK",
"current_method":"TOTP:1",
"chains":[
{
"name":"Time based one time password",
"apply_for_ep_owner":false,
"is_enabled":true,
"is_trusted":true,
"short_name":"",
"image_name":"default",
"position":0,
"methods":["TOTP:1"]
}],
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"user_email":"jsmith@company.com",
"completed_methods":["TOTP:1"],
"login_session_id":"U0ubr6cq1UIsTJrzjrLLftC9Czpghq83",
"user_cn":"JSmith",
"plugins":["LdapRules"],
"data_id":"OSLogon",
"user_id":"ab2b845652d311e5a19a000c2951aca4"
}
For the enrollment, the time based one-time password authentication method you should start enrollment process and provide enrollment data as a JSON container.
Table 3-97 The enrollment data for the TOTP authentication method
|
Parameter name |
Description |
|---|---|
|
secret |
The secret for one-time password generation, parameter could be a hex string or a base32 string |
|
is_base32_secret |
The boolean identifier, set it true, when secret is a base32 string. This is optional parameter with default value – false. |
|
period |
The period in seconds for generated password, this parameter determines lifetime for one-time password. This is optional password with default value – 30 seconds. |
|
otp_format |
The password format from supporting password format list, this is optional parameter |
|
hash |
The name of hashing algorithm, this is optional parameter. List of the hashing algorithm provided in Python library hashlib.algorithms_guaranteed |
Table 3-98 The one-time password’s formats
|
One-time password format |
Description |
|---|---|
|
dec4 |
4 decimal digits |
|
dec6 |
6 decimal digits |
|
dec7 |
7 decimal digits |
|
dec8 |
8 decimal digits |
Resource will return a JSON object with status of the enrollment process.
The TOTP authentication method supports this set of the enrollment reasons.
Table 3-99 The TOTP method’s enrollment reasons.
|
Enrollment reason value |
Description |
|---|---|
|
TOTP_SCAN_QR |
Method wait when QR code with secret will be scanned |
On the following example, the user JSmith from the COMPANY repository will enroll the time based one-time password authentication method, user has a login session with the identifier “JXjt1OLSRLcGeJ9G9Unt9HX4aq5lHYmB”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"TOTP:1",
"login_session_id":"JXjt1OLSRLcGeJ9G9Unt9HX4aq5lHYmB"
}
Response
{
"enroll_process_id":"rfiU0Xf6ghvV03HGiPvV0DV6fhHtYVTF"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/rfiU0Xf6ghvV03HGiPvV0DV6fhHtYVTF/do_enroll
Request
{
"response":
{
"secret":"12345678901234567890",
"period":60
},
"login_session_id":"JXjt1OLSRLcGeJ9G9Unt9HX4aq5lHYmB"
}
Response
{
"reason":"",
"msg":"",
"status":"OK",
"method_id":"TOTP:1"
}
The voice call authentication method provide users’ authentication by a pin code inputted via phone. The voice call authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the voice call authentication method or continue with the voice call authentication method in case, when the authentication chain has more than one authentication methods. This method does not accept data from user. This method has two steps: on first step you should make an empty POST request for starting calling to the user’s phone, on next steps you should make an empty POST request for checking authentication status.
The voice call authentication method supports the list of the authentication reasons.
Table 3-100 The voice call method’s authentication reasons
|
Reason value |
Description |
|---|---|
|
VOICE_PIN_NOT_VERIFIED |
The PIN code provided for the authentication was not verified |
|
VOICE_CALL_IN_PROGRESS |
The voice call in progress |
|
VOICE_PIN_EXPIRED |
The PIN code provided for the authentication was expired |
|
VOICE_CANNOT_CALL |
The voice call authentication method cannot start call |
|
VOICE_CALL_INITIATED |
The voice call authentication method was initiated |
On the following example, the user JSmith from the COMPANY repository will try to authenticate by the voice call authentication method, user already has an endpoint session with the identifier “655WwK8qwGt8cJlhMe82o3HVJWFFi0ec”.
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"VOICE:1",
"user_name":"COMPANY\\JSmith",
"event":"NAM",
"endpoint_session_id":"655WwK8qwGt8cJlhMe82o3HVJWFFi0ec"
}
Response
{
"event_data_id":"OSLogon",
"event_name":"NAM",
"reason":"PROCESS_STARTED",
"chains":[
{
"is_enabled":true,
"image_name":"default",
"short_name":"",
"is_trusted":true,
"apply_for_ep_owner":false,
"methods":["VOICE:1"],
"name":"Voice call",
"position":0
}],
"logon_process_id":"FjVLwfybejy1brptN45p9uQvuVva5hA5",
"completed_methods":[],
"plugins":[],
"current_method":"VOICE:1",
"status":"MORE_DATA",
"msg":"Process started"
}
On this request we start calling
HTTP POST
https://authserver.example.com/api/v1/logon/FjVLwfybejy1brptN45p9uQvuVva5hA5/do_logon
Request
{
"response":{},
"endpoint_session_id":"655WwK8qwGt8cJlhMe82o3HVJWFFi0ec"
}
Response
{
"event_data_id":"OSLogon",
"event_name":"NAM",
"reason":"VOICE_CALL_INITIATED",
"chains":[
{
"is_enabled":true,
"image_name":"default",
"short_name":"",
"is_trusted":true,
"apply_for_ep_owner":false,
"methods":["VOICE:1"],
"name":"Voice call",
"position":0
}],
"logon_process_id":"FjVLwfybejy1brptN45p9uQvuVva5hA5",
"completed_methods":[],
"plugins":[],
"current_method":"VOICE:1",
"status":"MORE_DATA",
"msg":"Call initiated"
}
HTTP POST
https://authserver.example.com/api/v1/logon/FjVLwfybejy1brptN45p9uQvuVva5hA5/do_logon
Request
{
"response":{},
"endpoint_session_id":"655WwK8qwGt8cJlhMe82o3HVJWFFi0ec"
}
Response
{
"event_data_id":"OSLogon",
"event_name":"NAM",
"reason":"VOICE_CALL_IN_PROGRESS",
"chains":[
{
"is_enabled":true,
"image_name":"default",
"short_name":"",
"is_trusted":true,
"apply_for_ep_owner":false,
"methods":["VOICE:1"],
"name":"Voice call",
"position":0
}],
"logon_process_id":"FjVLwfybejy1brptN45p9uQvuVva5hA5",
"completed_methods":[],
"plugins":[],
"current_method":"VOICE:1",
"status":"MORE_DATA",
"msg":"Call in progress"
}
User entered a PIN code from the phone and authentication status changed
HTTP POST
https://authserver.example.com/api/v1/logon/FjVLwfybejy1brptN45p9uQvuVva5hA5/do_logon
Request
{
"response":{},
"endpoint_session_id":"655WwK8qwGt8cJlhMe82o3HVJWFFi0ec"
}
Response
{
"current_method":"VOICE:1",
"user_cn":"JSmith",
"user_name_netbios":"COMPANY\\JSmith",
"user_dn":"CN=JSmith,CN=Users,DC=company,DC=com",
"reason":"CHAIN_COMPLETED",
"event_name":"NAM",
"user_email":"jsmith@company.com",
"msg":"Welcome!",
"user_name":"COMPANY\\JSmith",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"data_id":"OSLogon",
"logon_process_id":"FjVLwfybejy1brptN45p9uQvuVva5hA5",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"status": "OK",
"event_data_id":"OSLogon",
"chains":[
{
"is_enabled":true,
"image_name":"default",
"short_name":"",
"is_trusted":true,
"apply_for_ep_owner":false,
"methods":["VOICE:1"],
"name":"Voice call",
"position":0
}],
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"login_session_id":"znX7jRuvaZogxGpPW5zlGt77f4FsJSzL",
"completed_methods":["VOICE:1"],
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"plugins":["LdapRules"],
"user_mobile_phone":"+16086783619"
}
For the enrollment, the voice call authentication method you should start an enrollment process and provide the enrollment data as a JSON container.
Table 3-101 The enrollment data for the voice call authentication method
|
Parameter name |
Description |
|---|---|
|
pin |
The PIN code for the user’s authentication |
Resource will return JSON object with status of the enrollment process.
On the following example, the user JSmith from the COMPANY repository will enroll the password authentication method, user has a login session with identifier the “PJHyEFQFTjt7fgHmW28avMnKFMHldiT7”.
HTTP POST
https://authserver.example.com/api/v1/enroll
Request
{
"method_id":"VOICE:1",
"login_session_id":"PJHyEFQFTjt7fgHmW28avMnKFMHldiT7"
}
Response
{
"enroll_process_id":"lHpM6G8Z8DiHBw0iFoAK8LfCMDxIu9hk"
}
HTTP POST
https://authserver.example.com/api/v1/enroll/lHpM6G8Z8DiHBw0iFoAK8LfCMDxIu9hk/do_enroll
Request
{
"response":
{
"pin":"135978"
},
"login_session_id":"PJHyEFQFTjt7fgHmW28avMnKFMHldiT7"
}
Response
{
"reason":"",
"msg":"",
"status":"OK",
"method_id":"VOICE:1"
}
The NotarisID authentication method is a method for the authentication by Notaris identifier. The NotarisID authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the NotarisID authentication method or continue with the NotarisID authentication method in case, when the authentication chain has more than one authentication methods. When authentication will start, appliance create a request to the NotarisID system with enrolled user’s Notaris Indentifier, for checking status of authentication in NotarisID system, you should send an empty response to the appliance, the appliance will return status of method authentication.The NotarisID method supports the list of the authentication reasons.
Table 3-102 NotarisID method's authentication reasons.
|
Reason Value |
Reason Description |
|---|---|
|
OK |
The authentication was successful. |
|
WRONG_STATE |
The NotarisID system return a wrong state. |
|
TOO_OFTEN_POLL |
The requests to the NotarisID system is too often. |
|
WAITING_FOR_USER_ACCEPT |
The appliance wait for accepting authentication by user in NotarisID system. |
|
ERROR |
The authentication failed. |
ExampleOn next example, the user JSmith form the Advanced Authentication repository will try to authenticate by the NotarisID, user has an endpoint session with the identifier “zQ9YQ1Txpax09iRBBTQJN71tSDgsMiuA”.HTTP POSThttps://authserver.example.com/api/v1/logonRequest{ "method_id":"NOTARIS_ID:1", "user_name":"AUTHASAS\\JSmith", "event":"NAM", "endpoint_session_id":"zQ9YQ1Txpax09iRBBTQJN71tSDgsMiuA"}Response{ "reason":"PROCESS_STARTED", "current_method":"NOTARIS_ID:1", "msg":"Process started", "chains":[ { "is_trusted":null, "is_enabled":true, "short_name":"", "position": 0, "methods":["NOTARIS_ID:1"], "name": "NotarisID", "apply_for_ep_owner":false, "image_name":"default" }], "event_data_id":"OSLogon", "status":"MORE_DATA", "plugins":[], "logon_process_id":"ULMzchEGWNPnutRROYDM18p24tTvQh2g", "completed_methods":[], "event_name":"NAM"}HTTP POSThttps://authserver.example.com/api/v1/logon/ULMzchEGWNPnutRROYDM18p24tTvQh2g/do_logonRequest{ "response": {}, "endpoint_session_id":"zQ9YQ1Txpax09iRBBTQJN71tSDgsMiuA"}Response{ "reason":"OK", "user_id":"ab2b845652d311e5a19a000c2951aca4", "event_name":"NAM", "chains":[ { "is_trusted":null, "is_enabled":true, "short_name":"", "position": 0, "methods":["NOTARIS_ID:1"], "name": "NotarisID", "apply_for_ep_owner":false, "image_name":"default" }], "data_id":"OSLogon", "repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450", "msg":"Welcome!", "plugins":["LdapRules"], "user_name":"AUTHASAS\\JSmith", "user_email":"jsmith@authasas.com", "current_method":"NOTARIS_ID:1", "user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500", "status":"OK", "logon_process_id":"ULMzchEGWNPnutRROYDM18p24tTvQh2g", "user_dn":"CN=JSmith,CN=Users,DC=authasas,DC=com", "user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100", "login_session_id":"6XFwPdePJ6y0pq9dBWFIcyerTVH2yMRJ", "user_mobile_phone":"+16086783619", "event_data_id":"OSLogon", "completed_methods":["NOTARIS_ID:1"], "user_name_netbios":"AUTHASAS\\JSmith", "repo_id":"d3fba00652d211e5a19a000c2951aca4", "user_cn":"JSmith"
}
For the enrollment, the NotarisID authentication method you should start an enrollment process and provide an enrollment data as JSON container.
Table 3-103 Enrollment data for the NotarisID method
|
Parameter Name |
Parameter Description |
|---|---|
|
notaris_id |
The NotarisID identifier. |
Resource will return a JSON object with status of the enrollment process.The NotarisID authentication method supports this set of the enrollment reasons.
Table 3-104 NotarisID method’s enrollment reasons
|
Reason Value |
Reason Description |
|---|---|
|
NO_NOTARISID |
The identifier is not valid NotarisID identifier. |
ExampleOn next example, the user JSmith from the Advanced Authentication repository will enroll the NotarisID method, user has a login session with the identifier “wQabBzcnJTBqOqTdClHJTtrkpHFUzg40”.
HTTP POST
https://authserver.example.com/api/v1/enrollRequest{ "method_id":"NOTARIS_ID:1", "login_session_id":"wQabBzcnJTBqOqTdClHJTtrkpHFUzg40"}Response{ "enroll_process_id":"j7wpbJRTJ3LHIhSFSn2UWAEnTA15ldTK"}
HTTP POST
https://authserver.example.com/api/v1/enroll/j7wpbJRTJ3LHIhSFSn2UWAEnTA15ldTK/do_enrollRequest{ "response": { "notaris_id":"CZA7GXTO@notarisid" }, "login_session_id":"wQabBzcnJTBqOqTdClHJTtrkpHFUzg40"}Response{ "reason":"", "msg":"", "status":"OK", "method_id":"NOTARIS_ID:1"}
The PKI authentication method is a method for the authentication by public key infrastructure, with this method user have a private key on a smartcard and public key on appliance, user sign a challenge from the appliance and appliance validate this request. The PKI authentication method could be used as a single method in the authentication chain or as a part of the authentication chain.
For the authentication, you should create a logon process with the PKI authentication method or continue with the PKI authentication method in case, when the authentication chain has more than one authentication methods. You should provide a JSON container with user’s PKI data by POST request. The PKI method have a two steps, at first you should get a challenge from the appliance with empty request, at second step you should provide signed challenge to the appliance for validation.
Table 3-105 The authentication data for the PKI authentication method for second step
|
Parameter Name |
Parameter Description |
|---|---|
|
signature |
The signature for validation. |
|
padding |
The padding of the signature. |
|
hash |
The name of the hash algorithm. |
Resource will return a JSON-object with information about current state of the authentication and the signature on first step.
Table 3-106 The response parameter for PKI method.
|
Parameter Name |
Parameter Description |
|---|---|
|
challenge |
The challenge for signing. |
The PKI authentication method supports the list of the authentication reasons.
|
Reason Value |
Reason Description |
|---|---|
|
PKI_WAITING_AUTH_SIGN |
The appliance waiting for the authentication sign. |
|
PKI_SIGN_VERIFICATION_FAILED |
The verification of the sign was failed. |
|
PKI_CERT_VALIDATION_FAILED |
The validation of the certificate was failed. |
|
PKI_WRONG_CARD |
The card is wrong. |
HTTP POST
https://authserver.example.com/api/v1/logon
Request
{
"method_id":"PKI:1",
"user_name":"AUTHASAS\\JSmith",
"event":"NAM",
"endpoint_session_id":"P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u"
}
Response
{
"reason":"PROCESS_STARTED",
"current_method":"PKI:1",
"msg":"Process started",
"chains":[
{
"is_trusted":null,
"is_enabled":true,
"short_name":"",
"position": 0,
"methods":["PKI:1"],
"name": "PKI",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi",
"completed_methods":[],
"event_name":"NAM"
}
HTTP POST
https://authserver.example.com/api/v1/logon/t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi/do_logon
Request
{
"response": {},
"endpoint_session_id":"P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u"
}
Response
{
"reason":"PKI_WAITING_AUTH_SIGN",
"current_method":"PKI:1",
"msg":"Process started",
"chains":[
{
"is_trusted":null,
"is_enabled":true,
"short_name":"",
"position": 0,
"methods":["PKI:1"],
"name": "PKI",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"event_data_id":"OSLogon",
"status":"MORE_DATA",
"plugins":[],
"logon_process_id":"t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi",
"completed_methods":[],
"event_name":"NAM",
"challenge":"f81e9d6882aca80cbe97e291ee5771aba7cc13facb3c79a5ae924e788bc4f7d2"
}
HTTP POST
https://authserver.example.com/api/v1/logon/t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi/do_logon
Request
{
"response":
{
"signature":"d84f3a9b7244031aa5....42d123bdb715a153974e992b16d02",
"padding":"PKCS#1",
"hash":"SHA1"
},
"endpoint_session_id":"P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u"
}
Response
{
"reason":"CHAIN_COMPLETED",
"user_id":"ab2b845652d311e5a19a000c2951aca4",
"event_name":"NAM",
"chains":[
{
"is_trusted":null,
"is_enabled":true,
"short_name":"",
"position": 0,
"methods":["PKI:1"],
"name": "PKI",
"apply_for_ep_owner":false,
"image_name":"default"
}],
"data_id":"OSLogon",
"repo_obj_id":"2d3c89ccb3ea7b4dacbdfda13e26f450",
"msg":"Welcome!",
"plugins":["LdapRules"],
"user_name":"AUTHASAS\\JSmith",
"user_email":"jsmith@authasas.com",
"current_method":"PKI:1",
"user_sid":"S-1-5-21-4279545561-3293806183-1755797738-500",
"status":"OK",
"logon_process_id":"t9HZES2DFD6vDjhA3wNtizyjAuqMTrwi",
"user_dn":"CN=JSmith,CN=Users,DC=authasas,DC=com",
"user_sid_hex":"010500000000000515000000d9ae14ff677e53c4ea58a768f40100",
"login_session_id":"6XFwPdePJ6y0pq9dBWFIcyerTVH2yMRJ",
"user_mobile_phone":"+16086783619",
"event_data_id":"OSLogon",
"completed_methods":["PKI:1"],
"user_name_netbios":"AUTHASAS\\JSmith",
"repo_id":"d3fba00652d211e5a19a000c2951aca4",
"user_cn":"JSmith"
}
For the enrollment, the PKI authentication method you should start an enrollment process and provide an enrollment data as JSON container.
Table 3-108 The enrollment data for the PKI method
|
Parameter Name |
Parameter Description |
|---|---|
|
card_uid |
The card UID. |
|
modulus |
The modulus for the sign. |
|
exponent |
The exponent for the sign. |
Resource will return a JSON object with status of the enrollment process.The PKI authentication method supports this set of the enrollment reasons.
Table 3-109 The emergency password method’s enrollment reasons
|
Reason Value |
Reason Description |
|---|---|
|
PKI_CERT_VALIDATION_FAILED |
The validation of the certificate was failed. |
ExampleOn next example, the user JSmith from the Advanced Authentication repository will enroll the PKI authentication method, user has a login session with the identifier “WXogCpZcHlsGsmmYiXkcxbg1qJMHJ4eD”.
HTTP POSThttps://authserver.example.com/api/v1/enrollRequest{ "method_id":"EMERG_PASSWORD:1", "login_session_id":"WXogCpZcHlsGsmmYiXkcxbg1qJMHJ4eD"}Response{ "enroll_process_id":"hn0k1pTx1T6MQwOIbhBPUlLIopROig4Q"}HTTP POSThttps://authserver.example.com/api/v1/enroll/hn0k1pTx1T6MQwOIbhBPUlLIopROig4Q/do_enrollRequest{ "response": { "card_uid":"11223344", "modulus":"a49c35fdc669519e9d0c713c....91daaa9d2604eeeaad73d13b1", "exponent":"010001" }, "login_session_id":"WXogCpZcHlsGsmmYiXkcxbg1qJMHJ4eD"}Response{ "reason":"", "msg":" Enrollment complete" ",