OAuth 2.0 Integration

Use SecSign ID OAuth 2.0 two factor authentication on your OAuth 2.0 project with an easy and highly secure user login using iOS or Android mobile devices as well as for desktop use.


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.


Most websites and applications offer the possibility to connect accounts with existing social media accounts for posting automated content, import contacts or profile information. Those websites and applications use the authentication and authorization standard OAuth2.0 (RFC 6749).

A website using the service of another application, for example posting a Bitly link on your twitter stream, should use OAuth instead of asking for a password. OAuth is a authentication protocol that allows for the interaction between two applications without revealing the login credentials.


    SecSign ID is a plugin for real two-factor authentication (2FA) for web sites and applications. 2FA adds another layer of security to your website by using a second token. In this case the physical token is your smartphone.

    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.

    1. OAuth 2.0 Operating Mode

    OAuth2.0 can only be used for authorization, not authentication, though the user needs to authenticate himself to the provider to be able to proceed with the authorization.

    Thus, the authentication is an essential step during the authorization, but it is not provided by OAuth.

    The OAuth transaction includes three main parties:

    1. User
      The end-user or entity, the owner of the specific resource
    2. Client (OAuth Consumer)
      The program or app using the resource after authorization
    3. Server (OAuth provider)
      The entity providing or hosting the specific resource

    This construct is also referred to as “OAuth Love Triangle”.

    1.1 Authorization process

    In the following example we introduce Alice as User, Bitly as OAuth consumer and Facebook as OAuth provider holding Alices’ secured information (the Facebook profile).

    Alice would like to use her Facebook data for the Bitly registration process. That’s how it works:

    Step 1: The user expresses her intent

    Alice (User): ”Hi Bitly, could you please get all the information you need from my Facebook profile?”
    Bitly (OAuth consumer): “Great! I’ll ask you for your permission in just a bit!”

    Step 2: The consumer receives the permission

    Bitly: “Facebook, a user would like to use her profile data for a registration. Could I get a request-token?”
    Facebook (OAuth provider): “Of course! Here’s the token and a secret.”

    The secret is required to prevent forged requests. The consumer uses the secret to sign requests. This way the service provider can verify the consumer application as the source for the request.

    Step 3: The user is forwarded to the service provider

    Bitly: “OK Alice, I am forwarding you to Facebook to verify the activity. Take this token.”

    In case Bitly was an untrustworthy provider it could use a popup-window that appears to be from Facebook but is in fact a phishing page to get Alices’ Facebook information. Make sure the URL the provider is forwarding you to is in fact the service provider (in this case Facebook).

    Step 4: The user grants permission

    Alice: ”Facebook, I’d like to authorize this request-token from Bitly.”
    Facebook: ”Alright. Just to be sure: You’d like to allow Bitly to access the following data from your Facebook profile: Email-address, Name, …?”
    Alice: “Yes!”
    Facebook: ”Ok. Could you please return to Bitly and tell him to use his request-token now?”

    Step 5: The consumer receives the access-token

    Bitly: ”Facebook, can I exchange my request-token for a access-token?”
    Facebook: ” Sure! Here is your access-token and a secret. ”

    Step 6: The consumer accesses the protected resources.

    Bitly: ”I’d like to get the profile data from Alice. Here is my access-token.”
    Facebook: ”There you go: Alices’ data…”

    bitlylogin

    contiuneasalice

    1.2 Grant Types

    Consumer login credentials

    The consumer has to be registered with the provider. Generally, basic information like name of application, website and similar have to be provided to the provider. Also, an URI (TLS secured) has to be registered for Web-server, browser based or mobile applications to, after successful confirmation with the provider, transfer the user back to the consumer.

    After the consumer registration a public client ID and a secret is provided for example for regulating API-access authorization on the provider page.

    The first step of an OAuth2 Authorization is to receive permission from the user. Generally, for browser-based and mobile applications an interface with the service for the user is provided for this. OAuth 2 offers some “grant types” for different use cases:

    Authorization Code

    In case of the authorization code the user uses the OAuth provider login and releases his data. The provider sends an authorization code when the user is transferred back to the consumer. The authorization code together with the client-ID and a password act as login credentials. Based on this information a access-token is issued by the OAuth provider.

    Implicit

    An implicit authorization differs only slightly from using an authorization code while having a less complex communication process. After logging in with the OAuth Provider a authorization code and access-token is issued.

    Password

    Release of the password by the owner of the data: In this case the consumer receives the login credentials for the provider. This method is very risky and requires a high degree of trust for the consumer.

    Client credentials

    This method is used in case the consumer application needs information on the OAuth provider that do not have an owner.

    1.3 Access Token: Bearer or MAC?

    Most OAuth implementations are based on the OAuth2.0 Bearer-token (RFC Standard). The OAuth2.0 Bearer-token profile offers a simplified regulation for authentication.

    This specification describes how Bearer-token can be used in HTTP- requests to access OAuth2.0 secured resources. The Bearer-token has to be secured with SSL/TLS. If HTTPS is not an option, Bearer-token can not be used. In this case, MAC-token present an alternative. The primary purpose of MAC-token is the protection of the HTTP-authentication in cases where SSL/TLS can not be used.

    Neither the client nor the OAuth consumer control the token-type. The authorization server decides on which token-type to use in Step 2, when the access-token is returned. The access-token provides all necessary information to the OAuth Consumer to inquire a secure request for a resource (together with type-specific attributes). Every access-token type definition defines additional attributes that are sent to the OAuth consumer, additionally to the “access_token” response parameter.

    OAuth2.0 mainly consists of three phases:

    1. Authorization Grant
    2. Exchange of the authorization grant for an access-token
    3. Access to the resource with the access-token

    So where does the token-type come into play?

    Example for a response with the access-token (Bearer):

    The access-token identifies the MAC-key (=MAC-key-ID) which in turn calculates the MAC-value of the request. The actual key is, in contrast to the Bearer-token-profile, hidden to the consumer. Typically, the server allocates a specific time frame to every set of MAC-login-credentials.

    Example for a response with the access-token (MAC):

    The MAC-access-token has two additional attributes. mac_key and mac_algorithm. The mac_key is a combined symmetric key, mac_algorithm describes the algorithm to be used.

    In Step 3 a specific resource is requested with the access-token

    With a Bearer-token only the access-token from the authorization server from step 2 has to be transferred:

    With the MAC-token-profile the consumer needs to send some more information:

    1. id is the MAC-key-ID or the access-token from step 2
    2. ts is the time stamp of the request (elapsed seconds based on fixed time point, integer). This value is unique in all requests with the same time stamp and MAC-key-ID.
    3. Nonce is a distinct character string generated by the consumer. The value is unique in all requests with the same time stamp and MAC-key-ID combination.
    4. mac is calculated by the consumer from the MAC algorithm and the MAC key

    The MAC value is a constant, reproducible linking of several HTTP-request-elements in a single string. It consists of the following information: time stamp of the request, the nonce value, the HTTP-request method (HEAD, GET, POST,..), the HTTP request URI (defined in RFC2616 chapter 5.1.2.), host name, port, value of the optional request header field attribute “ext”.
    Every single element is followed by a line feed character (%x0A). The string is then hashed with the algorithm defined under the mac_algorithm.

    The implementation with the MAC-token-procedure is way more complex for both the consumer and the OAuth provider. However, it provides a method in case the key can not be transferred directly, as with the Bearer-token-procedure. If the data transfer is secured with SSL/TLS, the simple Bearer-token is generally preferred.

    2. Advantages and disadvantages

    In the previous example Alice never needed to release her Facebook login credentials to Bitly. She simply delegated the access safely via OAuth. Alice can login to Facebook any time and review access rights as well as remove tokens for certain applications without effecting other.

    Also, OAuth allows for detailed degrees of authorization. This way she can allow Bitly to post on her Facebook account while restricting LinkedIn to “read only”.

    OAuth is a robust solution for browser-based applications and an immense improvement to the HTTP basic authentication. Still, there are some issues in the development of the consumer or the provider that render the system vulnerable.

    Normally, the third-party-app or the consumer never have access to the login-credentials of the user. Still, sensible user data may be transferred under specific circumstances. One example for a transfer like that is a bank-app. Account number, addresses and transactions can be viewed or transactions can be initiated. Providing those information one has to ensure 1) a secured transfer and 2) that the app does not store the information. As soon as the provider releases the data it is unable to control the sensitive data, eventually presenting a legal issue, too.

    An untrustworthy app could sell the collected addresses, pass on account information and evaluate banking transactions, even if they don’t know the login-credentials. Thus, from a providers point it is not recommended to allow the consumer dynamic or automatic access to the API. Consumer have to register manually with the provider and award specific callback URI’s before initiating the first API request. After the verification the consumer receives the consumer credentials from the provider and may initiate requests to the API.

    Since OAuth only takes care of the authorization but does come in touch with the authentication, user data are vulnerable to attacks. An untrustworthy consumer may try to obtain provider login-credentials of the user by phishing. A way to prevent this kind of attack is a two-factor authentication provided by the provider to eliminate password based login-credentials (see 4). If no optional parameter is presented (‘state’ with random hash), user accounts may be taken over via CSRF (Cross-Site-Request-Forgery). Since parameter are optional they are mostly neglected. To prevent covert redirects or open redirects the provider needs to verify the callback-URL for previous registration by the consumer.

    Thus, when developing a OAuth Provider it is important to prevent possible exploits to protect the resources and user accounts from fraudulent use.

    3. OAuth in combination with 2FA

    To prevent phishing attacks we use the the SecSign ID two-factor authentication to authenticate the provider.

    OAuth is a good starting point to grant third-party provider access to resources. However, OAuth only regulates the authorization, not the authentication.

    Provider with a password based authentication are vulnerable to attacks by untrustworthy consumers trying to steal login-credentials for the provider from careless users. One way is the simulation of an OAuth activity by presenting a popup-window that looks like the provider (for example Facebook), but is in fact a phishing page. If the user does not verify the validity of the page and enters the Facebook login-credentials he sends them directly to the consumer. The user needs to verify that the URL he is forwarded to is in fact the provider (in this case, Facebook).

    This problem can be avoided by the provider offering a real two-factor authentication (for example SecSign). The registration without a password protects the user from theft of his user login-credentials. SecSign solves the problem of user login-credentials by using the Challenge-response-authentication with 2048-Bit RSA key pairs. Passwords become unnecessary and sensitive data are neither transferred nor stored. That means that hacker can not attack user accounts since there are no passwords that can be stolen.

    The two-factor authentication method utilizes the mobile device (something, that is in the possession of the user) and the knowledge of the user (the PIN for the identity verification). For the log-in the user simply provides the SecSign App user name and is presented with a symbol. The user then chooses his SecSign ID in the App and provides the PIN. By choosing the correct symbol in the app the user is forwarded to the specific provider.

    4. Example for the implementation with PHP

    The following example shows the implementation in a specific scenario.

    • Website A / OAuth Provider:
      The website the access should be granted to. Every user has a personal profile and can save a note
    • Website B / OAuth Consumer:
      The application enables the publication of notes. The Consumer offers the option to retrieve notes
      from website A and to publish them

    How can Website B access the user data from Website A without asking for the user name and password?

    This is where OAuth can be used. OAuth enables Website B to access data (provided by API) from Website A, without the user ever having to provide his login-credentials.

    4.1 Preparation

    The following information can give an idea about how to realize a OAuth2 Server or OAuth Provider.

    To prevent phishing attacks we deploy the SecSign ID two-factor authentication for the authentication at the provider. Also, the session is hashed at the consumer and a state variable is transferred to the provider to prevent CSRF attacks.

    Our example refers to a local test environment for the provider and the consumer. Since the integrated PHP Server are single threaded, two instances have to be created to enable the provider and the consumer to communicate at the same time.

    Please consider, that this example uses a Bearer-token, which has to be protected with SSL/TSL. This can be neglected with a local test, in a productive environment certain safety measures need to be employed to ensure, besides others, the communication via SSL/TLS or MAC-token.

    This article shows the necessary steps and files to develop and test an OAuth Provider with 2FA and an OAuth Consumer.

    Get the source code

    Create a new folder for the provider and start the web server:

    Open the new console/terminal and create a new web server authority for the consumer:

    Composer is required for the following steps. Composer is a package manager which installs dependencies for a PHP program, for example libraries.

    4.2 OAuth Provider (Server)

    The following example gives an idea how to realize an OAuth2 Server or OAuth Provider. We are going to use the OAuth2-server-php PHP library for easy access to all functions. An overview about different libraries and languages are available here.

    1. Install dependencies and prepare the database

    Dependencies are installed using composer install. We are using OAuth2-server-php and secsignphphelper, which allow for simple use of the two-factor authentication.

    Switch to the secsign-provider register and create composer.json:

    Use the following table to create the standard databases (MySQL, SQLite, PostgreSQL or MS SQL Server):

    2. OAuth2 Server

    In the next step the OAuth2 Server-object needs to be created and configured. The server object will be used in all end points of the application.

    server.php :

    3. Token Controller

    The next step is the creation of the token controller. This URI will return the token to the consumer.

    token.php:

    An OAuth consumer or OAuth Client (consumer1) was already registered with the provider when creating the database. The following command can be used in the prompt to test the token controller:

    An access-token should be received:

    4. Resource Controller

    resource.php:

    After creating the tokens we can now validate them.

    The resource controller is responsible for issuing the notes. In the next step we are going to create the controller for the authorization which will return a distinct code to the user if the login was successful.

    The consumer can now use its credentials and the user code to request a token. An access-token is issued from the token controller to the consumer if the request is successful. The access-token is forwarded to the resource controller to retrieve the note.

    The resource controller validates the token and verifies that the token is connected to a user. The note is sent to the consumer if the verification is successful.

    5. Controller for the authorization

    The controller for authorization allows an user to approve third party applications. Instead of assigning the access-token directly (as with the previous token-controller example) an authorize-controller is used. The authorize-controller only assigns a token if the user approved the request.

    authorize.php:

    The following URL shows the authorization form. If a user logs on with the SecSign ID two-factor authentication he (in this case automatically) confirms the release of his note to consumer1:

    The authorization code can be used to request an access-token:

    If the request was successful, an access-token is released. This access-token can be used to request the actual user resource (the note):

    4.3 Oauth Consumer (Client)

    The following example gives an idea on how to realize the OAuth2 client or OAuth Consumer. In the previous examples the provider was operated manually, now a basic sample consumer is used. Error reports and similar were neglected to give a simple overview of the consumer mode of operation.

    The consumer only consists of the index.php:

    By requesting http://localhost:8089 in the browser the landing page of the consumer is displayed. After selecting the link for transferring the note you are forwarded to the provider. The authentication with the SecSign ID and the OAuth Authorization take place simultaneously. If this step was successful, you are transferred to the consumer, who then requests an access-token. After the access-token is available, the note can be requested. In the next step the note can be processed further and saved. In this case the note is simply issued by the consumer.

    Keywords: 2 factor authentication OAuth, Two-factor authentication OAuth, 2fa OAuth, How to use OAuth, How to integrate OAuth, OAuth php

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

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

    Do NOT follow this link or you will be banned from the site!