This article is about my newest development of an easy-to-use lightweight implementation of OpenID Connect (OIDC) in C# to authenticate against Google. It does not require any additional libraries or frameworks other than .net Framework 4.0 or above. Google recently announced that their OpenID2.0 authentication is deprecated and will be shut down by April 20, 2015 so it is time to move on!
Why do you need to move?
If you haven't used authentication against Google, you may want to move on to the next chapter. However, if you have, you may have noticed the warning messages already stating:
Important: Google has deprecated OpenID 2.0 and will shut it down after a migration period. If your app uses OpenID 2.0, you must migrate your app by the shutdown date April 20, 2015, as shown in the
migration timetable.
About four years ago, I published an article about "Using Google OAuth in asp.net" and of course used it myself. Because of the upcomming shutdown, I needed to find another solution.
Google provided lots of sample code and libraries for several programming languages including C#, but the reason I have decided to create my own one, was not only that I wanted to have an atomic lightweight implementation and but also curiosity. Maybe mainly curiosity ;-)
What do I need to get the job done?
- Microsoft .net4 Framework or above (it might even run on Mono, who knows?).
- Download the library and the sample.
- You need to register a web application project and configure it at Google Developers Console in order to obtain API client credentials.
- Optional: If you want to obtain information from Google+ you need to set the scope to OpenID, Email and Profile. You also need to activate the Google+ API. 10000 requests per day are for free, however, if you exceed this number, you will need to activate payments at Google.
For demonstration purposes, I used the internal "Visual Studio Development Server" running on localhost port 43517. In my sample WebApplication I've created an IHttpHandler called "OAuth2CallbackHandler" that receives the response from Google under the URL http://localhost:43517/oauth2callback which is the URL I've setup as the Redirect URI in my Google project.
Make sure to configure the project at Google correctly and match the configuration with your application.
In web.config of the sample WebApplication you need to configure the ClientID and ClientSecret and the GoogleRedirectURI. You may want to configure a proxy server or want to change the authentication callback url.
You may want to customize the logon screen with your own logo and corporate identity:
Receiving Google+ Information (Optional)
Besides the information in the IDTokenPayload (which already includes the email address), you can additionally request more information from Google+.
If you are intending to access user information from Google+, you need to set the Scope to OpenID, Email and Profile in the AuthenticationRequest entity.
Futhermore, it is important that you activate the Google+ API in your developers console!
You can send up to 10000 requests per day for free. If you exceed this number you will end up receiving 403 error codes (permission denied) or you need to setup a payment plan at Google.
How does it work?
I've developed this library according to this Google documentation:
developers.google.com/accounts/docs/OpenIDConnect
The library exposes one major class "Amon.cc.Oidc.Authentication.AuthenticationUtility" that handles the request and the response.
The AuthenticationUtility has these three public static methods:
- Authenticate()
- Authenticate(AuthenticationRequest request)
- HandleResponse()
Authenticate()
Authenticate() is an overload for Authenticate(AuthenticationRequest request) using the OpenID and Email scope by default.
Authenticate(AuthenticationRequest request)
This method initiates the authentication against Google.
- Gathering all required properties for the authentication process, such as clientID, clientSecret, scope etc.
- Setting up a CSRF token including storing a cookie.
Google highly recommends to using a CSRF token for security reasons.
- Setting up the state parameter, where you put in every kind of state you want into it, it will then be sent back after the authentication process.
- Redirecting to Google to authenticate and by doing that, terminating the current request.
HandleResponse()
After being redirected back from Google, there is either a "code" or an "error" parameter, regardless of error or success, the "state" parameter is always posted back. Google will always redirect back to the configured redirect uri. The HandleResponse method needs to be called on that target site or handler in order to obtain the requested values.
- Verification of the CSRF token.
- Checking if errors were posted back.
- Downloading, parsing and caching the Discovery Document for the authentication, jwks (Json Web Keys), token-endpoints.
- Exchanging the "code" at the token endpoint in order to receive the token response.
- Verifying the signature of the token.
- Decrypting the token using RSACryptoProviders created by the JWKs.
- Deserializing the IDTokenPayload to TokenInformaion.
- Optional: Receiving user information from Google+.
- Return the AuthenticationResponse with the state, the IDTokenPayload and the user information, the latter is optional.
Class Diagrams
As you can see, the AuthenticationUtility class is simple and easy to use and the only one that is public besides Entities and Exceptions.
See all class diagrams in full size:
Download the source code
Feel free to use this open source library licensed under the conditions of the "Creative Commons By 3.0 AT" for all of your applications.
I have uploaded the C# class library "Amon.cc.Oidc.Authentication" to github, including a very basic ASP.NET4 WebApplication that demonstrates how to use this library with Forms Authentication.
Looking for more?
As I mentioned before, this is a lightweight implementation of OIDC with Google. You may want to have a look at their code samples and libraries, the Thinktecture.IdentityServer.v3 or Microsofts OWIN security components in ASP.NET: OpenID Connect!