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:
- Front channel - RP redirects the user to OP, and OP redirects user back to RP. The data is transferred using HTTP GET/POST parameters
- 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.
- 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.
- 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.
- 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
- Python - https://github.com/OpenIDC/pyoidc/
- Java - https://bitbucket.org/connect2id/oauth-2.0-sdk-with-openid-connect-extensions https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server/tree/master/openid-connect-client
- Ruby - https://github.com/nov/openid_connect
- Go - https://github.com/coreos/go-oidc
- PHP - https://github.com/jumbojett/OpenID-Connect-PHP
- ASP.NET - https://github.com/openiddict/openiddict-samples