Authentication Using OAuth 2.0

What is OAuth?

OAuth is an open security protocol designed to protect system and user credentials in client applications. Prior to implementing OAuth, the API required client applications to provide both client and user credentials. The Getty Images API authenticated the credentials and then granted access to the API and user functionality such as search, download, and lightbox management. OAuth allows users to authorize a client application to access user functionality without requiring the client application to directly handle the user’s credentials. Thus OAuth improves security by reducing the exposure of end user credentials.

Do I Need Getty Images User Credentials?

If you have been working with one of our account managers on a business-to-business licensing agreement, you are more than likely using the Resource Owner and Password flow. Note that you must specify GettyImages.com or iStockPhoto.com user credentials in the call to retrieve access tokens. If you are unsure about these credentials, please contact your account manager.

Important Terminology

Before we dive into the details of the OAuth 2.0 authorization workflows, let’s make sure we’re using a common vocabulary:

Term Definition Example (if applicable)
Resource Owner The end user who has access to a set of resources. A Getty Images or iStock end user.
Protected Resource Resource, stored on or provided by a server, that requires authorization to access it. Images, videos, lightboxes
Authorization Server Entity that protects resources and validates credentials before authorizing a client application to take any action on behalf of an end user (such as search, lightbox, or download). Getty Images’ OAuth server
Client Application Application using the Getty Images API. Getty Images API client
Client Credentials API key and secret for the client application.
Access Token Token provided by the authorization server to the client application to authorize access to resources.
Token Revocation Means of revoking an access token. Getty Images or a user can revoke an access token if suspicious activity is detected.
Client Type A client type is assigned to a client application based on their ability to authenticate securely with the authorization server. Public or confidential (see the OAuth 2.0 RFC for more info)

Authorization Grant Types

Summarized below are the four authorization grant flows in OAuth 2.0.

Authorization Grant Client Environment Entities Required
Authorization Code Web application with a server-side component which can secure the API secret API key and secret, User ID and password
Implicit Grant Client-side application, where the application cannot secure the API secret API key, User ID and password
Resource Owner Password Credentials Resource owner has high degree of trust with the client application. API key and secret, User ID and password
Client Credentials Client application is also the resource owner. API key and secret

Authorization Code Grant

Summary

Getty Images requires use of the authorization code grant for third-party web applications that have client and server components, or mobile applications.

  1. Client application makes a GET request to the authorization endpoint at https://api.gettyimages.com/oauth2/auth passing the following information:

    • Client ID: API key.
    • Response type: authorization_code.
    • Redirect URI: URI that has been registered with the Getty Images API to receive the authorization code. Parameters may be added that are not registered.
    • State: Optional state data which will be passed back to the client in the final redirect
  2. Client application is redirected to the Getty Images sign-in page.

  3. End user signs in with their Getty Images or iStock credentials and clicks Authorize.
  4. Client is redirected back to the redirect URI with the authorization code in the query string.
  5. Application makes a POST request to the token endpoint (https://api.gettyimages.com/oauth2/token):
    • Content type: application/x-www-form-urlencoded
    • Grant type: _authorizationcode
    • Code: The authorization code received from, the Getty Images authorization server.
    • Redirect URI: The redirect URI that was used to make the initial request.
    • Client ID: API key.
    • Client secret: Required only if the client type is confidential. If the client type is public, sending this parameter will cause the request to fail. Mobile applications should not use client secret as it could be exposed to an attacker.
  6. Getty Images authorization server responds with the token response:
    • Access token: The access token to be used to authorize other API calls.
    • Token type: Bearer.
    • Expiration time: Number of seconds until the access token expires.
    • Refresh token: A token which can be used to refresh the access token. Used with the refresh token grant instead of prompting the end-user for their credentials repeatedly.

Find more information about the authorization code grant at the OAuth 2.0 RFC

Example Authorization Code Request

GET https://api.gettyimages.com/oauth2/auth?client_id=abc123&response_type=authorization_code&state=datasentfromclient&redirect_uri=https%3A%2F%2Fyourhost%2Fauthreceiver HTTP/1.1
Host: api.gettyimages.com

Example Authorization Code Response

HTTP/1.1 302 Found
Location: https://yourhost/authreceiver?code=def456&state=datasentfromclient

Example Access Token Request

POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=abc123&client_secret=yoursecret&redirect_uri=https%3A%2F%2Fyourhost%2Fauthreceiver&code=def456

Example Access Token Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "accesstokendata",
    "token_type": "Bearer",
    "expires_in": 1800,
    "refresh_token": "refreshtokendata"
}

Token Expiration and Revocation

