Single Sign-on using OpenID Connect

What is OpenID Connect (OIDC)

OpenID Connect (short - OIDC) is a simple identification layer built on top of OAuth2 protocol. OIDC is useful for centralizing authentication of your webapps (both traditional and new-style single page apps) and is suitable for mobile and destkop application as well. Compared to plain OAuth2 OpenID Connect has additional security measures. Besides identification OpenID Connect provides an API to obtain various information about the users. OpenID connect is developed by the OpenID Foundation which provides specifications for various parts of the protocol.


All AuthMachine instances list OpenID Connect endpoints at /.well-known/openid-configuration/ URL. If you are familiar with OpenID Connect protocol you can use that straight away - AuthMachine has been certified as 100% compliant with OIDC specifications.


OpenID connect uses the following main terms:

  • OP (OpenID Provider) - authorization server, which stores information about users, provides the capability for users to log in and give their consent to share their information with the parties which request such information. In our case, the OP is AuthMachine itself.
  • RP (Relying Party) - an application (web, mobile or desktop) which requests an OP to authenticate the user and provide information about him. In our case, RP is your application, which you would like to integrate with AuthMachine.
  • Authentication Flow - a sequence of request-response procedures which occurs between OP, RP and the user during the authentication.

OIDC Authentication Flows

During the authentication process, OP and RP must communicate in some way. OIDC defines two ways of communication:

  1. Front channel - RP redirects the user to OP, and OP redirects user back to RP. The data is transferred using HTTP GET/POST parameters
  2. Back channel - RP sends a REST-style request to OP and gets the data it requested in the response. This request isn't visible to the user.

OIDC defines 3 types of authentication flows.

  1. Basic Flow (aka authorization code flow). RP redirects the user to the authorization endpoint of OP. OP performs user identification and redirects the user back to RP with authentication code attached. Then RP uses the received authentication code to obtain user information (id token, access token, refresh token). This flow is a mixture of front and back channel data transfers.
  2. Implicit Flow. RP redirects the user to the authorization endpoint of OP. OP performs user identification and redirects the user back to RP with the userinfo attached. Only the front channel of data transfer is used in this flow.
  3. Hybrid Flow. RP redirects the user to the authorization endpoint of OP. OP performs user identification and redirects the user back to RP with authentication code and user information attached. The authentication code can be used to retrieve userinfo and refresh token. As you can see, this flow is a combination of Basic and Implicit flows.

Here's a comparison of the flows from the OpenID Connect core spec:

Property Auth Code Flow Implicit Flow Hybrid Flow
All tokens returned from Authorization Endpoint no yes no
All tokens returned from Token Endpoint yes no no
Tokens not revealed to User Agent yes no no
Client can be authenticated yes no yes
Refresh Token possible yes no yes
Communication in one round trip no yes no
Most communication server-to-server yes no varies

Choosing an appropriate flow

When choosing the best flow you need to consider what type of data transfer is preferrable for you. If you have a traditional web app you can go with the basic flow. The app can issue the userinfo request and store the received tokens in the user's session. The availability of the refresh token makes possible to request new access tokens when they expire without asking the user to re-authenticate. It's also the most secure flow cause the amount of data exposed to the user is minimal - most communication is done on the back channel.

The implicit flow is the simplest one. It uses exclusively the front channel of the data transfer, and thus is usable in applications without server-side backend like mobile or desktop apps. On the other hand, this flow isn't secure enough to transfer long-lived refresh tokens, so you have to re-authenticate the user when the access token is expired.

The hybrid flow is the most complex flow, which is designed for complex apps which require authentication on the front-end and back-end side. Using the hybrid flow you can quickly get the access and id tokens at your front-end while leaving the possibility for the back-end side to retrieve a long-lived refresh token.

Existing client libraries


Last updated on Apr 21 2019