CONTACT US GET A DEMO

OAuth 2.0

 

Action Required: References to the /ministryplatform/oauth/ will no longer be supported after access to the Legacy version of the Platform is removed. This may be a breaking change, so if you have custom development that references this value, be sure to replace it (see below) before saying goodbye to legacy.

Open Authorization (OAuth for short) is the industry standard for token-based authorization on the internet. MinistryPlatform supports several OAuth 2.0 workflows and also serves as a Security Token Service (STS) provider. MinistryPlatform is also a client and can support other token providers such as Facebook or Google.

Discovery

The discovery URL can be found by adding an "OAuth" subfolder to the Ministry Platform URL. Important: Replace the current Discovery URL with the new next generation friendly URL ASAP.

Current, Soon-To-Be Invalid Discovery URL
https://example.ministryplatform.com/ministryplatform/oauth/
New Next Generation Friendly Discovery URL
https://example.ministryplatform.com/ministryplatformapi/oauth/.well-known/openid-configuration

The discovery URL will display various end-points, scopes, and response types supported by MinistryPlatform's OAuth implementation.

General Use

  • User chooses to login using STS provider
  • User is redirected to provider’s login page
  • STS provider authenticates user
  • User is redirected back to original application along with an Access Token
  • Access Token is passed in Authorization Header of each subsequent request in order to gain access to Resources

OAuth and MinistryPlatform

  • MinistryPlatform acts as an STS provider
    • Login using the platform's login UI
    • Get an Access Token using the platform
    • Utilize OAuth workflows using the platform
    • Authorization uses existing Security Roles to determine access
  • MinistryPlatform acts as an STS consumer
    • Configure the platform to login using Facebook (and other OAuth providers)
    • Theoretically, login to Facebook using the platform!
  • BatchManager and CloudTools
    • Use Client Credentials workflow
    • Authorization uses existing Security Roles

Workflows

Client Credentials
  • Allows client applications to have access without storing a user name or password anywhere
  • Can be used to provide data to an end-user whether they are logged in or not
  • Best choice for 99% of your application development
  • Client-specific user assignment

See API & Identity Pages  and Giving Developers Access

Implicit Grant
  • Can allow applications to be developed entirely in client-side JavaScript
  • Assumes end-user has significant rights within MinistryPlatform
  • Access Token belongs to the end-user
Authorization Code
  • Similar in end-user experience to Implicit Grant
  • Redirects user to the authorization server
Resource Owner
  • Assumes your client application has (or can collect) the end user’s credentials
  • Could be used like Client Credentials if you have a safe place for your application to store the user name and password (not recommended)

See Administering Users and Working With 3rd Party Developers

See Also

Additional Documentation