OAuth 2.0 Apps
OAuth 2.0 Guide
When interacting with the Bynder API, your OAuth application will allow your users to access Bynder services and data. In order to achieve that you need each one of your users to authenticate with Bynder through your OAuth application to both verify their identity and generate access tokens which allow them to access their data on Bynder. Previously Bynder only offered the OAuth 1.0a authorization framework to provide authorized access to the Bynder API but we have seen a tremendous growth and demand in integrations and want to offer the newest standard OAuth 2.0 (https://tools.ietf.org/html/rfc6749).
OAuth 2.0 is an authorization framework and the industry-standard delegation protocol that enables third-party applications to obtain access to services. Bynder OAuth Apps allow you to generate access tokens that provide authorized access to the Bynder API in order to request Bynder assets or other available data. The OAuth 2.0 service will generate an access token based on the OAuth App’s scopes and the user's permissions and the API will then validate the request based on the available scopes and user permissions in the access token.
OAuth 2.0 Flow
Obtaining an access token is accomplished by following the OAuth 2.0 authentication flow. That simply refers to the steps taken to obtain an access token. The OAuth 2.0 specification formalizes a number of these flows referred to as grant types. The OAuth 2.0 standard specifies four grant types to obtain authorized access: authorization code, implicit, resource owner password credentials and client credentials.
With OAuth Apps we at Bynder have implemented the Authorization Code Grant Flow which is used by confidential and public clients to exchange an authorization code for an access token.
The flow process includes four actors:
- Resource owner: a Bynder end-user who has access to certain resources like assets, guides, workflow jobs, etc.
- Resource server: the Bynder server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.
- Client: the application making protected resource requests on behalf of the resource owner and with its authorization.
- Authorization server: the Bynder Authorization server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.
The Authorization Code grant type is suitable for regular web applications. The resource owner initiates the flow and will be redirected to Bynder’s Authorization server. The Authorization server will ask the user to login via the new Bynder login page https://YOURdomain/v6/login-provider/login using username/password credentials or if available via SSO.
Upon successful authentication the user is redirected to the redirect URL previously specified and the application can get the authorization code included in this URL and use it to request an access token.
The OAuth Scopes define what resources can be requested using that access token in an API call (e.g. all assets a given user can view). These scopes are passed to the Authorization Server during the authentication flow and the user needs to consent to them for these scopes to be granted and included in the access token.
Since the access token has an expiration date of one hour, our Authorization Server offers the possibility to refresh the token. Thereby OAuth applications developers can implement logic to continuously refresh the access token. In order for a refresh token to be generated and retrieved by the Authorization Server, the “offline” scope as to be requested. Bynder’s OAuth 2.0 implementation also offers a procedure to revoke refresh tokens as part of the OAuth 2.0 standard via the settings page.
Scopes for OAuth Apps
An OAuth access token can have various levels of permissions to access data via Bynder’s API. OAuth scopes let you specify exactly what type of access you need and thereby limit access for access tokens. We defined scopes as high level access to API resources in terms of read and write (e.g. asset:read). If the user has consented to the asset:read scope the granular permission on what assets this user can access will apply by the resource server. Scopes do not grant any additional permissions beyond the ones the user already has.
A full list of which scopes you need to access Bynder’s API resources is shown in the API documentation.
Types of Tokens
- Access Tokens
- JWTs containing user scopes and permissions.
- Expire in one hour.
- Refresh Tokens
- Can be used to generate new Access Tokens.
- Do not expire (permanent) and can be revoked via the OAuth App Settings page.
Create OAuth App
A detailed admin guide can be found here: https://help.bynder.com/system/create-oauth-apps.htm
In short you need to be a user with permission`Access & manage OAuth Apps` to access OAuth Apps via your Bynder portal settings.
Create your client by defining: Application name, Homepage URL, Application description, Authorization redirect URIs, Set HTTP access control (CORS) and select the OAuth scopes your app needs.
Use the Bynder SDKs where we implemented OAuth 2.0 for you to get kick started with your integration.