You are here: Photobucket API Help > Getting Started > End-User Authentication > Web Authentication

Web Authentication

Requirements

To implement End-User authentication, you must:

Read, understand, and implement the Photobucket Consumer Authentication requirements.
Have the ability to show End-Users an external web page (HTML, CSS, Javascript).

As well, End-Users must be able to accept cookies.

If you cannot meet these requirements, please contact Photobucket to request alternatives. Or, if you are a partner, you can use the Direct Authentication method.

Condensed Procedure

The following web authentication procedure is the condensed version.

Note: The web authentication procedure outlined here is the greatly preferred method of authenticating users.

Get a Login Request token by an HTTP POST to http://api.photobucket.com/login/request.

Receive an oauth_token and oauth_token_secret: oauth_token=<token>&oauth_token_secret=<token_secret>

You may also receive extra information in this response, formatted in the same way. next_step=<url> contains the URL of the next step of the End-User Login page for your convenience.

Direct the End-User to Login page at: http://photobucket.com/apilogin/login?oauth_token=<token>.

End-User logs in.

End-User authorizes your application.

End-User is directed back to your application.

Receive a "ready" response from Photobucket in the callback redirect: <callback>oauth_token=<token>&username=<user>&subdomain=<api###.photobucket.com>
Get a User Access token by an HTTP POST to: http://api.photobucket.com/login/access?oauth_token=<token>&<oauth_parameters>

Receive a oauth_token and oauth_token_secret: oauth_token=<token>&oauth_token_secret=<token_secret>

You may also receive extra information in the response, formatted the same way.
username=username contains the user who logged in.
subdomain=api###.photobucket.com contains the sub-domain that is required to access the logged in user’s media.
homeurl=url contains the url of the logged in user’s photo album.

See the method Web User Login for details.

Procedure

End-User web authentication happens in essentially four parts, per OAuth Section 6:

Consumer gets a Request Token.
Consumer directs End-User to User Login/Authorization site on Photobucket.
Photobucket directs End-User back to Consumer, to notify that Login/Authorization is complete.
Consumer gets a User Access Token by providing the now authorized Request Token.

Notes:

Request tokens DO expire if any of the steps take too long. If a Request token expires, the procedure can stall. The expiration date is refreshed at each step. So as long as activity occurs, the Request token should not expire.

Remember to sign the User Access Token method as you might a user request, but with the request token and request token secret.

Information sent to the End-User login from the Consumer is available to the End User - do not put too much information here.

See the method Web User Login for details.

1. Consumer gets a Request token.

The Request Token is an unauthorized token that can only be used to request an access token after it has been authorized. See Requesting a Page Anonymously for details about the Request Token signing procedure.

Use the Photobucket API libraries that are provided, and issue a "login request".
Use another OAuth request library and issue a POST to"/login/request". (There are a few available from OAuth.net's repository).

The response from either of the preceding login requests contains an oauth_token (<token>) and an oauth_token_secret (<token_secret>), in the text format "oauth_token=<token>&oauth_token_secret=<token_secret>", as specified in the OAuth spec.

This token and token secret are used in the login and access requests. The response also contains next_step, which is the URL to the Login page for the user.

2. Consumer directs End-User to user login and authorization on Photobucket.

The End-User must be directed to Photobucket to continue the login process and authorize the request token. Typically, a Consumer site redirects the End-User to the Photobucket API Login and Authorization page at: http://photobucket.com/apilogin/login.

Requests to this page are NOT signed via the OAuth signature methods.

The Photobucket API Login and Authorization page requires the oauth_token parameter, and allows the extra parameter:

oauth_token (required) - The token gathered from step 1: "Consumer gets a request token".
extra (optional) - Use this parameter to store a session ID, etc., in case the Consumer needs it after the login is complete. The values for extra are limited to the characters [a-zA-Z0-9_+%-] (word characters, numbers, and urlencoded values). The extra parameter is not otherwise modified by Photobucket and is passed back to the Consumer as-is.

The redirect therefore is minimally:

http://photobucket.com/apilogin/login?oauth_token=<token>

Login Page

The End-User is presented an HTML web page that contains inputs for their login name and password, and a checkbox to remember their login between browser sessions. On submit:

If the login is successful, a cookie is issued to the End-User that represents their login on Photobucket, and the End-User is directed to the API authorization page.
If the login is not successful, the End-User is presented the login page again.

Authorization Page

After successfully logging in, the End-User is presented with an HTML web page that has button option to "Accept" or "Deny" your application from accessing their account. On submit:

If "Accept" is selected, the request token is signed and the End-User is redirected back to the Consumer via the Consumer’s pre-set callback URL. Proceed to step 3 and the Callback section.
If "Deny" is selected, the request token is NOT signed. The End-User is redirected back to the Consumer via the Consumer's pre-set callback URL. Proceed to step 3 and the Callback section.

Regardless of whether the End-User selects "Accept" or "Deny", if a callback was not set, the End-User is directed to a "Finish" page. Proceed to step 3 and the Login Complete Page section.

3. Photobucket directs End-User back to Consumer.

Callback

After the End-User has completed the authorization, the End-User is redirected to the Consumer via the pre-set callback URL. The callback URL is appended with these parameters:

oauth_request - Request token that started the chain of authorization.
status - Status of the callback:
- ready - The request token is authorized and ready.
- denied - The request token is not signed because the End-User denied access to their account on the Authorization page.
- canceled - The request token is not signed because the End-User canceled the login process on the Login page.
extra - Optional parameter provided at the beginning of the login/authorization process. It is sent back as-is.

The Consumer is expected to use the callback URL parameters to continue the login process.

Login Complete Page

If a callback URL was not set by the Consumer, an HTML page that states the process is complete is shown.

If the End-User allowed the Consumer to access their account, the Login Complete page contains the request token used during the login process. If the application requires it, the End-User can use those items to continue the login process.
If the End-User canceled the process or denied access, the Login Complete page is the end of the process.

4. Consumer gets an authorized User Access token.

The User Access token is used for all other user-authorized requests. See Requesting a Page as a Logged-in User as that is the same signing procedure for getting an access token from a request token. Only the Get User Access token method takes both the Request token <token> and the Request token secret <token_secret>.

Use provided Photobucket API libraries and issue an "access request" command, providing the <token> and <token_secret> to the method.
Use another OAuth request library, and issue a POST to "/login/access", providing the <token> and <token_secret> to the method.

The response from either of these contains an oauth_token <token> and an oauth_token_secret <token_secret>, in the text format 'oauth_token=<token>&oauth_token_secret=<token_secret>' as specified in the OAuth spec.

This User Access token and User Access token secret are used in all subsequent requests requiring a user login.

The following addition information is supplied:

Username – Username of the user who logged in.
Subdomain – API sub-domain that contains the user’s media.
Homeurl = URL of the user’s home directory (this is an HTML page).

Published 25-June-10. See developer.photobucket.com for additional resources.