SecSign protects user accounts from phishing, brute-force and hacker attacks as well as theft or copying of authentication credentials. The SecSign ID Two-Factor Authentication (2FA) adds an additional layer of protection to the mobile device by including it as a physical token in the authentication process.
The SecSign ID session authentication is based on 2048-bit-RSA key pairs. The SecSign ID app includes the user’s private key (secured with a PIN) and the SecSign ID Server knows the user’s public key.
The SecSign ID server verifies the possession of the private key and the knowledge of the key during the authentication of the session. It then evaluates the authentication request and informs the service if access can be granted via the SecSign ID API.
The SecSign ID Server can be used in the public cloud or as in-house solution. The latter allows for all systems and data in the internet and intranet to remain with the client. The in-house solution can either be installed on a on-premise server or with a hybrid cloud configuration.
The end- points of the SecSign ID API are the following URLs:
https://httpapi.secsign.com, Port 443 https://httpapi2.secsign.com als Fallbackserver, Port 443
The interface expects a HTTP-POST request and URL-coded parameter lists as an answer. The server answers in URL-coded format as well.
The URL-coded format is easier to pars in some programming languages, for example Perl and C. With the next update, the request header will transmit the format and JSON will be supported for both transmitting to the server and returning.
The public ID-server is only used for this kind of communication. The upstream SecSign Routing Server prevents other requests. Additional communication options are possible with an in-house setup, for example a web-service and SOAP.
The ID Server includes a web application firewall. It monitors that the amount of required parameters matches. Also, the parameter value format is verified. When the API expects a true or false but receives a different value, a bad-request-error is returned (see 7. Error Messages).
To authenticate the user an authentication session needs to be started. The client sends an authentication request and receives the access pass in return. The user’s mobile device displays the option to confirm the login.
The client sends a POST request to the SecSign ID API server to request an AuthSession. The parameter to be transferred are URL-coded. That means, all key-pairs are separated by a “=” and concatenated with “&”:ParameterName1=Value&ParameterName2=Value2…
PARAMETER NAME | STATUS | VALUE |
request | required | ReqRequestAuthSession Notifies the server that this is a request for an authentication session. |
secsignid | required | The user’s SecSign ID, valid characters are 0-9a-zA-Z-@_. |
servicename | required | Name of the project or website (this value is displayed to the mobile device user). |
serviceaddress | required | IP-address or URL of the project/website (this value is displayed to the mobile device user). |
pluginname | required | Is used in case a plugin (for example Joomla or WordPress) uses the API. |
apimethod | required | Describes the setting for the authentication, or which API is used. SecSignIDApi_PHP, SecSignIDApi_C, SecSignIDApi_Ruby, SecSignIDApi_Python, SecSignIDApi_Perl … |
showaccesspass | required | true or false The SecSign ID can be used with or without AccessPass. Omitting the AccessPass is only recommended if a two step authentication is used.The answer to the request will always return accesspassicondata, which includes the AccessPass. The app does no display an AccessPass if the value is “false”. In this case, the client can ignore accesspassicondata. Standard value: true (the AccessPass is displayed). |
Example for a request for authentication of the SecSign ID “johndoe” on a website with AccessPass:
request=ReqRequestAuthSession&secsignid=johndoe&servicename=Testwebsite&serviceaddress=localhost&pluginname=wordpress&apimethod=SecSignIDApi_PHP
The server sends an answer with the HTTP status code 200 and the following URL-coded parameter in the message body when the request is accepted. If an error occurs the associated status code is transmitted with the corresponding parameter list including the error description (see 6. Error Messages).
PARAMETER NAME | STATUS | VALUE |
authsessionid | always | 19 digit number – ID of the requested session |
servicename | always | The service name of the request |
SecSignID | always | The user’s SecSign ID |
authsessionstate | always | Session Status 0 No-State: Is used when the session state is undefined 1 Pending: The AuthSession was requested but was neither confirmed nor rejected 2 Expired: The AuthSession has expired (timeout after 2 minutes) 3 Accepted: The AuthSession has been accepted by the user on the user´s smartphone 4 Denied: The AuthSession has been rejected by the user on the user’s smartphone 5 Suspended: The ID-Server has canceled the AuthSession, for example, because the user started several login attempts at the same time 6 Canceled: The user canceled the complete login process on the website 7 Fetched: The user has the access pass already on the smartphone but has not confirmed the AuthSession yet 8 Invalid: This session has become invalid. |
serviceaddress | always | The service address of the request |
requestid | always | The ID of the current requested session. This ID is used to assign further requests, for example about the status of the session. |
authsessionicondata | always | The AccessPass is returned as a base64-coded PNG-image and has to be presented to the user during login. The same image is sent to the smartphone by the ID Server. The user can log in by comparing the images and accept the AuthSession on the phone. |
authsessionid=9162914906710510618&servicename=libsecsignidC&secsignid=johndoe&authsessionstate=1&serviceaddress=localhost&requestid=134B0110289F76FE58A5449868187B99BB7FC59D8689A59EC809D50F6C1E234C&authsessionicondata=iVB...YC
The AccessPass is stored at authsessionicondata and, if HTML is used, can be directly embedded in the img element.
<img id="secsignid-accesspass-img" style="display: block;" src="data:;base64,iVB...YC=" alt="" />
The client can request the status of the authentication to find out if a user accepted or denied an authentication session on his phone. Depending on the client this can be performed in continuous intervals (polling), until a status code is transmitted and the process can continue (for example when the user is logged in).
The client needs to send a POST request to the SecSign ID API Server to retrieve the status of the authentication. The transferred parameter are URL coded.
PARAMETER NAME | STATUS | VALUE |
request | required | ReqGetAuthSessionState Informs the server that this is a request for a session status. The session is defined in authsessionid and requestid. |
secsignid | required | The user’s SecSign ID |
authsessionid | required | Session ID |
requestid | required | The ID of the current requested session. This ID is used to assign further requests, for example about the status of the session. |
apimethod | required (soon optional) |
This Parameter describes the environment of the authentication or which API is used. SecSignIDApi_PHP SecSignIDApi_C … |
Example for the session status request:
request=ReqGetAuthSessionState&secsignid=johndoe&authsessionid=9162914906710510618&requestid=134B0110289F76FE58A5449868187B99BB7FC59D8689A59EC809D50F6C1E234C&apimethod=SecSignIDApi_PHP
The SecSign ID server answer includes the parameter “authsessionstate”, which describes the authentication session status. Depending on the status the client can act accordingly.
If the status returns accepted (3), the user can be logged in. If the authentication is suspended (5) or rejected (4), the user can be returned to the login screen. If the login session is pending (1) the status should be requested again after a certain period.
PARAMETER NAME | STATUS | VALUE |
message | optional | Status message when the user could not be authenticated and no technical error was detected, for example if the session was denied by the user: “You have denied the access pass.” |
authsessionid | always | The session ID |
secsignid | optional | The user’s SecSign ID is transmitted when the user is authenticated successfully. The SecSign ID should be used for further login steps at the client, since previous login information could consist of the priority code instead of the true SecSign ID (see 8.). |
authsessionstate | always | Session Status 0 No-State: Is used when the session state is undefined 1 Pending: The AuthSession was requested but was neither confirmed nor rejected 2 Expired: The AuthSession has expired (timeout after 2 minutes) 3 Accepted: The AuthSession has been accepted by the user on the user´s smartphone 4 Denied: The AuthSession has been rejected by the user on the user’s smartphone 5 Suspended: The ID-Server has canceled the AuthSession, for example, because the user started several login attempts at the same time 6 Canceled: The user canceled the complete login process on the website 7 Fetched: The user has the access pass already on the smartphone but has not confirmed the AuthSession yet 8 Invalid: This session has become invalid. |
Example for the answer to the session status request:
authsessionid=9162914906710510618&secsignid=johndoe&authsessionstate=3
Example for the answer to the session status request, if the user denied the authentication:
message=You have denied the access pass.&authsessionid=9162914906710510618&authsessionstate=4
The authentication can be aborted at any point, as long as the user did not confirm the login on his phone. The session can be released when the user was logged in successfully and the session information no longer need to be retrieved from the server.
PARAMETER NAME | STATUS | VALUE |
request | required | ReqReleaseAuthSession Informs the server that the session can be released, for example with a successful authentication.ReqCancelAuthSession Informs the server to cancel the session. |
secsignid | required | The user’s SecSign ID |
authsessionid | required | The session’s ID |
requestid | required | The ID of the current requested session. This ID is used to assign further requests, for example about the status of the session. |
apimethod | required (soon optional) |
Describes the setting for the authentication, or which API is used. SecSignIDApi_Ruby, SecSignIDApi_Python, … |
Example for the cancellation of a session:
request=ReqCancelAuthSessionState&secsignid=johndoe&authsessionid=9162914906710510618&requestid=134B0110289F76FE58A5449868187B99BB7FC59D8689A59EC809D50F6C1E234C
The answer of the server includes the ID of the session that has been cancelled, as well as the status of the session. If another status request is sent after releasing or cancelling of the session an error is returned since the session no longer exists.
PARAMETER NAME | STATUS | VALUE |
authsessionid | required | The session ID |
authsessionstate | required | Session Status 0 No-State: Is used when the session state is undefined 1 Pending: The AuthSession was requested but was neither confirmed nor rejected 2 Expired: The AuthSession has expired (timeout after 2 minutes) 3 Accepted: The AuthSession has been accepted by the user on the user´s smartphone 4 Denied: The AuthSession has been rejected by the user on the user’s smartphone 5 Suspended: The ID-Server has canceled the AuthSession, for example, because the user started several login attempts at the same time 6 Canceled: The user canceled the complete login process on the website 7 Fetched: The user has the access pass already on the smartphone but has not confirmed the AuthSession yet 8 Invalid: This session has become invalid. |
Example for the answer to release a session after a successful authentication.
authsessionid=9162914906710510618&authsessionstate=3
There are two different types of error messages:
1. Technical errors may occur with incorrect syntax in the parameter list. The error messages are returned with the HTTP status code 400 and contain a HTML message body, for example:
<h1>Bad Request HTTP/1.1 400</h1> The server could not understand this request. <p class="errormsg">bad parameter: Parameter is missing for request 'ReqReleaseAuthSession'.</p>
2. Context errors may occur when there is a problem with the authentication itself, for example if the specified SecSign ID does not exist or the session is expired.
error=400&errormsg=No session could be found therefor the request could not be processed.&errorcode=10013
PARAMETER NAME | STATUS | VALUE |
error | always | Error HTTP status code |
errormsg | always | Description of the error |
errormsg | always | Description of the error as code |
A user cannot start several authentication sessions without accepting or denying the first one. This feature is important to prevent mix-ups or accidentally confirm logins.
If two login sessions are requested (via ReqRequestAuthSession) without accepting the first one on the phone, all logins are suspended and an error is returned.
The user can override the suspension by selecting his SecSign ID on his phone.
If the problem persists a priority code is displayed on the phone, which can be used instead of the SecSign ID. If the session is accepted on the phone, “ReqGetAuthSessionState” returns the true SecSign ID for the user.
We provide an ever growing list of APIs and plugins to easily integrate the SecSign ID Two-Factor Authentication in any project. An overview is available at Plugin and APIs.
We do not only offer APIs in different programming languages but also plugins for CMS, Server and VPN environments, oAuth2 and many more. These plugins use our APIs and offer additional functionalities, for example user management, easy and native installation, logging or integration in firewalls or Active Directory.
The JIRA plugin for example uses the JAVA-API. The PHP-Api and JS-API is used by WordPress, Joomla, Drupal, Typo3 and many more. The ASP.net/C#-API is used for the Windows and Cisco VPN and the C-API is used for protecting Unix SSH services. The Objective-C API is used by our AppleTV and iPhone/iPad apps.
You can experience the SecSign ID two-factor authentication and the two-factor login by simply integrating the plugin into your website or test environment. Or you can try out the login process on our website without having to register first. You already have a SecSign ID or you want one? Login now and use the portal or use our hassle free registration.
See for yourself how fast and convenient the login process using challenge-response authentication with 2048-bit key pairs is. There is no need for passwords, and no passwords or other confidential information are ever transmitted. It is easy to integrate and simple to use.
For more information about the patented SafeKey procedure and it's unique security can be found here.
If you are missing an API for the programming language you are working with, feel free to contact us and we’ll find a solution with you. If you need help with the integration into an existing system or you can’t find the plugin for your content management system you are working with, don’t hesitate to contact our support team.
On premise installations of SecSign ID offer the flexibility to connect with your preferred servers, services, and devices. And you can customize the SecSign ID with your own organization’s branding.
Choose between our SecSign ID Cloud or operate your own on-premise Two-Factor Authentication server.
Operate your own YourBrand ID app - Two-Factor Authentication customized to your needs.
Integrate SecSign ID Two-Factor Authentication in existing apps with our ready-to-use SDK.
Use the Two-Factor Authentication Server to secure your company Active Directory/LDAP. Your own Identity and Access Management System, for example for mandatory updates and additional security features.
Integration in any login environment: web, local, VPN, remote desktop, mobile logins and many more.
No need for complex integration: we have plugins for almost all environments.
Want to learn more about SecSign’s innovative and highly secure
solutions for protecting your user accounts and sensitive data?
Use our contact form to submit your information, and a SecSign sales representative will contact you within one business day.
If you need assistance with an existing SecSign account or product
installation, please see the FAQs for more information on the most common questions. You don’t find the solution to your problem? Don’t hesitate to contact the
Product Support
I am Interested in