This documentation will outline how a client application can use OAuth2 to request an access_token in order to make API requests on behalf of an end-user, how to use a token once you have one, and how to refresh a token once it expires.
What is OAuth2?¶
OAuth2 is a way for third-party client applications to request authorization to act on behalf of an end-user without requiring the user to expose their username and password. The client must direct its users to a page within MediaCore where the user approves the client to act on its behalf. Once the user has approved the client application, the application will receive an access_token.
What is an access_token?¶
An access_token is like a temporary password that allows a client application to “log in” as a user and perform actions on their behalf. Each token can be limited to a specific subset of the permissions that a user has, called a scope (see Scopes).
Tokens are passed through the Authorization header. If you had, for example, a token token1234, the header would look like this:
Authorization: Bearer token1234
Because tokens are included directly in the request headers, you must always use HTTPS!
How can I get an access_token?¶
Your client application can request an access_token for an end-user by redirecting that user to an authorization page within MediaCore. Once the user either approves or denies your authorization request, they will be redirected back to a preconfigured callback URL within your client.
The exact process will vary depending on the type of client application. For detailed walkthroughs, refer to Authentication Flows.
Why is all this complexity necessary?¶
In general, OAuth is very useful because it allows third-party applications to gain limited access to perform actions as an end-user. The user can rest easy knowing that the application can only perform the actions that the user authorized, so you can use an application to read content without risk of it accidentally overwriting your content. This is especially important for site administrators who have a great deal of power.
For MediaCore, OAuth is particularly crucial because many MediaCore users log into MediaCore via an external SSO provider (e.g. via Google Apps, or via their University’s Shibboleth server). Many of these SSO providers require users to log in using their web browser, and MediaCore’s integration with these SSO providers is entirely encapsulated within MediaCore’s web-based login flow. OAuth allows client applications to be ignorant of the incredible complexity of all of MediaCore’s SSO integrations.
The following are complete walkthroughs of the authentication process for each distinct kind of client application:
- Server Authentication Flow
- Native/Desktop Authentication Flow
- Client/JS Authentication Flow