Dev Overview of OpenID Connect
OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol, which allows clients to verify the identity of an end user based on the authentication performed by an authorization server or identity provider (IdP), as well as to obtain basic profile information about the end user in an interoperable and REST-like manner. OpenID Connect specifies a RESTful HTTP API, using JSON as a data format.
OpenID Connect is an increasingly common authentication protocol: when an app prompts you to authenticate using your Facebook or Google+ credentials, the app is probably using OpenID Connect.
OpenID Connect allows a range of clients, including web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users.
OneLogin provides a custom connector option that makes it easy to configure your OpenID Connect-enabled app to use OneLogin as the Identity Provider (IdP) in an OpenID Connect flow.
For more information about API authorization, see How to setup an API Authorization PoC.
Why Adopt OpenID Connect for my App?
OpenID Connect is easier to integrate than SAML, and it can work with a wider variety of apps. Specifically, it provides:
-
Easily consumed identity tokens
Client apps receive the user’s identity encoded in a secure JSON Web Token (JWT) called the ID token. JWTs are elegant and portable and support a range of signature and encryption algorithms.
-
The OAuth 2.0 protocol
Clients use OAuth 2.0 flows to obtain ID tokens, which work with web apps as well as native mobile apps. OAuth 2.0 also means that you have a single protocol for authentication and authorization (obtaining access tokens).
-
Simplicity with capability
OpenID Connect is simple enough to integrate with basic apps, while also offering features and security options that can meet demanding enterprise requirements.
Grant Types
OpenID Connect supports the following authentication flows:
- The Implicit Flow is required for apps that have no “back end” logic on the web server, like a Javascript app.
- The Authentication (or Basic) Flow is designed for apps that have a back end that can communicate with the IdP away from prying eyes.
- The Resource Owner Password Grant does not have an login UI and is useful when access to a web browser is not possible.
- The Client Credentials Grant is useful for machine to machine authorization.
Implicit Flow
The Implicit flow is required for apps and websites that have no back end logic on the web server, and everything that is passed between the app or site and the IdP can be viewed using browser development tools.
In the Implicit flow, a public/private key (JSON Web Key or JWK) scheme is used to encrypt or sign user details. When you register your client app with the IdP (OneLogin), you will receive a client ID and a client secret. In an Implicit flow, the client secret should never be exposed.
In Step 1, the user attempts to start a session with your client app and is redirected to the OpenID Provider (OneLogin), passing in the client ID, which is unique for that application. In Step 2, the OpenID Provider authenticates and authorizes the user for a particular application instance. In Step 3, user details are encoded by the OpenID Provider into an id_token (JWT) that contains user information (scopes, in OAuth terms) and signature (using RS256), which is passed to a preconfigured Redirect page on the web server. In Step 4, the client app confirms the JWT id_token and confirms the signature using the public key. If everything is fine, a session is established for the user.
In the Implicit flow, the transaction is secure despite the fact that everything is passed in the “front end” and the client app cannot be authenticated, because the IdP sends tokens encrypted using a public/private key scheme and will only send tokens to the preconfigured Redirect URI. In other words, someone could steal the public key and client id, but that doesn’t matter, because only the IdP has the proper information (the redirect URI for the intended client app and the private key) to use the public key and client ID correctly.
Authentication Flow
The Authentication (or Basic) flow is an option for apps that have web-server logic that enables back-end communication with the IdP (OneLogin). It functions like a traditional three-legged OAuth flow and results in a traditional OAuth access token being returned in secret to the web application via calls made on the back end. In this flow, rather than transmit the user details, the provider sends a special, one-time-use code that can be exchanged by the back-end web service for an OAuth access token. This exchange needs to include the client id and client secret in addition to the code, just like a traditional OAuth 2.0 flow. It is more secure than the Implicit flow, because tokens are not visible through the browser and the client app can also be authenticated.
In Step 1, the user attempts to start a session with your client app and is redirected to the OpenID Provider (OneLogin), passing in the client ID, which is unique for that application. In Step 2, the OpenID Provider authenticates and authorizes the user for a particular application instance. So far, it looks like the Implicit flow. But in Step 3, a one-time-use code is passed back to the web server using a predefined Redirect URI. In Step 4, the web server passes the code, client ID, and client secret to the OpenID Provider’s token endpoint, and the OpenID Provider validates the code and returns a one-hour access token. In Step 5, the web server uses the access token to get further details about the user (if necessary) and establishes a session for the user.
Getting Started
To configure OneLogin as the IdP for your OpenID Connect-enabled app, you must:
Postman Collection
Replace sample variables indicated by {{ }} with your actual values.
Download for the OpenId Connect API
Have a Question?
Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.
Found a bug? Submit a support ticket.
Have a product idea or request? Share it with us in our Ideas Portal.
