Generic selectors
Exact matches only
Search in title
Search in content

SecSign ID Server API

Find out why our Two-Factor Authentication is the best, some key-facts for developers and why you should upgrade to SecSign for your business.

Learn more about the options of on-premise use and your own customized ID App in your corporate design.

Download the plugin as cloud version for a free and convenient protection.

Documentation for the SecSign ID Identity Server interface for Two-Factor Authentication.

TWO-FACTOR AUTHENTICATION OVERVIEW

Table of contents

    Start right now! Questions?

    Feel free to get in touch with us if you need help setting up your SecSign ID plugin or to request a plugin for a not yet supported environment.
    CONTACT US

    1. SecSign ID API Server

    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.

    2. Authentication Process

    server api authentication

    • The user provides his SecSign ID via the internet service, which then sends an authentication request for the provided ID to the ID Server.
    • The ID Server sends a push notification to the user’s mobile device.
    • The ID Server sends an access symbol to the internet service.
    • The internet service displays the respective access symbol.
    • The user selects his SecSign ID on his mobile device and enters his PIN. The mobile app verifies that the user is the owner of the provided SecSign ID.
    • The ID server sends the access symbol to the mobile app.
    • The user confirms the correct access symbol and the mobile app passes it on to the ID Server.
    • The internet service checks the authentication session status.
    • The ID server verifies the access permission.
    • The internet service grants access to the user.This API documentation describes the communication between the client or web service and the SecSign ID server from the client’s view.

    3. Swagger Api Documentation with Endpoints

    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).



    4. Start the authentication

    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.

    REQUEST

    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
    ANSWER

    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="" />

    5. Request the Status of Authentication

    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).

    REQUEST

    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
    ANSWER

    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

    6. Abort or release Authentication

    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.

    REQUEST
    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
    ANSWER

    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

    7. Error Messages

    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

    8. Priority Codes

    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.

    9. Available APIS

    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.

    available_apis

    10. See for yourself

    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.

    Your own ID-Server

    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.

    your_own_id

    Why upgrade to SecSign?

    On-premise or in the cloud

    Choose between our SecSign ID Cloud or operate your own on-premise Two-Factor Authentication server.

    Easy customization

    Operate your own YourBrand ID app - Two-Factor Authentication customized to your needs.

    Ready-to-use SDK

    Integrate SecSign ID Two-Factor Authentication in existing apps with our ready-to-use SDK.

    Easy user management

    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.

    Cover all logins

    Integration in any login environment: web, local, VPN, remote desktop, mobile logins and many more.

    Plugins for all your needs

    No need for complex integration: we have plugins for almost all environments.

    SecSign 2FA