Skip to main content

Recent posts

Tutorial 3: Social login with OpenID Connect

In a previous tutorial we showed how AuthGuard can be used alongside an LDAP server for identity federation. In this example, we will achieve something similar but with an OpenID Connect instead.

Also applies to any OAuth 2.0 provider

In this tutorial we will focus on OpenID Connect providers but the same steps still apply to a regular OAuth 2.0 providers. The only difference will be the inclusion of an ID token.

Prerequisites#

  1. A standard AuthGuard distribution or a custom distribution with the JWT extension.

  2. Follow the guideline for the server setup.

OpenID Connect#

OpenID Connect is, in summary, an addition to regular OAuth 2.0 where the identity provider also provies and ID token which carries information about the user.

Scenario#

Our scenario will follow a regular Authorization Code flow and it goes as follows:

  1. Your client will make a request to AuthGuard to generate an authorization URL for a specific provider.
  2. Your application should follow the redirect and take the user to the authorization page of the identity provider.
  3. Once the user approves the authentication, they will be redirected back to your application or website.
  4. Ask AuthGuard to verify the state and exchange the authorization code with access and (optionally) ID tokens.
  5. AuthGuard will perform those actions and will return the tokens generated by the provider, as well as the account ID of the corresponding AuthGuard account if configured to do so.

Test Setup#

For this tutorial you will need to set up an OAuth client with an identity provider. For example, Google.

AuthGuard Configuration#

There are no special exchanges which need to be allowed in order for this to work. The only needed configuration is to add the providers. You can add as many as you want, as long as they unique provider names. For example, the configuration for Google OAuth will look something like this

oauth:
clients:
- provider: google
clientId: <your client ID>
clientSecret: <you client secret>
defaultScopes: ['openid', 'profile', 'email']
authUrl: https://accounts.google.com/o/oauth2/v2/auth
tokenUrl: https://oauth2.googleapis.com/token
authRedirectUrl: <your authorization redirect URL>
tokenRedirectUrl: <your token redirect URL>
accountProvider: true
emailField: email

Two things to note here:

  1. The default scopes may differ from provider to the next. Make sure that you know which scopes to use. For an OIDC-compliant provider, "openid" and "profile" scopes will be there. We added "email" scope since we will be used the user's email.
  2. If you want AuthGuard to create local accounts for users, then you can set "accountProvider" to true, and then specify which field in the ID token should be used as an email.

Social Login#

The social login process is broken into two steps: obtaining an authorization URL, then exchanging the authorization code returned by the identity server with usable tokens.

Authorization URL#

Obtaining an authorization URL can simply done by making a GET request to /oauth/auth_url?provider=<provider>. AuthGuard will return back an HTTP response of 302 and the "Location" header will have the URL for that provider. Behind the scenes, AuthGuard will generate a session and use its token as the state (nonce) token.

After redirecting the user to that login page, they will be asked to approve the authorization or not. If it was successful then the identity server will redirect them back to your application with a state, an athorization code.

Exchange the Authorization Code#

Now that you have an authorization code and a state token, you can call AuthGuard to perform the exchange and get access, refresh, and potentially ID tokens from the identity server. To do so, send a POST request to /oauth/authorize?provider=<provider>&state=<returned state>&code=<returned code>.

If the provider is also configured as an account provider then AuthGuard will create a social account for each unique user. The subject of the ID will be used as an external ID to link the two. If an account already exists, then AuthGuard will just retrieve the existing user.