Creating an OAuth-Based Handler

Note: For OAuth 2.0 based logins, administrators can normally use the "Other OAuth 2.0" option when creating a Login Method and provide more details in settings. However, you might want to implement a complete Login Handler to allow ease of setup or to provide additional options and features.

Note: This documentation assumes familiarity with common terms and concepts used by OAuth.

To make a Login Handler which uses OAuth, first change the class you have already written to extend one of these classes instead of \IPS\Login\Handler:

• \IPS\Login\Handler\OAuth2 for OAuth 2.0 (all grant types supported)
• \IPS\Login\Handler\OAuth1 for OAuth 1.0 (only 3-legged OAuth supported flow)

Implementing these classes will automatically add a number of settings to allow the administrator to provide a client ID, client secret, and to control syncing for display names and email addresses/ 

You will then need to implement a number of methods:

• For all OAuth versions:
  • authorizationEndpoint() should return the authorization endpoint URL - note that you may want to pass an additional parameter for AdminCP or reauthentication logins to provide additional security in those contexts.
  • authenticatedUserId() should return the user ID of the authenticated user based on the access token passed. Note that for OAuth 2.0 an access token is passed, and for OAuth 1.0 both an access token and access token secret is passed.
  • If supported, additional methods to get additional information about the authenticated user based on the access token passed:
    • authenticatedUserName() should return the display name - you may want to add a setting to control if this is used or what kind of name is used (as is done for most of the built-in OAuth-based login handlers).
    • authenticatedEmail() to return the email address
• For OAuth 2.0 only:
  • tokenEndpoint() should return the token endpoint URL
  • grantType() should return the grant type to use (in most cases this will be "authorization_code").
  • Optional: scopesToRequest() should return an array of scopes to be requested.
• For OAuth 1.0 only:
  • tokenRequestEndpoint() should return the token request endpoint URL
  • accessTokenEndpoint() should return the access token endpoint URL

If the grant type you are using is button-based (which will usually be the case) you can also use the methods described in Creating a Button Handler to control the look of the button.

For an example of how to implement these methods, see one of the built-in OAuth-based login handlers.