Documentation for Drupal's OAuth2 Authentication Module

Purpose

OAuth2 Authentication allows users to log into your Drupal site authenticating against a remote identity provider (IDP) via OAuth2.

That is, if a user's credentials can be used to retrieve a valid access token, he/she will be logged into the site with those credentials and the token will be added to his/her session. If the user doesn't exist yet, it will be created.

Disclaimer

In doing this, we're making the assumption that resource requesters are actually resource owners. Generally, one shouldn't make that assumption as OAuth2 is an authorization mechanism, not an authentication mechanism.

If you found this module looking for a standard way to have users log in via OAuth2, then you should probably go with OpenID Connect instead. It provides a proper identity layer on top of OAuth2. Think of it like the evolution of SAML. This module is meant for those that don't have access to an OpenID Connect server, do have access to an IDP that speaks OAuth2, and can trust the environment in which all of it operates.

If you haven't considered the security implications of using this module, and you don't control the environment in which it's running, then you shouldn't be using it. For example, you probably don't want to do this sort of thing on a mobile environment as it can't be trusted to the same extent as a Drupal site behind a corporate firewall.

If you made it this far, and are still considering using the module, then make sure you've read and understood the following articles.

• Why OAuth it self is not an authentication framework?
• The problem with OAuth for Authentication

It also wouldn't hurt to study the official OAuth 2.0 Threat Model and Security Considerations.

Initial Set-Up

1. Install and enable the OAuth2 Client and OAuth2 Authentication modules as you would any other.
2. If you wish to override any of the methods in the OAuth2AuthenticationClient class to change the module's behaviour, create another class that extends it and implement the desired methods. This is best done in a custom module for your site, something like Sitename Authentication (sitename_authentication) where S/sitename is the name of your site.
3. Surf to the configuration page over at Home » Administration » Configuration » Web services » OAuth2 Authentication to configure your token endpoint. This section is mandatory while the others are optional. They contain sane defaults, but look over all of it to make sure it's what you need for your set-up.
4. If you subclassed OAuth2AuthenticationClient, replace the default class name in Miscellaneous Settings » Client Class with the name of your new class.
5. Hit the Save configuration button to save your settings.
6. Enjoy!

Notes

• When an existing local user logs in, the module will attempt to get an access token for him/her. On success, the token will be added to the user's session. On failure, the user will still be logged in, but will not get a token. Whenever a request to get a token is made, the results are reported in the log.
• Once you've got this set up, you'll have to ensure that the Web-services client module you're using supports the OAuth2 protocol (i.e. token access to resources). If you're already using one that doesn't, you'll have to add that support. Otherwise, go with one that supports this already.

Issues

Token Expiration

If the total expiration time for your tokens, including successive tokens returned by your token server through refresh tokens (RTs), is less than the maximum time a user can be logged in (see Session Expire for details), users will still be logged in when their final tokens expire.

As this module doesn't (yet) deal with that situation, you'll need to come up with a solution that meets your requirements. Some background information on this can be found over at Best-Practice for dealing with OAuth 2.0 Token expiration at the Consumer.

Options

• Automatically log out each user after being logged in for the token expiry time.
• Extend the token expiration time to the maximum amount of time a user can be logged in.
• Add support for refresh tokens (RTs) that can keep working until a user's login session expires.
• Have the token server issue tokens that don't expire.
• Some combination of the above.

Real-World Solutions

• Facebook: Access Tokens
• LinkedIn: Handling Errors & Invalid Tokens
• Box: OAuth2 update - Longer lived refresh tokens
• Salesforce: Understanding the OAuth Refresh Token Process

Helpful Drupal Modules

• Session expire (also explains the default login session length)
• Automated Logout
• Ejector Seat