Tokens issued by the authorization code grant are valid for at most 30 minutes. Be sure to check the expires_in property of the response to determine when the access token actually expires. If the client application needs to access content for the user longer that 30 minutes, it can use the refresh token to get a new access token that will also be valid for 30 minutes. The refresh token is valid for one year and can be used as many times as needed within that one year to get a new access token. The refresh token cannot be used for API access.

Implicit Grant

Summary

Getty Images requires the use of the implicit grant for third-party web-based client applications without a server-side component. In this flow, the user authorizes the application to access their protected resources using the Getty Images authorization server. Developers follow these steps to get an access token for their application:

  1. Client application makes a *GET request to the authorization endpoint at https://api.gettyimages.com/oauth2/auth and passes in the following information:

    • Client ID: API key.
    • Response type: token.
    • Redirect URI: URI that has been registered with the Getty Images API to receive the access token. Parameters may be added that are not registered.
    • State: Optional state data which will be passed back to the client in the final redirect
  2. Client application is redirected to the Getty Images sign-in page.
  3. End user signs in with their Getty Images or iStock credentials, and clicks Authorize.
  4. If authorization is successful, client is redirected back to the redirect URI with the token in the query string.

Find more information about the implicit grant at the OAuth 2.0 RFC

Example request:

GET https://api.gettyimages.com/oauth2/auth/?response_type=token&client_id=abc123&state=datasentfromclient&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: api.gettyimages.com

Example response:

HTTP/1.1 302 Found
Location: https://client.example.com/cb#access_token=accesstokendata&state=xyz&token_type=bearer

Token Expiration and Revocation

Tokens issued by the implicit grant are long-lived, i.e., their expiration time is longer than 30 minutes (usually one year). Some resources require a token that has been issued within a certain time period. For instance, search functionality accepts any unexpired token whereas download functionality requires a token to be issued within the last 30 days.

Once an access token is no longer valid (has expired) for a given resource, a new access token must be retrieved to access that resource. The implicit grant does not support access token refresh. A new access token must be requested once it expires.

Access tokens will be revoked when the user changes their password. Revoked tokens cannot be used for any API access.

Resource Owner Grant

Summary

The resource owner grant is available to Getty Images partner applications capable of protecting the client secret and the user's credentials. Used when the client application and user accounts are owned by the same organization.

  1. Client application makes a POST request to the token endpoint passing the following information:

    • Grant type: password.
    • User name: user's login ID.
    • Password: user's password.
    • Client ID: API key.
    • Client secret: API secret.
  2. Client receives the following response:

    • Access token: The access token to be used to authorize other API calls.
    • Token type: Bearer.
    • Expiration time: Number of seconds until the access token expires.
    • Refresh token: A token which can be used to refresh the access token. Used with the refresh token grant instead of prompting the end-user for their credentials repeatedly.
Example Resource Owner Request
POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

client_id=abc123&client_secret=yoursecret&grant_type=password&username=usersloginid&password=userspassword
Example Resource Owner Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
        "access_token":"accesstokendata",
        "token_type":"Bearer",
        "expires_in":1800,
        "refresh_token":"refreshtokendata"
}
Example Refresh Token Request
POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=abc123&client_secret=yoursecret&refresh_token=refreshtokendata

Token Expiration and Revocation

Tokens issued by the resource owner grant are valid for at most 30 minutes. Be sure to check the expires_in property of the response to determine when the access token actually expires. If the client application needs to access content for the user longer that 30 minutes, it can use the refresh token to get a new access token that will also be valid for 30 minutes. The refresh token is valid for one year and can be used as many times as needed within that one year to get a new access token. The refresh token cannot be used for API access.

Refresh tokens can be revoked when the user changes their password. Revoked tokens cannot be used for any API access.

Find more information about the resource owner grant at the OAuth 2.0 RFC

Client Credentials Grant

Summary

http://tools.ietf.org/html/rfc6749#section-4.4
Client Credentials flow is for client applications that will not have individual users. An application token is created and limits the client application to operations that do not need user credentials. A Sandbox application (for trial development and without a licensing agreement) can only use Client Credential flow.

  1. Client application calls the token endpoint with the following information in the request:

    • Grant type: client_credentials.
    • Client ID: API key.
    • Client secret: Api secret.
  2. Client receives the following response:

    • Access token: The access token to be used to authorize other API calls.
    • Token type: Bearer.
    • Expiration time: Number of seconds until the access token expires.
Example request:
POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

client_id=abc123&client_secret=yoursecret&grant_type=client_credentials
Example response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
        "access_token":"accesstokendata",
        "token_type":"Bearer",
        "expires_in":1800,
}

Token Expiration and Revocation

Tokens issued by the client credentials grant are good for at most 30 minutes. Be sure to check the expires_in property of the response to determine when the access token actually expires. Once the access token has expired, a request for a new access token is required.

Find more information about client credentials grant at the OAuth 2.0 RFC

References

OAuth 2.0 Specification