Access Tokens

Summary: Outlines how Access Tokens are used as well as some limitations and security considerations.

Summary

As part of the OpenID Connect and Open Authorization (OAuth) 2.0 flows, access tokens are provided by ADP and used for secure calls to protect ADP Web application programming interfaces (APIs). This article outlines how access tokens are used as well as some limitations and security considerations.

About Access Tokens

An access token is a time-bound token, or credential, used for accessing protected ADP Web APIs. They are restricted to an access scope. ADP provides access tokens to your application as part of the OpenID Connect and OAuth 2.0 authentication and authorization flow.

How to Use an Access Token

After your application obtains an access token, it can be used to request multiple Web APIs for as long as the access token is valid.

Your application must follow these guidelines to request a protected Web API:

  • Use the Transport Client Authentication in all Web API requests with the X.5090 certificate provided during the registration of your application. For example, mutual Secure Sockets Layer (SSL)/Transport Layer Security (TLS).
  • Use the HTTP Authorization header with the Bearer authentication scheme and a valid access token.

The following is an example of a Web API request with a bearer token:

GET /hr/v1/workers HTTP/ 1.1 Host : api.adp.com Authorization : Bearer 024ded5f831d4483a9c606710026b09b

Your application must be able to process the errors as defined in the Internet Engineering Taskforce (IETF) Request for Comment (RFC) 6750. Your application must be able to handle the errors in the following table.

HTTP Status

Error Code

Description

400 Bad Request

invalid_request

Specifies that the Web API request is missing a required parameter or includes an invalid or distorted parameter value.

401 Unauthorized

invalid_token

Indicates the Web API request contained an expired, revoked, or invalid access token. Additional information about the error might be provided in the WWW-Authenticate header.

403 Forbidden

insufficient_scope

Specifies that the Web API request requires higher privileges than provided by the access token.

500 Internal Server Error

 

Indicates the Web API cannot be processed due to a runtime error.

503 Service Unavailable

 

Indicates the Web API cannot be processed because the service is unavailable.

The following is an example of an error:

HTTP/ 1.1 401 Unauthorized WWW- Authenticate : Bearer realm="oauth", error="invalid_token", error_description=" Access token expired"

For other errors, the authorization server might provide the error code and error_description in the body as a JavaScript Object Notation (JSON) object.

The following is another example of an error:

HTTP/ 1.1 403 Forbidden Content - Type : application/json;charset=UTF- 8 { "error":"insufficient_scope", "error_description":" Unauthorized Web API"

For other errors, the authorization server might provide the error code and error_description in the body as a JSON object. 

ADP Web API Limitations

For security reasons, ADP places limits on the usage of access tokens and Web APIs.

You may want to consider the following limitations in your application:

  • Access tokens are tied to your application. You cannot use one access token in another application.
  • Access tokens may be tied to the computing environment used by your application during the authorization process. For example, restricted to a certain IP address. Access might not be allowed from a different computing environment.
  • Access tokens have a short life span. By default, access tokens expire in 60 minutes. If your application and security requirements require a smaller expiration time, indicate your requirements during application registration.

Your application should limit access to under 300 times in a 60 second period, with no more than 50 concurrent requests in any time. ADP will throttle your requests when this limit is exceeded. Then, return a response of HTTP 429 for too many requests. 

Since tokens do not expire within 60 minutes, your application should only request a different token when the current one is about to expire. Do not call a new token for every API request.

If your application and security requirements require a different setting, indicate your requirements during application registration.

Security Considerations

ADP recommends your organization consider keeping application credentials under strict control to prevent leakage and misuse . This includes the following:

  • Account identifier
  • Account secret
  • X.509 certificate

Your application should never store or pass access tokens in cookies or parameters. They are transient and stored temporarily in your application's memory.

You should do the following:

  • Discard access tokens when your application finishes its processing with ADP.
  • Consider limiting the access scope requested in authorization requests. This limits the capabilities associated with access tokens produced by these authorization requests.  

Known Issues and Limitations

Issue #1: Wrong Response Code for an Invalid/Expired Token Call)

Currently, an invalid/expired token triggers an HTTP 400 response which states an invalid_request.